Where Claude Code and Codex keep /goal state, and how one open-source app reads both

An open-source desktop app called Kiteline reads `/goal` state from both Claude Code and Codex by parsing two different storage formats: Claude Code writes `goal_status` attachment lines into its JSONL session transcripts, while Codex keeps goals in a `thread_goals` table inside `goals_N.sqlite` under `CODEX_HOME`. The implementation, in `watcher/kiteline-watch.py`, normalizes both sources into a single shape consumed by the phone, watch and desktop UIs, and handles edge cases such as read-only SQLite connections, WAL-change polling, truncated transcripts and detecting when a goal has stalled.

Both Claude Code and Codex now have /goal : you give a session a condition that can be checked, and the agent keeps working round after round until the condition is met. It is a good fit for long, well-defined jobs such as "get every unit test passing" or "first paint under 1.5 s and Lighthouse above 90", the kind of task where an agent would otherwise stop halfway and write a confident summary. The interesting part for tool builders is that the two agents record goals in completely different places. This post walks through both formats, using the implementation in Kiteline https://github.com/hon6/kiteline , an open-source desktop app Mac, Windows, Linux that follows Claude Code, Codex and other agent sessions and shows their progress on a phone. All the code mentioned below is in watcher/kiteline-watch.py . goal status attachments in the transcript Claude Code writes each session as a JSONL transcript. Once a goal is set, extra lines appear with type: "attachment" and attachment.type: "goal status" . The fields tell you what happened: | Line | Meaning | |---|---| | {met: false, sentinel: true, condition} | Goal set | | {met: true, sentinel: true} | Goal cleared /goal clear , or an unrecoverable error | | {met: false, condition, reason} | One check: not met yet, reason says what is missing | | {met: true, condition, reason, iterations, durationMs, tokens} | Goal met, with rounds, time and tokens | | {failed: true, …} | The check decided the goal can't be met | The check at the end of each round is itself a model call that judges the condition and explains why. Pauses show up as system lines instead, such as Goal paused · <cause · … or Goal still active · <cause · retrying in N min , which are easy to match: GOAL PAUSED RE = re.compile r"^Goal paused ?: after \d+ automatic retries ? · .+? · " GOAL RETRY RE = re.compile r"^Goal still active · .+? · retrying in \d+ min" GOAL ERROR RE = re.compile r"^Goal cleared after an unrecoverable error \ .+? \ " A small state machine ClaudeGoal consumes these lines: the "set" line opens a goal, every check bumps checks and stores the reason, and met / failed / cleared change the state. If the transcript was truncated or resumed and the "set" line is missing, it picks up from the first check it sees. thread goals table in local SQLite Codex does not put goals in the rollout file. They live in goals N.sqlite under CODEX HOME , one row per thread: select thread id, objective, status, token budget, tokens used, time used seconds, created at ms, updated at ms from thread goals status is one of active , paused , blocked , usage limited , budget limited or complete . Two details matter when you read this from another process: sqlite3.connect "file:...?mode=ro", uri=True so you never compete with Codex for the write lock. -wal file. If neither changed, reuse the last result, so polling every second costs nothing. If the table doesn't exist an older Codex , remember that until the file changes. Both sources are turned into the same shape, and every UI phone, watch, desktop only reads that: {"text": "Retry failed payment callbacks automatically…", "state": "active", "checks": 2, "reason": "1 case still fails: a duplicate callback for the same order is booked twice"} On the phone this becomes "Goal · round 3" in the session list, and a goal bar above the message box with the round, the time spent and the last check: Reading the formats is easy. Deciding that a goal has stopped is not, and a wrong answer means a confusing push notification. Request interrupted by user marker and otherwise waits for two minutes of idleness before calling a goal paused. ClaudeGoal now polls the file itself from a byte offset starting over if the file was rewritten and got shorter , so the snapshot always has the latest state. The full implementation ClaudeGoal , GoalBook , codex goals , goal command is in hon6/kiteline https://github.com/hon6/kiteline . Claude Code is a product of Anthropic and Codex is a product of OpenAI; Kiteline is an independent third-party tool.