// Blog / team workflow

Agent handoff between coding sessions without losing repo context

A useful handoff is not a chat recap. It is a repo-local pointer to what changed, what is trusted, and what must be rechecked.

technical blog Session handoff workflow Published May 25, 2026 Updated May 25, 2026

Open GitHub Read comparison

// direct answer

Short answer

Handoff works when the repository stores a starting point for the next session: Routing Bundle, handoff summary, confidence report, unresolved follow-up work, changed files, and current source. Treat the session summary as a reference until current code confirms it.

Move work from one coding-agent session to another without losing repo context or trust warnings.

// the problem

Chat summaries lose important context between sessions

A session ends with useful context in the agent's answer, but none of it is durable or easy to verify.

The next session starts cold, misses a warning, or repeats the same investigation.

The team thinks it handed off work, but it only handed off prose.

// repository handoff

Leave the next session a file-backed starting point

A handoff should point to files, trust state, changed areas, and repair items.

The handoff summary is useful only when it routes the next agent to source, tests, and evidence.

After meaningful work, rebuild routing and search so the next session sees the current map.

// concrete example

A safe session restart

The first agent updates docs and finds stale module context, but does not finish repair.

Fallback if handoff_summary.json does not exist yet: use routing_bundle.json + pr_summary.md + repair_queue.json, then re-read current source before continuing.

Mini handoff template: Changed: __. Verified: __. Needs re-check: __. Next source files: __. Tests: __.

Before ending, it refreshes the Routing Bundle and leaves a handoff summary that points to the outdated module and unresolved follow-up item.

The next agent reads those files and rechecks source before continuing instead of trusting the prior conversation.

// files you can inspect

Files for the next coding-agent session

Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.

Handoff summary OPTIONAL OUTPUT

`.knowledge/maintenance/handoff_summary.json`

The next agent needs a compact continuation point with routes, risks, and pending work.

Use it for

Session continuation
Finding recent context

Do not use it for

Skipping source recheck
Treating chat recap as truth

Append-only events CREATED AFTER A HEALTH CHECK

`.knowledge/maintenance/events/`

Events preserve maintenance actions across sessions.

Events live under .knowledge/maintenance/events/YYYY-MM-DD.ndjson.

Use it for

Understanding recent maintenance
Auditing changes to knowledge state

Do not use it for

Replacing git history

Open repair work CREATED AFTER A HEALTH CHECK

`.knowledge/maintenance/repair_queue.json`

Unfinished uncertainty should be visible to the next agent.

Use it for

Picking up incomplete work
Prioritizing rechecks

Do not use it for

Blocking unrelated edits

Current route CREATED DURING SETUP

`.knowledge/maintenance/routing_bundle.json`

The next session should start from the current route, not a stale conversation.

Use it for

First read
Finding module boundaries

Do not use it for

Behavior proof

// commands to try

Commands and expected checks

node .knowledge/tools/flow.js release --no-color

what it does: The handoff refresh rebuilds routing, trust, freshness, search, PR summary, and Inspector outputs.
where to look: .knowledge/maintenance/pr_summary.md and .knowledge/maintenance/routing_bundle.json

node .knowledge/tools/build-routing-bundle.js

what it does: The compact routing file is current for the next session.
where to look: .knowledge/maintenance/routing_bundle.json

node .knowledge/tools/build-search-index.js

what it does: Local search reflects current repository context.
where to look: .knowledge/search/index.json

node .knowledge/tools/doctor.js

what it does: The next agent sees whether it should use caution.
where to look: .knowledge/maintenance/quality_report.json

Handoff timeline files and checks

From one session to the next

01 Session A changes or investigates a module.

02 Knowledge maintenance refreshes route, search, trust, and handoff state.

03 The follow-up list captures unresolved uncertainty.

04 Session B starts from repo-local files and rechecks source as needed.

// practical reference

Handoff files

A handoff should leave inspectable files, not just a friendly summary.
File	Carries	Next agent should
Handoff summary	Recent context and warnings.	Use it to choose what to inspect.
Routing bundle	Current first-read map.	Open target source and tests.
Items to re-check	Unresolved or outdated context.	Verify, assign, or document.
Events	Maintenance actions.	Audit what changed since last session.

// quick FAQ

FAQ

Is a chat summary still useful?

Yes, but it should point to repo-local context and current source files. It should not become the source of truth.

What should be refreshed before handoff?

At minimum, routing, search, and doctor status after meaningful knowledge or source changes.

// next step

Use this page before ending a coding-agent session

Refresh the repo-local route, make unresolved repair work visible, and make the next agent re-read source for risky behavior.

Read Claude vs Codex article Open GitHub Read freshness article