Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
The cogit record format
cogit stores the why next to git's what. This document is the contract for
that record: the files, their JSON shapes, the message id, and how the graph is
read. It is written for anyone who wants to read or write .cogit/ without
running cogit — another agent, a viewer, an import/export tool.
The JSON Schemas in docs/schema/ are generated from the zod schemas
in packages/cli/src/schema/; they are the machine-readable form of this page.
npm run schemas regenerates them, and packages/cli/test/schema-export.test.ts
fails when a file and the code disagree.
Where the record lives
<project>/.cogit/
project.json # name, schema version (committed when shared)
sessions/<session-id>.json # one file per session, the notes
sessions/<session-id>.events.jsonl # append-only structure facts
conversations/<session-id>.jsonl.gz # the conversation store (local by default)
state/<session-id>.json # hook state: turn counter (local)
locks/ # lock files (local)
inbox/<session-id>.json # JSON the agent hands to `session write` (local)
HEAD # the session the next commit carries (local)
.gitignore # keeps all but the marker out of commits
map.html # generated map (local)
~/.config/cogit/ # or $COGIT_HOME / $XDG_CONFIG_HOME/cogit
config.json # global settings
projects.json # registry of project paths
panel.html # generated project switcher (local)
COGIT_HOME overrides the config directory (CODELINEAGE_HOME is still read as
a fallback). A pre-rename .codelineage/ is migrated to .cogit/ silently on
the first command or hook in the project.
What travels, and how
In a project that shares its record the root .gitignore says nothing about .cogit/;
.cogit/.gitignore keeps everything but the marker out of commits:
*
!.gitignore
!project.json
The sessions travel on refs instead, one per session, in the same repository:
refs/cogit/sessions/<session-id> # what this clone wrote
refs/cogit-remote/sessions/<session-id> # what the remote last said (local name)
refs/cogit/projects/<hash>/sessions/<session-id> # a project in a repository subdirectory
Each ref names a tree, not a commit, so no history builds up and git log --all stays
clean. The tree holds session.json, events.jsonl when it exists, and, with
shareConversations: true, conversation.jsonl.gz. A clone receives them through one
fetch line, +refs/cogit/*:refs/cogit-remote/*, which cogit adds the first time it runs
there. To read a session without cogit:
git fetch origin '+refs/cogit/*:refs/cogit-remote/*'
git show refs/cogit-remote/sessions/<session-id>:session.json
Everything else (state/, locks/, inbox/, map.html, HEAD, backups) stays local.
In a private project the root .gitignore holds /.cogit/ and nothing travels.
Versioning
Every versioned document has an integer schema field, starting at 1:
| File | Schema |
|---|---|
project.json |
PROJECT_SCHEMA = 1 |
sessions/<id>.json |
SESSION_SCHEMA = 1 |
sessions/<id>.events.jsonl |
event shape v1 (no per-line version) |
config.json |
CONFIG_SCHEMA = 1 |
projects.json |
CONFIG_SCHEMA = 1 |
state/<id>.json |
STATE_SCHEMA = 1 |
A reader must accept an older version by migrating it step by step
(parseVersioned in packages/cli/src/schema/versioned.ts). A newer version is
read best-effort with a warning, never rejected. A reader that changes the shape
of a document must do it in code (a migration), not by hand-editing old files.
project.json
{
"name": "cogit",
"schema": 1
}
project.json is the only file two people write; cogit writes it with sorted keys,
one per line. Older files also list epochs (named stretches of work that sessions
pointed at through an epoch field); cogit no longer groups sessions that way, so
readers drop both fields and a rewrite leaves them out.
sessions/.json
One file per session, written only by that session's owner. The session id is a
slug ([A-Za-z0-9][A-Za-z0-9_.-]{0,127}), normally the agent's session id.
{
"schema": 1,
"sessionId": "9c32…",
"agent": "claude-code",
"title": "e2e setup flow",
"startedAt": "2026-10-26T10:00:00.000Z",
"updatedAt": "2026-10-26T10:30:00.000Z",
"status": {
"goal": "…",
"done": ["…"],
"pending": [{"text": "…", "needsUser": true}],
"next": "…"
},
"leftOff": "…",
"nodes": [
{
"id": "h3f9a2c1b0d4",
"parent": null,
"kind": "message",
"title": "Set up the e2e flow",
"at": "2026-10-26T10:01:00.000Z",
"branch": {"title": "…", "asked": "…", "outcome": "…", "open": ""}
}
],
"author": "Eren",
"worktree": {"path": "/…/wt/feature", "branch": "feature"}
}
agentis the recording agent (claude-codetoday).authoris gituser.name(else the OS user), set on the first write. Older records have none.worktreeis set by the CLI when the session ran in a linked worktree.leftOffis one line on where the session left off, written by the session-end pass, so a later session can tell whether it continues this one. Older records have none.addedAtandtouchedAton a node are stamped bysession write, never taken from agent input. A resent node that changes nothing keepstouchedAt.
Nodes
kind is one of phase, message, step, decision, question. New records
write message nodes only: one per user message. The other kinds are kept for
records written before messages became the nodes; they still render.
A node carries the notes: title, optional summary, why, decidedBy
(user | agent | agreed), alternatives ({option, why}), work,
agentDecisions, commits (7–40 hex), files, links. The first message of a
branch carries branch ({title, asked, outcome, open}).
The message id
A message node id is stable: h plus the first 12 hex characters of the
SHA-256 of the canonical JSON:
{"sessionId":"<session>","uuid":"<transcript uuid or ''>","at":"<ISO time>","text":"<the text the user sent>"}
The JSON has that exact key order, no whitespace, and UTF-8 bytes. uuid is the
transcript's uuid for the user line, or "" when there is none. The parent is
not part of the hash: correcting a parent never renames a message, so notes
and links keep pointing at it. messages.ts computes it (messageHash).
m1, m2, … are display labels derived from send order, not ids. A reader
may accept a label where an id is expected (the CLI maps it), but a stored record
should use the stable id. A record written before stable ids (schema still 1; the
mN ids) is renamed on load and persisted on its next session write.
A cross-session reference has the form <sessionId>:<id>: a message of an
earlier session of the same project (never across projects).
Parents, links, roots
parent is the earlier message a node reacts to, null for a new root. A parent
must be an earlier message of the session (or a checked cross-session reference);
anything else is repaired to the previous message with a warning.
links are up to five earlier messages a node builds on besides its parent. On
the map, a link from the left channel is drawn as a dashed return arrow.
Siblings are ordered by when their thread began (the earliest at in their
subtree; addedAt for non-message nodes). A branch starts at a root or where a
message gains a second child.
sessions/.events.jsonl
Notes live in the session JSON and may be updated freely (like git notes).
Structure changes are facts and are appended here, one JSON object per line:
{"at":"2026-10-26T10:05:00.000Z","type":"parent","msg":"h3f9…","target":"h2b1…","by":"agent"}
{"at":"2026-10-26T10:06:00.000Z","type":"link","msg":"h3f9…","target":"h1aa…","by":"user"}
{"at":"2026-10-26T10:07:00.000Z","type":"unlink","msg":"h3f9…","target":"h1aa…","by":"agent"}
typeisparent,linkorunlink.msgis the message whose structure changed;targetis the parent (ornullfor a root) or the other message.byisagentoruser.atis when the change was recorded.
Replay is the only read rule: the last parent event for a message wins,
link adds a return, unlink removes one. A message with no parent event is a
root. Lines are never edited or deleted. A session with no events file (an older
record) keeps rendering from its JSON parent/links; the first
session write that changes its structure seeds the existing facts first.
conversations/.jsonl.gz
The conversation as the drill-down shows it, so it survives the agent deleting its transcript. The file is a sequence of gzip members, append-only; each member holds one or more JSON lines:
{"uuid":"…","hash":"h3f9…","at":"…","text":"…","replies":["…"],"tools":{"commands":1,"files":["src/a.ts"],"other":2}}
uuidis the transcript's uuid and the idempotency key: a turn already stored is not stored again.hashis the stable message id; a later line with the sameuuidmay add it to a turn stored before stable ids.text,repliesandtoolsare redacted before writing. Tool output is never stored, only counts and edited file paths.
conversations/ is local unless shareConversations is on, which adds it to the session's ref.
state, locks, inbox, HEAD
state/<id>.json:{schema, turns, turnsSinceUpdate, recordUpdatedAt}. Derived and machine-local; losing it only restarts the turn count.state/record-sync.json: what waits to be sent, what the last download or send said, and each session's file stamps. Derived and machine-local; losing it costs a re-hash.locks/: lock directories for the build and for one session's writes.inbox/<id>.json: where the record skill writes its JSON beforecogit session write --file … --consume. The CLI validates, redacts, merges and deletes it.HEAD: written by theUserPromptSubmithook, local and ignored:{sessionId, transcriptPath?, at?}. It names the session the next code commit from a terminal carries (see the trailer below). A missing or staleHEADmeans "no trailer".
The Thought: trailer
A code commit can name the message that led to it with a git trailer:
feat(auth): add the login form
Thought: h3f9a2c1b0d4
The git prepare-commit-msg hook adds it with git interpret-trailers, always
naming the newest user message of the session that made the commit:
- When the agent names the session in the hook's environment (Claude Code sets
CLAUDE_CODE_SESSION_IDin every Bash and hook subprocess), that session's transcript is used and.cogit/HEADis ignored — two sessions in one working tree each carry their own message. - When the variable is set but that session has no readable transcript (a
--continuewhose id moved, a session of another project), no trailer is added. cogit never falls back to.cogit/HEADhere: it may name the other session. - When the named session runs in another directory (its transcript's
cwdis neither in this project nor in the working tree being committed), no trailer is added: a session that commits into a neighbouring repository keeps its record in its own project, so the link could never be followed from here. - When no session is named (a human commit in a terminal),
.cogit/HEADis used when it is fresh (withintrailerMaxAgeHours, default 6) and its transcript is readable.
It is skipped for merge and squash commits and when the trailer is already
present (--amend). A failure never blocks the commit.
Readers must not trust the trailer alone: at read time cogit reads the trailers
back from git log (%(trailers:key=Thought,valueonly)) and attaches those
commits to their message nodes. A trailer wins over a commit hash the agent also
listed on the node.
The git pre-push hook queues the sessions the remote does not have yet and sends them in the
background, with --no-verify so that push does not set off the hook again. A code commit
carries only the trailer; the record never enters a commit.
Reading a branch for a pull request
cogit pr groups the commits of base..HEAD by the Thought: trailer and prints the
sessions' goals, each thought's title, summary, decisions and rejected options, and its
commits and changed files. It reads only the record (project.json, sessions/) — never
the conversation store and never the user's raw prompts — so its output is safe to paste into
a public pull request.
What the schemas describe
| File | Describes |
|---|---|
schema/session.json |
a stored session file |
schema/session-input.json |
the JSON the agent sends to session write |
schema/session-event.json |
one line of the events log |
schema/project.json |
project.json |
schema/config.json |
the global config.json |
schema/registry.json |
the global projects.json |
schema/hook-state.json |
state/<id>.json |
The schemas use JSON Schema 2020-12. session-input.json is generated in
input mode (fields with defaults are optional); the others in output mode
(what a written record contains).
Regenerate after a schema change:
npm run schemas # writes docs/schema/*.json
./qa runs the drift test, so a forgotten regeneration fails the gate.