--- title: "Worklogs and continuity: Kotharo" version: v0.8.3 canonical: https://kotharo.com/docs/worklogs-and-continuity/ --- # Worklogs and continuity A Claude Code session forgets everything when it ends or is cleared, and loses detail when it compacts. Kotharo keeps a few small files so the next session starts where the last one stopped. ## The files All of them live in your home folder, outside the repo, keyed by repo and branch: | File | Holds | Written by | |---|---|---| | `~/.claude/sessions//.md` | The branch's worklog: dated entries of what was decided, ruled out and left in flight | `/kotharo:work-save`, and an empty one at the end of a turn if none exists | | `~/.claude/sessions//.state.md` | The branch's state: the current ticket, the plan, decisions, rejected approaches, open questions | `/kotharo:next-ticket` | | `~/.claude/sessions/_folders/.md` | A worklog for a folder outside any repo | `/kotharo:work-save` | | `~/.claude/sessions/.precompact/.md` | A snapshot taken just before the session compacts | The band, by itself | `` is the repo's folder, so every worktree of a repo shares one place, and each `/` in a branch name becomes `-`. ## At the start of a session Each new session, and each one after `/clear`, reads back: 1. The branch's state file, if there is one, as the ground truth for the plan, the decisions and the approaches already ruled out. 2. The newest whole entries of the branch's worklog, up to 150 lines and 4,000 characters, with a note naming the file when older entries are left out. 3. After a compaction, the snapshot taken just before it. So you don't have to explain again what you settled yesterday, and Claude doesn't propose an approach the worklog says was rejected. ## Save your place ``` /kotharo:work-save ``` It appends a dated entry of two to five sentences to the branch's worklog: what was decided or ruled out, and what is left. Facts that outlive the branch go to a memory file. Run it with Save notes beside the [context ring](https://kotharo.com/docs/context-line/), at the end of a day, or after any decision worth keeping. ## Pick up where you left off ``` /kotharo:work-resume ``` It reads the git state, open pull requests, the worklog and the tickets in flight, and tells you where things stand. Give it a topic or a ticket, such as `/kotharo:work-resume ABC-123`, and it searches your worklogs, memory and tickets for it. It changes nothing. ## Move to the next ticket ``` /kotharo:next-ticket ABC-124 ``` It closes out the current ticket before you start the next: it runs the tests, commits, rewrites the branch's state file with the plan, the decisions and why, the rejected approaches and the open questions, and then tells you to `/clear`. `/kotharo:next-ticket checkpoint` saves and commits without changing the ticket. It never pushes. When a prompt names a ticket other than the session's current one, the band adds a note suggesting `/kotharo:next-ticket` first. It never blocks. ## The snapshot before compaction Just before Claude Code compacts a session, the band writes a snapshot: the branch, the git status, the last 5 commits, your last few prompts and Claude's last reply, each cut short. After the compaction, the session reads it back, so the thread isn't lost. Snapshots stay in `~/.claude/sessions/.precompact/` until you delete them. ## The team's own records When the team works a ticket, it keeps its records in the repo, under `docs/work//`: - `handoff.md`, one dated line for each step, stop and answer, for clear tickets and new features; - the plan, the requirements, the design and the QA report, as the lane calls for them. The lane itself, with its stage and any stop waiting on you, survives `/clear` and a new session, so the band shows it again and the team carries on. `/kotharo:leave` clears it. At close-out, the team writes a record of the ticket to `~/.claude/kotharo/records//`. Next: [Work already under way](https://kotharo.com/docs/work-under-way/). [All docs](https://kotharo.com/docs/) Written for Kotharo v0.8.3.