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

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, 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.

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:

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 \((.+?)\) " ) Enter fullscreen mode Exit fullscreen mode 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.

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 Enter fullscreen mode Exit fullscreen mode status is one of active, paused, blocked, usage_limited, budget_limited or complete. Two details matter when you read this from another process:

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" } Enter fullscreen mode Exit fullscreen mode 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.

The full implementation ( ClaudeGoal, GoalBook, codex_goals, goal_command ) is in hon6/kiteline. Claude Code is a product of Anthropic and Codex is a product of OpenAI; Kiteline is an independent third-party tool.