Agent sessions

Obra Todo doesn’t just tolerate agents — it gives them their own surface. Alongside your GTD lists, the app displays the working to-do lists of agent sessions (Claude Code and friends), grouped by the local project each session works in. You see, at a glance, which repos have agent work going on and how far along it is.

The two systems are deliberately separate: agents never write into your todo.json, and the app treats session files as read-only (it only deletes them when you clear finished sessions).

How it works

Each agent session doing multi-step work maintains one JSON file in:

~/Library/Application Support/studio.obra.todo/agent-sessions/

named <project-dir-name>--<YYYYMMDD-HHMM>-<4 random chars>.json, updated in place for the whole session. The app re-reads the directory whenever its window regains focus.

Session file shape

{
  "version": 1,
  "project": "obra-todo",
  "projectPath": "/Users/you/Sites/obra-todo",
  "title": "Build the agent to-do tracker",
  "startedAt": "2026-07-25T10:30:00.000Z",
  "updatedAt": "2026-07-25T10:55:00.000Z",
  "done": false,
  "tasks": [
    { "title": "Add Rust commands for the session spool", "status": "done" },
    { "title": "Render the Agents sidebar section", "status": "in_progress" },
    { "title": "Document the format", "status": "todo" }
  ]
}

Field	Meaning
project	The repo/directory name — what the sidebar groups by.
projectPath	Absolute path, shown for orientation.
title	One line describing the session’s work.
startedAt / updatedAt	ISO 8601; bump updatedAt on every write.
done	true once the work is finished — the session dims and becomes clearable.
tasks[].status	"todo", "in_progress", or "done". Unknown values read as "todo".

In the app

• The Agents sidebar section lists each project with agent activity; the badge counts open tasks across its active sessions.
• A project’s page shows session cards — green dot while active, dimmed when done — with each task’s state: gray check (done), blue dot (in progress), empty circle (todo).
• Clear finished deletes the finished sessions’ files for that project.

Wiring up Claude Code

A short global instruction makes every session feed the tracker. Put this in ~/.claude/CLAUDE.md:

Every session that does multi-step work must maintain its own to-do list as a JSON file in ~/Library/Application Support/studio.obra.todo/agent-sessions/, named <project-dir-name>--<YYYYMMDD-HHMM>-<4 random chars>.json, following the session-file shape documented in the Obra Todo repo’s FORMAT.md. Rewrite the whole file when statuses change, bump updatedAt, and set "done": true as the session’s last write. Skip trivial one-off answers. Never edit or delete other sessions’ files.

Rules for agents

1. Create the file when starting multi-step work; skip it for trivial answers.
2. Rewrite the whole file atomically whenever the plan or a status changes.
3. Set "done": true as your last write.
4. Never edit or delete other sessions’ files.