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(pkg): make the README and package ready for npm

Erenb1ef7035a418
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 081ce52..313c5e6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Added
+- npm readiness: the README now says what cogit is, shows the map, the four read verbs (`log`, `show`, `blame`, `search`), what git sees, privacy and every setting; the package carries `repository`, `homepage`, `bugs` and keywords, and `prepack` copies the repository README and LICENSE next to `package.json` so the registry page shows them. `npm pack` still ships only the bundled CLI, the plugin manifest, the skill, the hooks and those two files.
+
### Changed
- Activity is message time everywhere: the map's session lanes and the project switcher's last-activity date follow the newest message a session holds, so editing an old record no longer makes it look like it ran until now. The local map server watches Claude Code's transcripts while a map page is open (one recursive, debounced watcher) and rebuilds the map itself, so the page is live without the plugin's Stop hook; the watch closes when the last tab does. The `commitBetween` hint asks git for a commit that actually landed in this repository between the two messages instead of trusting a `git commit` line in the transcript, `blame` takes a `[dir]` positional like `log` and `show`, and `session show` gained `--full` for every recorded message and the parent candidates (the default stays compact). The record-update skill text is about half its former size, cutting the fixed cost of every update.
diff --git a/README.md b/README.md
index b643ab8..0329495 100644
--- a/README.md
+++ b/README.md
@@ -4,45 +4,98 @@
Git remembers what changed. cogit remembers why.
-The lineage of your AI coding sessions: every user message hangs from the message
-it reacts to, and the map draws each session as a git graph you can zoom into.
+![The map: sessions, branches and the thoughts behind them](docs/images/map.png)
+
+cogit records every message you send to an AI coding agent as a *thought commit*, with what
+came of it and the message it answered. Code commits point back to the thought through a
+`Thought:` trailer, so `git log` and `cogit log` tell two halves of one story. Your agent reads
+the lineage with `cogit log`, `show`, `blame` and `search`; you read it as a map of sessions,
+branches and decisions.
+
+## Install
+
+```bash
+npm install -g cogit # the CLI; Node >= 22.13
+npx cogit --help # or run it without installing
+```
+
+The Claude Code plugin adds the skill that keeps the record and the hooks that maintain it
+(Claude Code 2.1.275 or later):
+
+```text
+/plugin install cogit --marketplace sainthardrock/cogit
+```
## Quick start
```bash
-npm install -g cogit
-cogit init # answer the setup questions in the project you work in
-cogit open # open the map in the browser
+cd your-project
+cogit init # asks about git, transcript retention and summary language
+cogit open # builds the map and serves it on 127.0.0.1
+```
+
+Then work as usual. The skill updates the record every few turns (`updateEveryTurns`, default
+5) and at session end; the hooks write `.cogit/HEAD`, rebuild the map and, if `recordCommit`
+is `auto`, commit the record. Nothing cogit installs can block a prompt or a commit: every
+hook failure is silent and exits 0.
+
+## Read the lineage
+
+```bash
+cogit log # like git log: messages and branches, newest first
+cogit log --branches # only the branch summaries
+cogit log --file src/auth.ts # the thoughts that touched this file
+cogit show h3f9c2a1b4d6 # one message: the turn, what came of it, its commits
+cogit blame src/auth.ts:42 # which recorded message produced this line
+cogit search "refresh token" # titles, summaries, decisions and the stored conversation
```
-`init` also installs the Claude Code side: the lineage skill updates the record as
-you work, the hooks rebuild the map after each turn and at the end of a session.
-
-## Privacy and what travels with the repo
-
-- The skill records decisions and rationale, never raw chat; session files hold
- titles and summaries only.
-- `init` asks whether to commit the session records and now answers **yes** by
- default: `.cogit/sessions/` and `project.json` travel with a clone, while
- `.cogit/.gitignore` keeps local state (`conversations/`, `state/`, `locks/`,
- `inbox/`, `map.html`, `HEAD`, backups) out. Switch an existing project with
- `cogit config git commit|ignore`.
-- A git `pre-commit` hook stages the current session's record with the code
- commit, so a clone keeps the "why". It never creates a record-only commit.
-- The map's Conversation panel needs the real turns, so `build` reads them from
- Claude Code's local transcript and keeps a copy in
- `.cogit/conversations/<sessionId>.jsonl.gz`. This store lets the panel keep
- working after Claude Code deletes the transcript.
-- That copy stays on this machine by default. Turn on `shareConversations`
- (Settings → Recording, or `cogit config set shareConversations true`) to commit
- it too; a clone without it says "This conversation is not on this machine".
-- Each session records its author (git `user.name`, else the OS user) on its
- first write, shown on the map and in `cogit log`.
-- `recordCommit` controls the last messages after the last code commit: `ask`
- (default) offers a `chore(cogit): record <title>` commit at the next session
- start, `auto` commits exactly the record paths at session end, `off` does
- nothing. Both settings are in Settings → Recording.
-- Both the page and the conversation store go through the same redaction pass
- (common key and token patterns) before anything is written.
-- Claude Code deletes transcripts after `cleanupPeriodDays` (30 days by default).
- `init` offers to raise it, never silently.
+Each takes `[dir]` (or `-C <dir>`), the list verbs take `-n <count>` and `--json`. A message is
+addressed by its hash (`h` plus 12 hex), `<session-id-prefix>:mN`, or — for `show` — a commit
+hash with a `Thought:` trailer.
+
+## What git sees
+
+- `.cogit/sessions/` and `.cogit/project.json` are committed by default, so the record travels
+ with a clone. `cogit config git commit|ignore` switches an existing project; local state
+ (conversations, locks, inbox, map, `HEAD`) is always ignored.
+- A `pre-commit` hook stages the current session's record with your next code commit. It never
+ creates a record-only commit. `recordCommit` decides what happens to messages recorded after
+ the last commit: `ask` (default), `auto` or `off`.
+- A `prepare-commit-msg` hook adds `Thought: h<id>` to a commit it can attribute — skipped for
+ merges and squashes, and when `.cogit/HEAD` is older than `trailerMaxAgeHours`. `build`,
+ `log`, `blame` and the Files view read the trailers back with `git log`.
+
+## Privacy
+
+- The raw conversation stays on this machine. `.cogit/conversations/` holds a local copy of the
+ transcript so the panel keeps working after Claude Code deletes it; `.cogit/.gitignore` keeps
+ it out of git unless `shareConversations` is on.
+- The record holds titles, summaries, decisions and work items — never tool output.
+- A redaction pass for keys and token patterns runs over everything the map writes or shows.
+- Claude Code keeps transcripts for `cleanupPeriodDays` (30 days by default); `init` offers to
+ raise it and never changes it silently.
+
+## Settings
+
+`cogit config get [key]` and `cogit config set <key> <value>`, or **Settings** in the map.
+
+| Key | Default | What it does |
+|---|---|---|
+| `language` | `auto` | Summary language: the conversation's, or a fixed one |
+| `updateEveryTurns` | `5` | Turns between record updates |
+| `sessionEndCatchUp` | `true` | Summarize the last messages when a session ends |
+| `catchUpModel` | `haiku` | Model for the session-end catch-up |
+| `messageSummaries` | `false` | A summary on every message, not just every branch |
+| `startupContext` | `true` | Hand the agent the previous session's lineage at session start |
+| `gitPolicy` | `commit` | Whether new projects commit the record |
+| `shareConversations` | `false` | Commit the raw conversation too |
+| `recordCommit` | `ask` | What to do with messages after the last code commit |
+| `trailerMaxAgeHours` | `6` | How old `.cogit/HEAD` may be for a `Thought:` trailer |
+| `serverPort` | `4747` | Port for the local map server |
+
+## Docs and licence
+
+The design, the data model and the full CLI surface are in
+[specs/codelineage-mvp.md](specs/codelineage-mvp.md), kept up to date with the code. MIT —
+see [LICENSE](LICENSE).
diff --git a/docs/images/map.png b/docs/images/map.png
new file mode 100644
index 0000000..853e677
Binary files /dev/null and b/docs/images/map.png differ
diff --git a/packages/cli/.gitignore b/packages/cli/.gitignore
new file mode 100644
index 0000000..fc0c39c
--- /dev/null
+++ b/packages/cli/.gitignore
@@ -0,0 +1,3 @@
+# Generated by `npm pack` (scripts/copy-docs.mjs); the repository root holds the source.
+/README.md
+/LICENSE
diff --git a/packages/cli/package.json b/packages/cli/package.json
index f4f5cf8..b400e25 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -3,6 +3,24 @@
"version": "0.10.0",
"description": "Git remembers what changed. cogit remembers why.",
"license": "MIT",
+ "keywords": [
+ "git",
+ "ai",
+ "coding-agent",
+ "claude-code",
+ "history",
+ "lineage",
+ "commit",
+ "context"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/sainthardrock/cogit.git"
+ },
+ "homepage": "https://github.com/sainthardrock/cogit#readme",
+ "bugs": {
+ "url": "https://github.com/sainthardrock/cogit/issues"
+ },
"type": "module",
"bin": {
"cogit": "dist/cli.js"
@@ -19,7 +37,7 @@
"scripts": {
"prebuild": "node ../../scripts/sync-version.mjs",
"build": "tsup",
- "prepack": "node ../../scripts/sync-version.mjs"
+ "prepack": "node ../../scripts/sync-version.mjs && node ../../scripts/copy-docs.mjs"
},
"devDependencies": {
"@inquirer/prompts": "^8.7.4",
diff --git a/packages/cli/test/copy-docs.test.ts b/packages/cli/test/copy-docs.test.ts
new file mode 100644
index 0000000..5b10611
--- /dev/null
+++ b/packages/cli/test/copy-docs.test.ts
@@ -0,0 +1,22 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+// @ts-expect-error plain ESM script without types
+import { copyDocs, DOCS, run } from "../../../scripts/copy-docs.mjs";
+import { tempDir } from "./helpers.js";
+
+describe("copy-docs", () => {
+ it("copies the README and LICENSE next to package.json", async () => {
+ const root = await tempDir();
+ await mkdir(join(root, "packages/cli"), { recursive: true });
+ for (const name of DOCS as string[]) await writeFile(join(root, name), `${name}\n`);
+
+ expect(copyDocs(root)).toEqual(DOCS);
+ for (const name of DOCS as string[])
+ expect(await readFile(join(root, "packages/cli", name), "utf8")).toBe(`${name}\n`);
+ });
+
+ it("is what this repository publishes", () => {
+ expect(run(() => {})).toEqual(DOCS);
+ });
+});
diff --git a/packages/cli/test/plugin-manifest.test.ts b/packages/cli/test/plugin-manifest.test.ts
index 13e792c..5f301bc 100644
--- a/packages/cli/test/plugin-manifest.test.ts
+++ b/packages/cli/test/plugin-manifest.test.ts
@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
import { describe, expect, it } from "vitest";
const read = async (path: string) =>
@@ -38,6 +38,32 @@ describe("plugin packaging", () => {
]);
});
+ it("carries the npm metadata a publish needs", async () => {
+ const pkg = await read("../package.json");
+ // Story 6.1: the registry page comes from these fields alone.
+ expect(pkg.description).toBe("Git remembers what changed. cogit remembers why.");
+ expect(pkg.license).toBe("MIT");
+ expect(pkg.repository).toEqual({
+ type: "git",
+ url: "git+https://github.com/sainthardrock/cogit.git",
+ });
+ expect(pkg.homepage).toBe("https://github.com/sainthardrock/cogit#readme");
+ expect(pkg.bugs).toEqual({ url: "https://github.com/sainthardrock/cogit/issues" });
+ expect(pkg.keywords).toEqual(expect.arrayContaining(["git", "claude-code", "lineage"]));
+ });
+
+ it("keeps a README that shows the map and points at the spec and licence", async () => {
+ const readme = await readFile(new URL("../../../README.md", import.meta.url), "utf8");
+ expect(readme).toContain("![The map");
+ expect(readme).toContain("(docs/images/map.png)");
+ expect(readme).toContain("(specs/codelineage-mvp.md)");
+ expect(readme).toContain("(LICENSE)");
+ // A relative image only renders when the file it names is in the repository.
+ await expect(
+ access(new URL("../../../docs/images/map.png", import.meta.url)),
+ ).resolves.toBeUndefined();
+ });
+
it("ships no runtime dependencies, since the CLI is bundled into one file", async () => {
const pkg = await read("../package.json");
expect(pkg.dependencies).toBeUndefined();
diff --git a/scripts/copy-docs.mjs b/scripts/copy-docs.mjs
new file mode 100644
index 0000000..fc9aa4d
--- /dev/null
+++ b/scripts/copy-docs.mjs
@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// npm publishes from packages/cli; the registry shows the README and LICENSE it finds
+// next to package.json, so `prepack` copies the repo's two files there.
+import { copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DOCS = ["README.md", "LICENSE"];
+
+/** Copies the root docs into the package that npm publishes; returns what it copied. */
+export function copyDocs(root) {
+ const target = join(root, "packages/cli");
+ for (const name of DOCS) copyFileSync(join(root, name), join(target, name));
+ return [...DOCS];
+}
+
+/** Copies into this repository and prints each file. */
+export function run(log = console.log) {
+ for (const name of copyDocs(join(dirname(fileURLToPath(import.meta.url)), "..")))
+ log(`packages/cli/${name}: copied`);
+ return [...DOCS];
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) run();