Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
docs(pkg): make the README and package ready for npm
Erenb1ef7035a418
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex 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.+++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.pngnew file mode 100644index 0000000..853e677Binary files /dev/null and b/docs/images/map.png differdiff --git a/packages/cli/.gitignore b/packages/cli/.gitignorenew file mode 100644index 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+/LICENSEdiff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.mjsnew file mode 100644index 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();