Claude Code project management between sessions

A new app idea moves fast in Claude Code, Cursor or Codex: the agent writes code in minutes. After a few sessions, the fast part becomes a problem. Nobody, not you and not the agent, remembers what is done, what is half done, and what got decided along the way. A new session sees the code, not the decisions behind it, because the conversation where they were made belonged to an earlier session. The plan lives in a markdown file that stopped matching reality around session three, or in a chat from yesterday, gone along with the session it happened in.

The fix is a board outside the session that the agent reads when it starts and writes when it stops, with the card key from that board sitting in the commit the session produces. You, and anyone you show the project to, see where it stands without reading the commits.

The plan lives outside the chat

Put the plan on a board and the session itself becomes replaceable. Each session starts by reading a card: what it is for, and what the status block at the end of its description says has already happened. It ends by rewriting that same block, instead of hoping the next session remembers. The card key goes into the commit, so the code and the plan point at each other without you doing that by hand, and a quick look at the board tells you what a full git log would take longer to piece together. This is what people mean by Claude Code memory between sessions, kept as a board it reads and writes from outside the tool.

This is not the same as an agent operating a team's board, which is what Kanban board for AI agents covers. Here there is usually one board and one or two people, and the state of the project needs to exist somewhere the next session, and the next person, can actually read.

How to organize a Claude Code project in five steps

1. Create a workspace. New ones get a 14-day trial of whichever plan you pick, no credit card, and run on servers in Germany.
2. Create an API token with the scopes the agent needs: boards:read and cards:read to read the board and its cards, cards:write to update and move them, comments:write to leave a note, and git:write for the commit hook in step 4. This needs the Developer plan, the same one the MCP server and the CLI need.
3. Add the MCP server in Claude Code:

   claude mcp add zuuna \
     -e ZUUNA_API_TOKEN=zk_live_your_token \
     -- npx -y mcp-server-zuuna

   Using Cursor or Codex instead? Setup for both is on Zuuna for AI agents.
4. Install the commit hook, so a card key in a commit subject links the work automatically:

   curl -o zuuna https://app.zuuna.de/zuuna.sh
   chmod +x zuuna
   ./zuuna init https://app.zuuna.de zk_live_your_token

   More on the hook in the CLI reference.
5. Add a few lines to the project's CLAUDE.md, so the agent follows the same routine every session without being told again.

What goes in CLAUDE.md

## Zuuna board
- At the start of a session, read the board with `zuuna_board`, then the card in play with `zuuna_card`: the top one in "Next", or the one already in "In progress". Its description ends with a status block: Done / Open / Decided.
- Work only on that card. If none is in "Next" or "In progress", ask before starting anything new.
- Put the card key in the commit subject line, e.g. `APP-12: add password reset`.
- At the end of the session, rewrite the status block with `zuuna_update_card`: what got done, what's still open, what got decided and why.
- Optionally add a comment with `zuuna_comment` for people reading the card later; the next session does not read comments.
- Move the card to "Review" with `zuuna_move_card` when it's ready to look at.

The status block matters most: a description that says what is still open is what makes the next session useful instead of a guess, since the agent reads the card's description over MCP but not its comments. Moving the card to Review is what a person, including future you, checks before it counts as done; moving it on to Done from there is yours, the agent stops at Review.

A commit links the card, a rule moves it

The hook reports every commit, but a card key in the subject line or the branch name only links the commit to the card, it does not move it. Moving the card, from Next to In progress for instance, needs a rule you add once under the board's Automations settings: commit linked, then move to In progress, with the option that only lets it move forward. No rule comes preinstalled. It is a few clicks the first time, then the board updates itself on every commit that carries a card key. If the project lives on GitHub, GitLab, Gitea or Forgejo, you can connect the repository directly instead, so a pull request opening or merging, or CI passing or failing, can trigger rules too, not just the commit hook.

When a TODO.md file is still enough

None of this is worth setting up for a weekend project nobody else will see. A TODO.md file next to the code, updated by the agent at the end of a session, does the same job at a much smaller cost: no token, no scopes, no board to check. The point of a board is that more than one memory needs to agree on the state of a project, yours across sessions, or yours and someone else's. If that is not true yet, the plain file is the right amount of process. The moment it stops being enough is usually obvious: a second person starts reading the code, or you catch yourself re-deciding something that was already settled two sessions ago.