Logs and disk space

You will find the log you need, read what an agent printed with kraft view logs, and free the disk space that worktrees take.

Before you start

• $KRAFT_HOME is ~/.kraft unless you set it; see Environment variables. The commands find run/ as Kraft does: $KRAFT_RUN_DIR when you set it, else run/ under $KRAFT_HOME.
• Deleting old session logs needs the server stopped. If Kraft runs as a service, stop it as Stop a service says.

Find the logs

All logs are in run/logs/:

• server.log is the server's own output: startup, shutdown and its reason, errors. A foreground kraft writes here as well as to the terminal. Kraft moves it to server.log.1 at start once it passes about 8 MB, replacing the last one.
• <session id>.log is one worker session: everything an agent or command printed. Kraft never deletes these.
• <session id>.times.jsonl holds when each line of that session's log was written, one JSON object per line: {"n": <line number>, "t": <timestamp>}. kraft view logs and the item page's log take a line's time from it when the line carries none of its own.

Read a session's log through Kraft rather than by file name:

A session's log is its output with stdout and stderr merged. Each line shows a time, a source and the text. The time is when Kraft saw the line, in UTC. It is --:--:-- for a session Kraft took over after a restart, and for a log from before Kraft recorded times.

The source is stdout for a plain line. A line of the agent's structured log is agent (what the agent says), tool (a tool call or its result) or sys (the session's own start and result lines):

09:30:15 sys    init claude-sonnet-5-5
09:30:17 agent  I'll start with the failing test.
09:30:18 tool   Read(tests/test_board.py)
09:30:21 stdout npm warn deprecated inflight@1.0.6

While the item is stopped, a bare kraft view logs ID shows the session that stopped it, and names the newest one, such as an auto-escalation, on stderr. With -f it follows the newest one instead, and names on stderr the session that stopped the item.

To list an item's session ids:

kraft view events ID --type worker_session_created --json

You know it worked when kraft view logs ID prints the lines the agent or command wrote. For the server's own log, read the end of run/logs/server.log.

Reclaim disk space

Each work item gets a git worktree in run/worktrees/<item id>/, a full checkout of its repo, plus any dependencies its setup command installed. That adds up.

1. See what uses space:

   run="${KRAFT_RUN_DIR:-${KRAFT_HOME:-$HOME/.kraft}/run}"
   du -sh "$run"/*
   

2. Remove the worktrees you no longer need. A worktree is removed when its item is abandoned or archived:
   • Abandon a work item you no longer want: kraft item abandon ID --yes. It removes the worktree, and deletes the item's local branch and its attachment copies in run/attachments/. Uncommitted work is lost, and so are commits you never pushed.
   • Archive a completed or abandoned item from the board's Done group, or with POST /api/work-items/ID/archive. It removes the worktree and keeps the item's record and its attachment copies, so you can still duplicate it. Commit uncommitted changes in the worktree first, or copy them out from kraft repo open ID: archiving loses them.
   • Auto-archive. archive.after_days in policy.yaml archives completed and abandoned items that old. The shipped file sets 30. Lower it to reclaim space sooner. See policy.yaml.
3. Delete old session logs in run/logs/ and result files in run/results/ by hand, with the server stopped. They stay after archiving.

You know it worked when du -sh "$run"/* shows worktrees smaller, and ls "$run/worktrees" no longer lists the item.

What archive does to the branch

• It deletes the local branch only when every commit on it is somewhere else too: another branch such as the base, a remote-tracking branch, a tag, or what Kraft pushed. Otherwise the branch stays, and the archive event says how many commits it kept.
• Commits on a detached HEAD in the worktree are kept on a new branch, kraft/rescued/<item id>. If Kraft cannot make that branch, it archives the item but leaves the worktree, and the archive event's worktree_kept says why.

kraft item complete and kraft item cancel keep the worktree until the item is archived. A cancelled item that never pushed keeps its branch after that too. Delete it by hand once you are done with it: git branch -D <branch>.

Next steps

• Back up and restore the database: copy the database before you delete anything by hand
• policy.yaml: set archive.after_days and the rest of policy.yaml
• View verbs: every flag of kraft view logs