crew-context

Files (1)

• SKILL.md

SKILL.md (first lines)

# Context and handoff

## One correction first

Claude Code cannot clear its own session, and neither can a shell script a hook
launches — hooks run as child processes of the session, and a child cannot reset
its parent's conversation. Anything promising otherwise is guessing.

`context.autoClear` (experimental, off by default) does not contradict that. It
does not clear the conversation; it drives the **terminal**, typing `/clear` at
the prompt the way a human would. Different mechanism, different failure mode —
it depends on knowing which terminal: only this session's own, bound through its
Claude Code session record (a headless `claude -p` child is told instead), with
`tmux` exact by pane id and the rest refusing without one window. See
`hooks/scripts/auto-clear.sh` and the crew README's Auto-clear section.

You do not need it to. The lifecycle already provides the whole cycle:

| Moment | Hook | What crew does |
|---|---|---|
| Approaching the limit | `Stop` | Estimate usage; ask for a handoff note before the turn ends |
| Auto-compaction about to run | `PreCompact` | Snapshot the transcript, write a skeleton handoff if none exists |
| After `/clear`, `/compact`, or resume | `SessionStart` | Print the handoff — its stdout is injected as context |
| Any session start, including plain `startup` | `SessionStart` | the context hook (`crew-context.sh`) injects branch/HEAD, code-map anchor state and a pointer to the handoff, so crew says something even on a fresh session, not only after a clear or compact |

So the flow is: crew tells you it is time, you type `/clear` or `/compact`, and
the next session opens already holding the handoff. The one manual step is the
`/clear` itself, which is the step that should stay manual anyway.

## Measuring usage

No hook input reports token count, but the JSONL transcript that hooks receive
as `transcript_path` does: every assistant turn carries `message.usage`, and
the last one is the real prompt size. `context-watch.sh` reads that (under Git
Bash on Windows) - see "How the reading is taken" below. `/context` should agree
with the watcher to within a turn; if it does not, the budget is wrong, not
the reading, and the warning prints both numbers so you can see which.

The watcher fires **once per threshold crossing per session**. It writes
`.crew/.handoff-requested-<session_id>` (the payload's `session_id`, reduced to
`[A-Za-z0-9_-]`) and stays quiet afterwards; that session's next `SessionStart`
clears it, and so does a measured reading back under the threshold. Without
that gate a `Stop` hook returning exit 2 will fire on every turn and trap the
session in a loop. It never blocks on a `stop_hook_active` continuation, but
that continuation is the turn it hands to auto-clear.

The claim is taken atomically - `set -o noclobber` in bash - so two `Stop` hooks
firing together cannot both pass a test-then-create and print the warning twice
(before L-0727 slice 3, native Windows ran a PowerShell flavour beside the bash
one).

**The marker is per session.** It used to be one file per repository, so two
terminals in one repo shared it: the first to cross the threshold silenced the
other, and either one's `SessionStart` re-armed both. It is now keyed on the
payload's `session_id`, and `SessionStart` clears only its own session's marker
(other sessions' markers age out after seven days).

The marker also records the reading that caused it, and whether that reading
can be trusted. Auto-clear (opt-in per machine; see
`docs/guides/crew/src/auto-cycle.md`) never clears on an estimate, an unknown
window, a pre-compaction reading, or an empty marker.

## The handoff note

Write it to `.work/HANDOFF.md`. Keep it short, and prefer **pointers over
narrative**:

```
# Handoff
written: <iso timestamp>
ticket: T-0042
branch: feature/export-timeout
head: a1b2c3d
resume: /crew:<command> <ticket>

## Done
- <what is actually committed or in the working tree>

## In flight
- file:line — what is half-finished and why

## Next action
<one sentence. The single next thing, concrete enough to just do.>

## Do not
- <dead end already tried, so the next session does not repeat it>

## Verify first
- <anything asserted above that the next session should re-check>
```

**The `resume:` line** is the one machine-readable line in the note. It names
the single next command, and `crew_resume.RESUME_COMMANDS`
(`plugin/crew/hooks/scripts/crew_resume.py`) is its only definition:
`/crew:spec`, `/crew:plan`, `/crew:implement`, `/crew:review` and `/crew:done`
each take one ticket id (`T-0042`); `/crew:autopilot` takes a ticket id,
`--goal <slug>` (lowercase letters, digits and `-`) or nothing; `/crew:status`
takes nothing. `resume: none` when no allowlisted command is next. Exactly one
`resume:` line, nothing after the argument: a second line, trailing text, an
unknown command, or an excluded one (`/crew:approve`, `/crew:brainstorm`,
`/crew:fix`, `/crew:emergency`, `/crew:gate`, `/crew:promote`,
`/crew:migrate`, `/crew:change`) is refused, never guessed at. When the
plugin ships autopilot, ask it first: `crew_autopilot.py handoff-resume --root .
[--ticket <id>]` prints the line to write (T-0056). A running goal's
`resume: /crew:autopilot --goal <slug>` wins over the next command; its
`resume: none` with `kind=unknown` means it could not tell which goal runs.
The note's `branch:` and `head:` bind the ticket form only: a `--goal` line is
judged by its goal file, and auto-resume takes it only while that goal is
`running` (L-0658), on any branch.

**Why pointers rather than a summary.** A session at 85% of its context is the
least reliable narrator of what it just did — that is precisely when detail has
been compacted away and recollection drifts. The diff, the ticket, and the test
output are all more trustworthy than the memory of them. A good handoff says
"look here," not "here is what happened."

Under 40 lines. If it is longer, the session was doing too many things at once,
and that is the real finding.

From mbadali25/useful-claude-add-ons, GPL-2.0.

More from mbadali25/useful-claude-add-ons