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
feat(hooks): leave claude -p sessions unrecorded unless recordHeadless is on
Erenb8dcd8f7243c
diff --git a/docs/guide/settings.md b/docs/guide/settings.mdindex 7857096..b0be7f4 100644--- a/docs/guide/settings.md+++ b/docs/guide/settings.md@@ -32,6 +32,14 @@ A one-sentence summary under each message title, so a skim reads better. Off keeWhen a chat starts, the agent gets a short summary of where the previous session left off and how to read the record. It costs a few tokens; turn it off if your projects are unrelated.+### Headless sessions++`recordHeadless` · default `false`++**Record sessions that start without a person, such as `claude -p`.**++Some plugins and scripts run `claude -p` in the background, often once per prompt. Off, cogit leaves those sessions out of the map and the inbox. Turn it on if you do real work through `claude -p` or the SDK and want it recorded.+### Tried-before notes`tryBeforeNotes` · default `true`diff --git a/docs/schema/config.json b/docs/schema/config.jsonindex ad66b35..fe41ca5 100644--- a/docs/schema/config.json+++ b/docs/schema/config.json@@ -56,6 +56,10 @@"default": true,"type": "boolean"},+ "recordHeadless": {+ "default": false,+ "type": "boolean"+ },"serverPort": {"default": 4747,"type": "integer",@@ -134,6 +138,7 @@"sideEveryTurns","messageSummaries","startupContext",+ "recordHeadless","serverPort","gitPolicy","shareConversations",diff --git a/packages/cli/src/agents/claude/hooks.ts b/packages/cli/src/agents/claude/hooks.tsindex 67f55be..6db32df 100644--- a/packages/cli/src/agents/claude/hooks.ts+++ b/packages/cli/src/agents/claude/hooks.ts@@ -32,6 +32,15 @@ export function parseHookInput(stdin: string): HookInput | undefined {return parsed.success ? parsed.data : undefined;}+/**+ * Whether the hook runs in a session nobody types into: `claude -p` and the SDKs+ * mark themselves `sdk-*` in `CLAUDE_CODE_ENTRYPOINT`, which the hooks inherit.+ * Other plugins start such sessions in the background, one per prompt.+ */+export function isHeadless(env: NodeJS.ProcessEnv): boolean {+ return env.CLAUDE_CODE_ENTRYPOINT?.startsWith("sdk") ?? false;+}+/** A hook answer Claude Code shows the user as a warning line; the agent does not see it. */export function userNotice(text: string): Record<string, unknown> {return { systemMessage: text };diff --git a/packages/cli/src/agents/claude/index.ts b/packages/cli/src/agents/claude/index.tsindex c1b2089..d92e7d8 100644--- a/packages/cli/src/agents/claude/index.ts+++ b/packages/cli/src/agents/claude/index.ts@@ -1,5 +1,5 @@import { type AgentAdapter, DEFAULT_AGENT } from "../types.js";-import { additionalContext, parseHookInput, userNotice } from "./hooks.js";+import { additionalContext, isHeadless, parseHookInput, userNotice } from "./hooks.js";import {allowSkill,CLAUDE_DEFAULT_RETENTION,@@ -55,6 +55,7 @@ export const claude: AgentAdapter = {excerpt,parseHookInput,+ isHeadless,additionalContext,userNotice,diff --git a/packages/cli/src/agents/types.ts b/packages/cli/src/agents/types.tsindex f323bde..9e0302d 100644--- a/packages/cli/src/agents/types.ts+++ b/packages/cli/src/agents/types.ts@@ -135,6 +135,8 @@ export interface AgentAdapter {excerpt(text: string, max?: number): string;/** Parses a hook's stdin; undefined when it is not a payload cogit understands. */parseHookInput(stdin: string): HookInput | undefined;+ /** Whether the hook runs in a session started without a person (`claude -p`, an SDK). */+ isHeadless(env: NodeJS.ProcessEnv): boolean;/** Hook output that adds context for the agent, in the agent's own protocol. */additionalContext(event: string, text: string): Record<string, unknown>;/** A hook answer that shows one line to the user, not to the agent. */diff --git a/packages/cli/src/hooks/run.ts b/packages/cli/src/hooks/run.tsindex 9448634..86c8b41 100644--- a/packages/cli/src/hooks/run.ts+++ b/packages/cli/src/hooks/run.ts@@ -6,6 +6,7 @@ import { type AgentAdapter, defaultAgent, type HookInput } from "../agents/indeximport { Slug } from "../schema/common.js";import { captureDisabled, projectPaths } from "../store/paths.js";import { resolveProjectRoot } from "../store/root.js";+import { loadConfig } from "../store/stores.js";import { onPreToolUse } from "./pretooluse.js";import { onPromptSubmit } from "./promptsubmit.js";import { onSessionEnd } from "./sessionend.js";@@ -126,6 +127,8 @@ export async function runHook(await agent.markLive(input.session_id).catch((err: Error) => debug(`cogit mark: ${err.message}`));+ // A session nobody types into is left alone unless the user asked for it.+ if (agent.isHeadless(env) && !(await loadConfig(env)).recordHeadless) return undefined;// In a linked worktree both point at the worktree; the record lives in the main checkout.const { root } = await resolveProjectRoot(env[agent.projectDirEnv] ?? input.cwd ?? ".");const initialized = existsSync(projectPaths(root).project);diff --git a/packages/cli/src/schema/config.ts b/packages/cli/src/schema/config.tsindex 685c81c..ef80f3a 100644--- a/packages/cli/src/schema/config.ts+++ b/packages/cli/src/schema/config.ts@@ -39,6 +39,12 @@ export const Config = z.object({* how to read the record (`log` / `show`). On by default; costs only tokens.*/startupContext: z.boolean().default(true),+ /**+ * Whether sessions started without a person (`claude -p`, an SDK) are recorded.+ * Off by default: other plugins start them in the background, one per prompt,+ * and they would fill the map and the inbox.+ */+ recordHeadless: z.boolean().default(false),/** Port the local map server binds on `127.0.0.1`. */serverPort: z.int().min(1).max(65535).default(4747),/** Default for new projects; `init` asks per repo. Story 9.3: the record travels. */diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.tsindex fc46371..bcfcc54 100644--- a/packages/cli/src/view/model.ts+++ b/packages/cli/src/view/model.ts@@ -33,6 +33,7 @@ export const PANEL_EDITABLE_KEYS = ["recorder","messageSummaries","startupContext",+ "recordHeadless","tryBeforeNotes","language","updateEveryTurns",@@ -387,6 +388,8 @@ export interface PanelSettings {sideModel: string;messageSummaries: boolean;startupContext: boolean;+ /** Whether `claude -p` and SDK sessions are recorded. */+ recordHeadless: boolean;/*** Whether the agent is told before editing a file about options earlier* thoughts considered and rejected (Story 10.4).diff --git a/packages/cli/src/view/panel.ts b/packages/cli/src/view/panel.tsindex b813060..68fc491 100644--- a/packages/cli/src/view/panel.ts+++ b/packages/cli/src/view/panel.ts@@ -67,6 +67,7 @@ export function panelSettings(config: Config): PanelSettings {sideModel: config.sideModel,messageSummaries: config.messageSummaries,startupContext: config.startupContext,+ recordHeadless: config.recordHeadless,tryBeforeNotes: config.tryBeforeNotes,shareConversations: config.shareConversations,recordCommit: config.recordCommit,diff --git a/packages/cli/src/view/settings.ts b/packages/cli/src/view/settings.tsindex 2c6788f..856f752 100644--- a/packages/cli/src/view/settings.ts+++ b/packages/cli/src/view/settings.ts@@ -85,6 +85,16 @@ const EDITABLE: FieldSpec[] = ["are unrelated.",kind: "boolean",},+ {+ key: "recordHeadless",+ label: "Headless sessions",+ help: "Record sessions that start without a person, such as `claude -p`.",+ details:+ "Some plugins and scripts run `claude -p` in the background, often once per prompt. " ++ "Off, cogit leaves those sessions out of the map and the inbox. Turn it on if you do " ++ "real work through `claude -p` or the SDK and want it recorded.",+ kind: "boolean",+ },{key: "tryBeforeNotes",label: "Tried-before notes",@@ -260,6 +270,7 @@ export const DEFAULT_SETTINGS: PanelSettings = {sideModel: "haiku",messageSummaries: false,startupContext: true,+ recordHeadless: false,tryBeforeNotes: true,shareConversations: false,recordCommit: "ask",@@ -278,6 +289,7 @@ export function editableSettings(settings: PanelSettings): PanelEditableSettingsrecorder: settings.recorder,messageSummaries: settings.messageSummaries,startupContext: settings.startupContext,+ recordHeadless: settings.recordHeadless,tryBeforeNotes: settings.tryBeforeNotes,language: settings.language,updateEveryTurns: settings.updateEveryTurns,diff --git a/packages/cli/test/hooks.test.ts b/packages/cli/test/hooks.test.tsindex 2bdcfb5..5acaf30 100644--- a/packages/cli/test/hooks.test.ts+++ b/packages/cli/test/hooks.test.ts@@ -296,6 +296,19 @@ describe("runHook", () => {expect(await sessionStart("clear")).toBeUndefined();});+ it("leaves `claude -p` sessions alone unless recordHeadless is on", async () => {+ const headless = { ...env, CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };+ expect(await sessionStart("startup", headless)).toBeUndefined();+ await initialized(1);+ expect(await sessionStart("startup", headless)).toBeUndefined();+ expect(await stop({}, headless)).toBeUndefined();+ expect(spawned).toEqual([]);+ await configSet("recordHeadless", "true", fakeIo(env));+ expect(await sessionStart("startup", headless)).toContain("records this project's lineage");+ await stop({}, headless);+ expect(spawned).not.toEqual([]);+ });+it("silences the setup hint per project with hint-off and undoes it with hint-on", async () => {const off = fakeIo(env);await configHintOff(root, off);diff --git a/packages/cli/test/panel.test.ts b/packages/cli/test/panel.test.tsindex f53240a..5f880ba 100644--- a/packages/cli/test/panel.test.ts+++ b/packages/cli/test/panel.test.ts@@ -89,6 +89,7 @@ describe("buildPanel", () => {sideModel: "haiku",messageSummaries: false,startupContext: true,+ recordHeadless: false,tryBeforeNotes: true,shareConversations: false,recordCommit: "ask",diff --git a/packages/cli/test/server.test.ts b/packages/cli/test/server.test.tsindex 4e0a41c..b9cccdd 100644--- a/packages/cli/test/server.test.ts+++ b/packages/cli/test/server.test.ts@@ -550,6 +550,7 @@ describe("settings read", () => {recorder: "mixed",messageSummaries: false,startupContext: true,+ recordHeadless: false,tryBeforeNotes: true,language: "auto",updateEveryTurns: 15,diff --git a/packages/cli/test/settings.test.ts b/packages/cli/test/settings.test.tsindex 4255cd1..e114e86 100644--- a/packages/cli/test/settings.test.ts+++ b/packages/cli/test/settings.test.ts@@ -23,6 +23,7 @@ describe("settings model", () => {sideModel: parsed.sideModel,messageSummaries: parsed.messageSummaries,startupContext: parsed.startupContext,+ recordHeadless: parsed.recordHeadless,tryBeforeNotes: parsed.tryBeforeNotes,shareConversations: parsed.shareConversations,recordCommit: parsed.recordCommit,@@ -67,6 +68,7 @@ describe("settings model", () => {recorder: "mixed",messageSummaries: false,startupContext: true,+ recordHeadless: false,tryBeforeNotes: true,language: "tr",updateEveryTurns: 8,diff --git a/packages/template/src/fixture.ts b/packages/template/src/fixture.tsindex 42ea81b..970d3d3 100644--- a/packages/template/src/fixture.ts+++ b/packages/template/src/fixture.ts@@ -60,6 +60,7 @@ export const fixture: LineageViewModel = {sideModel: "haiku",messageSummaries: false,startupContext: true,+ recordHeadless: false,tryBeforeNotes: true,shareConversations: false,recordCommit: "ask",