Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

docs: bring the README and guide up to date with 0.20-0.25

Eren0c07da4e5f31
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d72192e..96ca74d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- The map tells your sessions from your teammates': a teammate's session always shows their name and yours never needs to, the side panel marks yours "(you)", and a new Everyone / You / teammate choice in the toolbar fades the other people's sessions.
### Changed
+- The README and the guide now describe what 0.20–0.25 ship: the map without epochs (row widths, open sessions remembered, the panel beside the map, one date shape, the person filter), Resume and Fork, forked sessions, `cogit doctor`, `why <file>:<line>` and the git-email identity. The map screenshots and the README demo are recorded again from the current map.
- A session records its author's git email next to their name, and people are told apart by email, as in git.
- A session only continues its author's own earlier sessions: after a pull, a teammate's sessions are no longer offered as the start of yours, and the map no longer draws a session as the continuation of someone else's.
diff --git a/README.md b/README.md
index 8094618..371cc7e 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Git remembers what changed. cogit remembers why.
<p align="center"><img src="docs/images/cogit-descartes.jpg" width="360" alt="René Descartes with git branches running through his hair"><br><i>Cogito, ergo commit.</i></p>
-<img src="docs/images/demo.gif" alt="cogit open shows the projects, then the map; pasting a message hash opens the decision behind it, and cogit why lists the thoughts behind a file">
+<img src="docs/images/demo.gif" alt="cogit open shows the map; pasting a message hash jumps to that message and opens the decision behind it">
cogit records every message you send to an AI coding agent as a *thought commit*: what you
asked, what came of it, and the message it answered. Your code commits point back to the
@@ -18,7 +18,8 @@ Claude Code today.
- **Every message becomes a thought commit**: the question, the outcome, the decisions with
their reasons and the options that were rejected, and which earlier message it continues.
- **A map of your sessions**: a git graph of your conversations with branches, decisions, a
- "Your turn" inbox and a one-click command to resume any chat.
+ "Your turn" inbox, and Resume and Fork buttons that copy the command to reopen a chat or
+ continue it as a new one.
- **Commits point back to their reason**: a `Thought:` trailer on each commit;
`cogit show <sha>`, `cogit blame` and `cogit why` follow it back.
- **Pull request descriptions with the decisions**: `cogit pr` writes the goal, the
@@ -75,7 +76,8 @@ cogit open .
- [Getting started](docs/guide/getting-started.md): what `init` asks, your first session,
setting up a team
-- [The map](docs/guide/map.md): sessions, branches, the inbox, unread work, files, search
+- [The map](docs/guide/map.md): sessions, branches, the inbox, unread work, files, search,
+ resuming and forking a session
- [Reading the lineage](docs/guide/reading-the-lineage.md): `log`, `show`, `blame`, `why`,
`search`
- [Pull requests](docs/guide/pull-requests.md): `cogit pr`
diff --git a/docs/guide/README.md b/docs/guide/README.md
index 013c527..2e22616 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -6,7 +6,7 @@ part in detail.
| Page | What it covers |
|---|---|
| [Getting started](getting-started.md) | Install, what `cogit init` asks, your first session, setting up a team |
-| [The map](map.md) | Sessions, branches, the "Your turn" inbox, unread work, files, search, resuming a session |
+| [The map](map.md) | Sessions, branches, the "Your turn" inbox, unread work, files, search, resuming or forking a session, the people filter |
| [Reading the lineage](reading-the-lineage.md) | `log`, `show`, `blame`, `why`, `search` in the terminal, and how the agent uses them |
| [Pull requests](pull-requests.md) | `cogit pr`: a review-ready description with the decisions behind the code |
| [Teams and git](teams-and-git.md) | What is committed, the `Thought:` trailer, the git hooks, teammates' records |
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 98343d4..e3a595f 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -6,6 +6,9 @@
- Claude Code 2.1.275 or later
- A git repository: cogit ties its record to your commits, so `cogit init` stops in a
directory that is not in one. Run `git init` first.
+- `git config user.name` and `git config user.email` set: cogit stamps each session with
+ them and, like git, tells people apart by email. Without an email `cogit init` warns, and
+ people are told apart by name instead, which is easier to get wrong.
## Install
diff --git a/docs/guide/map.md b/docs/guide/map.md
index 653ed08..aa1b98d 100644
--- a/docs/guide/map.md
+++ b/docs/guide/map.md
@@ -7,9 +7,13 @@ cogit open # the panel: every project on this machine
`cogit open` builds the page and serves it on `127.0.0.1` (port 4747, `serverPort`), starting
the server in the background if it is not running. The page refreshes itself whenever the
-record changes and keeps your place: the selected message, the unfolded branches, the scroll
-and the zoom. Nothing is sent anywhere; the server answers only this machine. The server
-stops on its own after 30 minutes without a page open; the next `cogit open` starts it again.
+record changes and keeps your place: the selected message, the unfolded branches, the open
+sessions, the scroll and the zoom. Nothing is sent anywhere; the server answers only this
+machine. The server stops on its own after 30 minutes without a page open; the next
+`cogit open` starts it again.
+
+Times read the same everywhere — `2026-10-30 21:09` in the details panel, the inbox and the
+project panel, `10-30` on the project tabs — instead of the browser's locale.
The panel lists every project `cogit init` set up on this machine. A project whose directory
was deleted or moved stays as a card marked "missing"; `cogit config prune` removes those
@@ -17,31 +21,50 @@ was deleted or moved stays as a card marked "missing"; `cogit config prune` remo
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../images/map-dark.png">
- <img src="../images/map-light.png" alt="The map: sessions, branches and the decision behind a message">
+ <img src="../images/map-light.png" alt="The map: sessions as branches, each message's commits and where the work left off">
</picture>
## Sessions and branches
The map reads like a git graph of your conversations. Time runs down the page.
-- **A session** is one Claude Code chat. Its header shows the title and when it ran.
-- **A row** is one message you sent, titled in your words and saying what came of it.
+- **A session** is one Claude Code chat. Its header shows the title, when it ran, and, when
+ someone else's sessions are on the map too, whose it is.
+- **A row** is one message you sent, titled in your words and saying what came of it. Rows
+ show the date on a day's first row and the time on the rest (`10-24 00:10`), so a long
+ session stays readable.
- **A branch** is a chain of messages that answer each other. It gets its own coloured lane;
its first message is a hollow ring carrying the branch's title. A new topic in the same chat
starts a new branch, and a message that goes back to an older thread curves out of that
thread.
-- **A return** to an earlier message without continuing it is a dashed arrow, marked
- `↩ m22` on the row.
-- **Long branches fold** to their first and last message and a "⋮ N more" row. "Unfold all"
- and "Fold all" open and close every branch at once.
+- **A continued session** starts with `↑ m37` on its first message, naming the message of an
+ earlier session it picks up from; hover it to see that session. A return to an earlier
+ message inside a session is listed in the message's details.
+- **Long branches fold** to their first and last message and a "⋮ N more — open" row.
+ **Unfold all** opens every session and every folded branch; **Fold all** closes them again.
- **"Left off here"** marks the newest message you sent. The map opens there.
A message with commits carries them as small chips with the commit subject, and a
`+1 240 −80 · 14 files` chip saying how much code landed after it.
+Clicking a message selects only that message; the details panel shows its branch. A session's
+header is highlighted only when the session itself is selected.
+
+The toolbar's Everyone / You / teammate choice fades the other people's sessions while leaving
+them in place, so the lines between them stay whole. It appears only when a teammate's sessions
+are on the map.
+
+Drag the right edge of an open session's messages to make the rows wider or narrower, so long
+titles wrap into fewer lines; double-click the edge to reset. Each session keeps its own width.
+Sessions you opened stay open after a reload, and the map still lands where you left off. Both
+are stored in the project's local `.cogit/state/map.json`, never in git, so every teammate
+keeps their own view.
+
## Message details
-Click a row to open its details on the right:
+Click a row to open its details in a column beside the map: the map keeps its place and
+narrows instead of the panel covering it, though a window narrower than 900 pixels lays the
+panel over the map.
- the branch it belongs to, with the branch summary: what was asked, what came of it, what is
still open
@@ -83,7 +106,8 @@ the map. In the terminal: `cogit log --file <path>` and `cogit why <path>`.
The search box in the top bar (Ctrl+F or Cmd+F) finds text in message titles, decisions,
branch summaries, session titles and the stored conversation, ignoring case and accents. Enter
and Shift+Enter step through the hits, Esc clears. A pasted message hash jumps straight to that
-message. In the terminal: `cogit search "<text>"`.
+message. Sessions the search opened close again when the search is cleared or stops matching
+them, unless you clicked into one. In the terminal: `cogit search "<text>"`.
## Switching projects
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 80a4c60..024d49f 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -36,9 +36,12 @@ A message without a record yet is picked up by the next side run or at the sessi
## The map looks old after an upgrade
-The map server keeps running in the background with the version it started with, and it
-rebuilds the map with that version. Stop it (it listens on `127.0.0.1:4747`) and run
-`cogit open .` again.
+Every map is stamped with the cogit version that built it. The next `cogit open` stops a
+server left running by the old version and starts this one, and the server rebuilds a map
+another version wrote before serving it, so the page matches the command you have. If a tab
+still shows the old page, reload it; a server too old to be stopped by `cogit open` keeps
+running on `127.0.0.1:4747`, and `cogit open .` falls back to the file — stop that process and
+open the map again.
## The port is taken
diff --git a/docs/images/demo.gif b/docs/images/demo.gif
index d66a00e..fa2e103 100644
Binary files a/docs/images/demo.gif and b/docs/images/demo.gif differ
diff --git a/docs/images/map-dark.png b/docs/images/map-dark.png
index 09e8b6e..8aaa86e 100644
Binary files a/docs/images/map-dark.png and b/docs/images/map-dark.png differ
diff --git a/docs/images/map-light.png b/docs/images/map-light.png
index cd0a87b..41e09f4 100644
Binary files a/docs/images/map-light.png and b/docs/images/map-light.png differ