Melech Handoff

Melech Handoff

Find and resume coding-agent sessions without putting handoff files in the repository or making the user copy transcript paths between chats.

Two modes only: list and cont. The script only discovers, lists, and looks up transcripts. The agent does the intelligent retrieval.

/melech-handoff
/melech-handoff list
/melech-handoff cont [session-id-prefix | objective]

Resolve the mode from the invocation. Do not ask which mode they want.

• Bare /melech-handoff or /melech-handoff list → list
• /melech-handoff plus a session id / unique id prefix → cont
• /melech-handoff cont … → cont

Set HANDOFF_SCRIPT to scripts/handoff.py beside this file. Run it with Python 3.9 or newer. Treat its JSON output as the source of truth; do not recreate transcript discovery with an unbounded home-directory search.

List

Run:

python3 "$HANDOFF_SCRIPT" list --cwd "$PWD" --limit 12

Show the rows newest first as compact Markdown cards. Do not use a table: CLI table renderers crush the metadata columns and cannot display multiline glimpses. Use the script fields; do not invent dates, agents, worktrees, or counts.

### `` · 
 · 
`` ·  user msgs · ~ tokens

1. 
2. 
3. 

age is the compact time since the transcript was last written, such as 8m ago, 3h ago, or 2d ago; this is the only timestamp shown because the list is ordered by recent activity. Exact created and modified values remain in the script output for lookup or debugging. worktree is main for the repository's main worktree and otherwise the worktree directory name. stats.approx_tokens is a cheap chars / 4 estimate, not a tokenizer result. topic is a short hint derived from the first meaningful human request. glimpse contains up to the three latest human user messages as real numbered lines. Preserve the newlines when rendering the card; do not duplicate messages when fewer than three exist. Each message may use up to 160 characters. Do not remove the cap because individual transcript turns can be thousands of characters. Tool results and metadata-only user records are ignored.

list is read-only. Show enough information for the user to invoke /melech-handoff cont , then stop. Do not start working or read full transcripts.

Continue

If the argument begins with a session ID or unique ID prefix, run:

python3 "$HANDOFF_SCRIPT" lookup --cwd "$PWD" --id ""

Any remaining text is the continuation objective.

If there is no ID, run list without a query. The script does not pretend to understand the objective. Choose distinctive terms from the objective and search only the returned primary_transcript_path files with rg.

• One clear transcript match: run lookup on its id, then continue.
• Several plausible matches: use one combined AskQuestion picker with the

matching candidates. After the pick, run lookup.

• No argument: show the five newest rows in one combined AskQuestion picker.

Each option starts with · · · , followed by worktree, stats, and the three-line glimpse. If undisplayed rows remain, append an Older sessions… option that opens the next five rows using the same layout. Do not add multiple questions to one picker because that requires one answer per question.

• If the user selects the picker's automatic Other option and enters text,

treat that text as the continuation objective and relevance query. Search the returned primary_transcript_path candidates for distinctive terms, independent of recency. Continue a single clear match; otherwise show one refreshed picker containing only the strongest relevant candidates.

• After a session is picked, run lookup.
• No match among the listed candidates: say so. Do not broaden into an

unbounded home-directory scan.

lookup returns primary_transcript_path, the text file to consult. If anything about the task or current state is unclear, search that transcript for relevant keywords such as task names, filenames, IDs, errors, and tool names. Then read a small window around matching lines to reconstruct intent and state. Avoid reading linearly end-to-end: JSONL transcripts can be large and individual lines can contain large payloads.

Use the continuation objective to decide what context is relevant. The agent, not the Python script, makes that judgment.

Do not write a card and do not invent a long recap. Follow retrieval constraints in the objective, such as “don’t read all.”

Continue the work directly once the target is clear. Do not ask whether the user wants you to proceed.

Boundaries

• Do not write files under ~/.melech/handoffs/. List and continue from

transcripts only.

• Scope defaults to the current worktree root, not sibling worktrees.
• Provider locations come only from references/providers.json.
• Database, encrypted, protobuf-only, and compressed-only histories are

recorded but unsupported.

• Transcript and handoff contents are private local history. Never publish,

upload, or paste them externally without explicit user instruction.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AdirD
• Source: AdirD/agent-shell-hamelech
• License: MIT

Install and usage instructions live in the source repository linked above.