Hark

Claude Code handoff: Resume work, reset context, and brief the next person

7 November 2026·By Mike Schreiber·9 min readhandoff

A Claude Code handoff starts with choosing what needs to continue. To reopen your own local conversation, use claude --continue or claude --resume. To reduce context while continuing the task, use /compact. To begin a fresh conversation, use /clear. Claude Code saves the previous local session so it can be resumed. Claude Code session documentation

For another person or a different coding tool, prepare a reviewed handoff file alongside the relevant code. Keep durable project instructions in CLAUDE.md, which Claude reads at session start, rather than relying on conversation history or machine-local auto memory. Claude Code memory documentation

Choose the right handoff method

These mechanisms solve different problems:

| Your situation | Use | What it does | | --- | --- | --- | | Returning to your latest local task | claude --continue | Reopens the most recent eligible session in the current directory | | Returning to a particular conversation | claude --resume | Opens a session picker; a name or ID can select a session directly | | Continuing a long conversation | /compact [instructions] | Replaces conversation history with a summary | | Starting a fresh conversation | /clear | Starts with empty conversational context while keeping project memory | | Giving someone task-specific context | A handoff file | Provides an explicitly written, reviewable brief |

The command behavior above is documented in Claude Code’s session guide and command reference. A handoff file is a workflow convention, not a special built-in file type.

/compact is not a portable handoff

Use compaction when the current conversation remains useful but has become long. You can direct its focus:


/compact Preserve the goal, decisions, changed files, test results, unresolved risks, and next steps.

The optional instructions focus the summary. They do not turn it into a separately reviewed project document. When a compacted session resumes, Claude uses the latest summary, retained messages, and subsequent messages rather than reloading all summarized history. Session restoration and compaction

Project-root CLAUDE.md is reread after compaction. Nested instruction files and path-scoped rules load again on demand. Put standing instructions in project guidance rather than leaving them only in chat. What survives compaction

/clear is a reset, not a summary

Use /clear when you want a fresh conversation without carrying the current discussion forward. It does not create a handoff brief. In the CLI, the previous session remains available through /resume. Context-management commands

If the new conversation needs selected facts from the old one, write and review those facts before clearing. Then explicitly ask the new session to read the handoff file.

Create a handoff another session can use

A useful brief should let the recipient locate the work, verify its state, and choose the next safe action. It should not require reconstructing your entire conversation.

1. Identify the exact code state

Record the repository, branch, commit, and any uncommitted changes. Check the actual working tree instead of trusting a conversational summary:


git status --short

git branch --show-current

git rev-parse HEAD

git status --short gives the working-tree status in short format (git-status). git branch --show-current prints the name of the current branch, and prints nothing in detached HEAD state (git-branch). git rev-parse HEAD resolves HEAD, the commit the working tree is based on, to its object name (git-rev-parse).

A branch name alone is insufficient because its contents can change. A commit alone is also insufficient if important work remains uncommitted.

Before someone else starts, agree on how those changes will reach them. Use the project’s approved commit, pull-request, or patch workflow. A handoff document describes code state; it does not deliver missing files.

2. Ask for an evidence-based draft

Give Claude a bounded request:


Draft HANDOFF.md for a fresh session or teammate.

Include the objective, branch and commit, changed files,

completed work, decisions and reasons, verification results,

known failures, blockers, and ordered next steps.



Separate observed results from assumptions.

Mark anything not checked as unverified.

Do not include credentials, private chat excerpts, or client-sensitive

material that is unnecessary for the task.

Do not commit or publish the file.

Review the draft against the diff, issue, and available test output. In particular, distinguish “implemented” from “verified” and “verified locally” from “ready for production.”

3. Use a compact template

This example is a suggested structure, not an automatically loaded Claude Code format:


# Task handoff



## Objective

- Requested outcome:

- Acceptance criteria:

- Out of scope:



## Code state

- Repository:

- Branch:

- Commit:

- Uncommitted or untracked changes:

- Pull request or patch:



## Current status

- Completed:

- In progress:

- Blocked:



## Decisions

- Decision:

- Reason:

- Supporting issue or document:



## Verification

- Command or check:

- Result:

- Commit/environment checked:

- Not run, and why:



## Risks and open questions

- Known failure:

- Assumption requiring confirmation:

- Decision owner:



## Next actions

1. First concrete action:

2. Next verification step:

3. Review or approval needed:



## References

- Relevant files:

