Session File (session.txt)¶
session.txt at the repo root holds the one task currently in flight, so a new session (or /task-resume) can pick it up. It is committed and pushed, so a session on another machine knows where work stopped after git pull. Durable status still goes to TASKS.md and docs/tracking.md. Whenever the file is non-empty, the SessionStart hook shows the user a status report from it at every startup. Unfinished tasks also get a "/task-resume" hint, and done tasks are shown as the last task, so keep the fields short and current: what it shows is exactly what is written here.
Format¶
Plain key: value lines, one per key, no nesting:
task: Continue Watching row (Explore)
status: in_progress
progress: 40
done: FE-1 selector; FE-4 summary invalidation
doing: FE-2 ContinueWatchingRow component
next: FE-2 ContinueWatchingRow component + styles
plan: docs/plans/plan-continue-watching.md
updated: 2026-10-18 21:05
status:in_progress|blocked|doneprogress: integer 0–100, your honest estimate of the whole task (not the current step)done: one;-item per finished subtask, written as<ID> <what> <commit>, e.g.BE-1 position column 6a0a5849. The startup report shows each item as a✅line, at most 8 items and 70 characters each, so keep every item shortdoing: subtasks started but not finished (matching[~]inTASKS.md), same item format asdone, shown as🔄lines. Optional: leave it out or set it to-when nothing is half-done. When a subtask finishes, move it fromdoingtodonenext: short,;-separated, concrete enough to act on without the conversation. Only the first item shows in the startup reportplan: artifact path, or-when there is noneupdated: local date and time asYYYY-MM-DD HH:MM(24h, e.g.2026-10-18 21:05), never the date alone; get it fromdate "+%Y-%m-%d %H:%M"blockedadds ablocker:line saying what is needed and from whom
When to Write It¶
- Start of any task with 3+ steps or one that will likely outlive the context window: create or overwrite the file
- After each step (task in a plan, commit, verified checkpoint): update
progress,done,next,updated - Blocked or waiting on the user:
status: blocked+blocker: - Finished (pushed, verified):
status: done,progress: 100
Skip it for one-shot questions and trivial edits. Write it with a single Write call (overwrite), never append. Never put secrets, tokens, hostnames/IPs, key paths or customer data in it: it is pushed to the remote.
Syncing Across Machines¶
- Commit
session.txttogether with the work it describes. A status-only update gets its ownchore(session): …commit. Pushing still needs the user's go-ahead, like every push. - Before stopping work on a machine, make sure the latest
session.txtis committed, so the nextgit pullelsewhere brings it along. - On a new machine,
git pullfirst; the SessionStart hook only sees the local copy.