Keeping the feed full¶
Cards are written by an agent session: Claude Code or Codex. GitTok does not start a model by itself, and it does not run claude -p. So generation needs a session that is open. All other work (analysis, rendering, learning, notifications, garbage collection) is local Python and needs no session.
What runs without an agent¶
| Job | How |
|---|---|
| The feed server: the feed, and the render, learning, profile, notification and garbage-collection workers | An agent session in the GitTok directory starts it (.mcp.json in Claude Code, .codex/config.toml in Codex) and it stops with the session. gittok serve starts it by hand. Nothing keeps it running when no session is open |
| Analysis of the repos | gittok analyze (cached by head commit). get_brief also runs it |
| Notifications | gittok notify. The server also runs this pass |
Ways to generate¶
| Way | Notes |
|---|---|
On demand: "make more cards", or /gittok-generate ($gittok-generate in Codex) |
Always works. The run makes as many cards as the feed needs |
| After a repo is added | Your agent profiles the new repo and then runs /gittok-generate for the first cards. It does not ask first. The run ends at nothing_to_do when the feed has enough cards |
| The SessionStart hint | gittok health --hint prints one line at the start of a session when the unseen cards will not last agent.target_runway_days. The line says to run /gittok-generate |
| The feed watch | gittok feed-watch blocks until the server says the feed wants cards, then exits. A session that runs it in the background is woken at that moment and runs /gittok-generate, then starts the watch again. Codex uses its own variant ("Codex sessions" below) |
Claude Code only: /loop 4h /gittok-generate in a session you leave open |
Most ticks end at nothing_to_do and cost one MCP call |
gittok init writes the hooks to .claude/settings.json of the GitTok directory for Claude Code, and to .codex/hooks.json for Codex (docs/install.md, "Session hooks"). A clone has them in its own project files.
Codex sessions¶
gittok init also writes .codex/config.toml, .codex/hooks.json and
.agents/skills/. Codex connects to the same stdio server and reads the same
workflow and worker instructions. Trust the project configuration and review the
hooks with /hooks. The startup instructions run the same hints if hooks did not.
Use $gittok-generate in place of /gittok-generate; generation uses Codex
subagents on the models of agent.models.codex (none: your session's model).
The Codex runtime adapter starts gittok feed-watch --codex-thread "$CODEX_THREAD_ID"
in the background (with uv run --quiet in a source clone). When the feed asks
for cards, the watch queues a fixed refill prompt with codex queue --thread <id>
--message <prompt> --resume, then exits. The local Codex daemon is asked to resume
the existing thread, so shell completion notifications are not needed to request
an idle refill. Private delivery receipts under data/codex-wake/ remember the
last signal queued to each thread, including across watch restarts. A per-thread
file lock covers the fresh receipt check, queue call and receipt write, so
overlapping watches cannot queue the same signal twice. The agent generates cards and starts the same watch again.
This requires a local Codex CLI with queue --resume, a nonempty thread id, and
a reachable daemon. A successful queue can still print a resume warning; the
agent preserves that warning rather than claiming it woke. A failed queue leaves
the feed request pending. Clients without this capability use the plain watch
and check health on the next user turn; automatic idle refill is unavailable there.
The Claude Code watch is unchanged and does not invoke Codex. The limits below still apply
to both clients.
How the feed watch works¶
- The server appends one line to
<data_dir>/feed-wants-cards.logwhen the feed wants cards. The line is one JSON object that holds a time and a count only, such as{"at":"2026-06-01T12:00:00+00:00","want":12}.gittok feed-watchreads whole lines of this shape and ignores any other text. - The notification worker of the feed server makes this check once a minute. A feed request does not make it.
- The feed wants cards when the unseen cards will not last
agent.target_runway_daysat the reading speed of the last 7 days. - It does not write a line when there are no repos, while a run that started in the last
agent.wake_cooldown_hoursis still open, whenagent.per_day_runsruns started in the last 24 hours (a new run could not start), or withinagent.wake_cooldown_hoursof the last line. - The end of the feed is the exception to the last rule. When no unseen card is left and a run that made at least one card started after the last line and has finished, the server writes a new line at once. So a reader who reads every card does not wait for the cooldown. When no run answered the last line (or a run made no card), a second line would say nothing new, and the server writes none. So runs that make nothing cannot chain up to the daily cap.
gittok feed-watchchecks the file every--pollseconds. It exits when a new line arrives. It also exits at once if the last line is newer than the newest run, because no run answered that line, but only while the feed still wants cards. If the feed is full again (a run foundnothing_to_do), the watch waits for a new line.gittok feed-watch --hintprints the line that tells the session to start the watch.--codex-thread THREADadds one queue-and-resume attempt for that Codex thread when a signal arrives. The prompt contains only a parsed count and fixed instructions, never raw log text or repo contents.
When cards are made without a request¶
All of these must be true:
- An agent session is open in the GitTok directory, and it started the feed watch. The SessionStart hook tells it to. In Claude Code, a turn starts for the session when the watch exits, also when the session is idle. If the session is in the middle of other work, the run starts after that work. In Codex, the watch queues a refill prompt for the thread ("Codex sessions" above); without that, Codex checks the feed on your next message.
- The feed server runs (the session starts it) and at least one repo is configured.
- The feed wants cards: the unseen cards last under
agent.target_runway_days(3). - No run is open, and fewer than
agent.per_day_runs(10) runs started in the last 24 hours. - The last signal is older than
agent.wake_cooldown_hours(4), or the feed is empty and a run that made cards answered the last signal.
With no session open, nothing makes cards. The server still writes the line, and the next session that starts the watch answers it at once.
The web app says this at the end of the feed. GET /api/feed has generating, which is true while a run is open; the end-of-feed card then says that new cards are being made now. Otherwise it says that more cards come by themselves while a session is open, and that the reader can ask for more at once.
Limits¶
The server enforces the limits, whatever starts the run: agent.max_count cards per run and agent.per_day_runs runs per day (docs/config.md). The worker models come from agent.models: in Claude Code Haiku and Sonnet by default, in Codex the session's model unless you name others.
A cloud agent cannot generate cards: it cannot reach 127.0.0.1 on your Mac, and it cannot read your local repos.