- Requirements:

- Shared project record:

Keep the brief task-specific. For example, “Run the payment retry test against the staging fixture” is more actionable than “finish testing.” Include the failure message or evidence link when it changes what the recipient should do next.

4. Test the receiving side

Start a fresh conversation and ask:


Read HANDOFF.md and the applicable project instructions.

Compare the brief with the current repository state.

Summarize the objective, verified status, blockers, and next action.

Flag contradictions or missing information before editing anything.

This is a practical acceptance check. If the recipient cannot identify the correct branch, explain a key decision, or distinguish passing checks from untested assumptions, revise the brief.

Keep project instructions separate from task status

CLAUDE.md is for context that should apply repeatedly: build commands, coding conventions, important constraints, and recurring workflow rules. Claude Code shares project-level instructions through source control when the file is committed. The documentation recommends concise, specific instructions and a target below 200 lines per file. Writing project instructions

HANDOFF.md is for changing task state: what happened, what remains, and where to continue. Avoid adding every temporary blocker or debugging attempt to permanent instructions.

Auto memory is another distinct mechanism. Claude writes notes it considers useful, but those notes are machine-local and are not automatically shared across machines or cloud environments. Do not assume a teammate receives them with a repository clone. Auto memory storage and scope

For portable repository guidance, AGENTS.md can help, but verify each tool’s discovery behavior. Claude Code’s documented native support depends on version and instruction-file configuration; its documentation also describes importing AGENTS.md from CLAUDE.md. Codex discovers AGENTS.md through its own instruction chain. Shared instructions do not imply shared conversation history. Claude Code instruction loading, Codex AGENTS.md documentation

Moving from cloud to terminal is a different handoff

If your task is already running in Claude Code’s cloud environment, use /teleport or claude --teleport to bring it into your terminal. Teleport checks the repository, fetches and checks out the session branch, and loads the conversation. It requires the same account, the correct repository, a clean working directory, and an available branch. Cloud-to-terminal handoff

This is session continuity, not a general transfer to another person or coding tool. The terminal receives its own copy; subsequent local work does not appear in the original cloud conversation. The documented CLI direction is cloud to terminal, not pushing an existing terminal conversation to the cloud. Terminal and cloud workflows

Close the cross-tool and cross-person gap

A technically complete repository handoff can still omit the project decisions behind the code. Another developer or client may need to know:

  • Which requirement was approved and by whom.
  • Why an alternative was rejected.
  • Which deliverables are accepted versus awaiting review.
  • Who owns a blocker or release decision.
  • Where the current supporting documents live.

Keep these facts in an agreed shared project record, then reference that record from the technical brief. Avoid maintaining conflicting copies of approval status in chat, a repository file, and a client document.

Hark keeps the accepted handoff and decisions in a project record, not a transcript dump. (Hark client handoff: a project record, not a transcript dump) The handoff page describes keeping the accepted handoff and accepted decisions in the project record and repository, with a session link only when its detail is useful. (Hark client handoff) Use that distinction when planning a handoff: share the accepted decisions and status the recipient needs, not an assumption that another assistant inherits your private conversation. For connection instructions, see connecting Hark with Claude Code. For the client-facing workflow, see client handoff.

Before sending a handoff, confirm the recipient can access its linked evidence. Remove secrets and unnecessary personal information, identify the next owner, and date the status summary. A useful handoff ends with an actionable next step, not merely a record of past activity.

FAQs

Is there a built-in /handoff command?

The official command reference does not list /handoff as a built-in command. A project may provide a custom skill with that name. Type / to inspect available commands, and distinguish custom workflows from built-in behavior. Command reference

Should I use /compact or /clear before handing off?

Use /compact to continue the current task with summarized context. Use /clear for a fresh conversation. For another person or tool, create and review a handoff file first; neither command substitutes for a portable brief. Session guide

Does CLAUDE.md preserve the whole conversation?

No. It supplies persistent written instructions, not a transcript. Saved sessions provide conversation continuity, while auto memory stores selected notes. Each serves a different purpose. Memory documentation

Can I export the conversation instead?

Yes. /export produces a readable plain-text conversation with messages and tool outputs. Review it for sensitive content before sharing. An export can provide supporting detail, but a concise brief is still useful for identifying current status and next actions. Export documentation

Sources

Mike Schreiber
Mike Schreiber

Founder of Hark. Builds with AI agents and the people around them.

XLinkedIn