@sayansr26/agent-os 0.6.1 → 0.6.3

package/plugins/auto-handoff/tests/seed-row.test.tsx

@@ -0,0 +1,58 @@
+import { test, expect } from 'claude-code/testing'
+import { linkify } from '../hooks/config.ts'
+
+const PLUGIN = 'auto-handoff'
+const PATH = '/home/me/.claude/state/auto-handoff/dbd019e5-410b-4d91-8db9-6755b2924e48.md'
+const URL = 'http://100.85.122.99:3846/dbd019e5-410b-4d91-8db9-6755b2924e48.html'
+const SEED = `[auto-handoff] ↪ Handoff from session dbd019e5. The previous session hit its context limit and was cleared. Read the brief at ${PATH} before doing anything else (readable copy: ${URL}) and follow its Instructions section. Open your first reply with the line "↪ Handoff from session dbd019e5".`
+
+const row = (text: string, origin: Record<string, unknown>) => ({
+  component: 'UserMessage' as const,
+  props: { text, origin, isExpanded: false } as never,
+})
+
+test('linkify turns the brief path and viewer URL into markdown links', async () => {
+  const out = linkify(SEED)
+  expect(out).toContain(`[dbd019e5-410b-4d91-8db9-6755b2924e48.md](file://${PATH})`)
+  expect(out).toContain(`[${URL}](${URL})`)
+  // Everything else stays as written.
+  expect(out.startsWith('[auto-handoff] ↪ Handoff from session dbd019e5.')).toBe(true)
+  expect(out).toContain('follow its Instructions section.')
+})
+
+test('linkify leaves a seed with no viewer link alone except for the path', async () => {
+  const text = `[auto-handoff] ↪ Handoff from session abc. Read the brief at ${PATH} before doing anything else and follow its Instructions section.`
+  const out = linkify(text)
+  expect(out).toContain(`(file://${PATH})`)
+  expect(out).not.toContain('http')
+})
+
+test('the seed row draws as a Markdown with clickable links on every surface', async $ => {
+  for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
+    const ui = await $.ui.mount({ plugin: PLUGIN, surface, ...row(SEED, { kind: 'plugin', name: PLUGIN }) })
+    const md = await ui.find({ type: 'Markdown' })
+    expect(md).toBeDefined()
+    expect(md?.text).toContain(`(file://${PATH})`)
+    expect(md?.text).toContain(`[${URL}](${URL})`)
+    await ui.unmount()
+  }
+})
+
+test('rows from other plugins or the person are left to the engine', async ($, on) => {
+  // Stands for the engine's own drawing beneath the plugin: a plain Text of the row.
+  on('ui.render', { component: 'UserMessage' }, async ($, e) => {
+    const { Text } = $.ui.resolve(e)
+    return <Text>{e.props.text}</Text>
+  })
+  const cases: Array<[string, Record<string, unknown>]> = [
+    [SEED, { kind: 'plugin', name: 'some-other-plugin' }],
+    [SEED, { kind: 'composer' }],
+    ['[auto-handoff] Not run: the context is past the handoff threshold.', { kind: 'plugin', name: PLUGIN }],
+  ]
+  for (const [text, origin] of cases) {
+    const ui = await $.ui.mount({ plugin: PLUGIN, surface: 'terminal', ...row(text, origin) })
+    expect(await ui.find({ type: 'Markdown' })).toBeUndefined()
+    expect((await ui.find({ type: 'Text' }))?.text).toBe(text)
+    await ui.unmount()
+  }
+})

package/plugins/auto-handoff/tests/viewer.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'claude-code/testing'
+import { chainOf, parseBrief, renderPage, sections, viewerLink, withHeader } from '../hooks/viewer.ts'
+import { SERVER_JS } from '../hooks/server.ts'
+
+describe('viewer', () => {
+  test('parseBrief extracts header and body', () => {
+    const brief = `---
+from: abc123
+to: def456
+chain: main-chain
+tokens: 150000
+at: 2026-10-04T12:00:00Z
+cwd: /home/user/project
+---
+## Work in Progress
+Building the viewer.
+
+## Next Step
+Test it.`
+    const { header, body } = parseBrief(brief)
+    expect(header.from).toBe('abc123')
+    expect(header.chain).toBe('main-chain')
+    expect(body).toContain('## Work in Progress')
+  })
+
+  test('parseBrief handles briefs with no header', () => {
+    const brief = `## Work in Progress\nDoing stuff`
+    const { header, body } = parseBrief(brief)
+    expect(header).toEqual({})
+    expect(body).toBe(brief)
+  })
+
+  test('withHeader round-trips a brief', () => {
+    const header = { from: 'abc', to: 'def', tokens: '150000' }
+    const body = '## Work\nStuff'
+    const result = withHeader(header, body)
+    const { header: h2, body: b2 } = parseBrief(result)
+    expect(h2.from).toBe('abc')
+    expect(h2.to).toBe('def')
+    expect(b2).toBe(body)
+  })
+
+  test('viewerLink is the short served link, or the local file with no server', () => {
+    expect(viewerLink({ host: '100.64.0.1', port: '3846' }, '/pages', 'abc12345')).toBe('http://100.64.0.1:3846/abc12345')
+    expect(viewerLink(undefined, '/pages', 'abc12345')).toBe('file:///pages/abc12345.html')
+    expect(viewerLink(undefined, 'C:\\Users\\x/.claude/pages', 'abc12345')).toBe('file:///C:/Users/x/.claude/pages/abc12345.html')
+  })
+
+  test('renderPage links the chain and escapes a brief that tries to close the script tag', () => {
+    const a = { id: 'aaaaaaaa-1', header: { chain: 'aaaaaaaa-1', at: '2026-10-04T00:00:00Z', to: 'bbbbbbbb-2' }, body: '## Work in Progress\nFirst.' }
+    const b = { id: 'bbbbbbbb-2', header: { chain: 'aaaaaaaa-1', from: 'aaaaaaaa-1', at: '2026-10-04T01:00:00Z' }, body: '## Next Step\n</script><b>x</b>' }
+    const page = renderPage(b, [a, b])
+    expect(page).toContain('href="aaaaaaaa-1.html"')
+    expect(page).toContain('Handoff Chain')
+    expect(page).not.toContain('</script><b>')
+  })
+
+  test('previous and next follow the chain, even where a header lost its from', () => {
+    const e = (id: string, at: string, header: Record<string, string>) => ({ id, header: { at, ...header }, body: '' })
+    const a = e('aaaaaaaa-1', '1', { to: 'bbbbbbbb-2' })
+    const b = e('bbbbbbbb-2', '2', { to: 'cccccccc-3' }) // a reload dropped its from
+    const c = e('cccccccc-3', '3', { from: 'bbbbbbbb-2', to: 'dddddddd-4' })
+    const mid = renderPage(b, [a, b, c])
+    expect(mid).toContain('<a href="aaaaaaaa-1.html">← previous</a>')
+    expect(mid).toContain('<a href="cccccccc-3.html">next →</a>')
+    const last = renderPage(c, [a, b, c])
+    expect(last).toContain('next: dddddddd, still running')
+    expect(last).not.toContain('href="dddddddd-4.html"')
+    expect(renderPage(a, [a, b, c])).not.toContain('← previous')
+  })
+
+  test('sections extracts visible sections', () => {
+    const body = `## Work in Progress
+Doing X
+
+## Instructions
+Don't read this
+
+## Next Step
+Do Y
+
+## How to Use This Brief
+Also don't read`
+    const visible = sections(body)
+    expect(visible.length).toBe(2)
+    expect(visible[0]).toContain('Work in Progress')
+    expect(visible[1]).toContain('Next Step')
+  })
+
+  test('chainOf joins a run whose chain id broke partway, through from/to links', () => {
+    const e = (id: string, at: string, header: Record<string, string>) => ({ id, header: { at, ...header }, body: '' })
+    const entries = [
+      e('a', '1', { chain: 'a', to: 'b' }),
+      e('b', '2', { chain: 'a', from: 'a', to: 'c' }),
+      e('c', '3', { chain: 'c', to: 'd' }), // the reload lost its from
+      e('d', '4', { chain: 'c', from: 'c' }),
+      e('x', '5', { chain: 'x' }),
+    ]
+    expect(chainOf(entries, 'd').map(x => x.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(chainOf(entries, 'a').map(x => x.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(chainOf(entries, 'x').map(x => x.id)).toEqual(['x'])
+  })
+
+  // A second session finds the port taken. Its child used to die with an unhandled EADDRINUSE
+  // stack trace in the log; it now says so in one line and exits 0. (Run live: see the 0.8.2 commit.)
+  test('the server exits quietly when the port is taken', () => {
+    expect(SERVER_JS).toContain("err.code === 'EADDRINUSE'")
+    expect(SERVER_JS).toContain('process.exit(0)')
+    expect(SERVER_JS.indexOf(".on('error'")).toBeLessThan(SERVER_JS.indexOf('.listen('))
+  })
+})

package/plugins/auto-handoff/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json",
+  "compilerOptions": { "allowImportingTsExtensions": true, "noEmit": true }
+}

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { setupState, describeState } from "../plugins/agent-os/skills/init/scrip
 import { applyScope, describe } from "./claude-setup.mjs";
 import { createInterface } from "node:readline/promises";
 import { compile, TARGETS } from "./targets.mjs";
+import { enabled as cursorEnabled } from "./cursor.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -35,11 +36,23 @@ Options
   --force        overwrite files agent-os did not generate (it refuses by default)
   --no-plugin    skip installing or updating the Claude Code plugins during init
   --no-auto-route
-                 init: install agent-os but not the auto-route model router
+                 init: leave out the auto-route model router
+  --no-auto-handoff
+                 init: leave out the auto-handoff session handoff
   --global       init: also write ~/.claude settings without asking
   --no-global    init: leave ~/.claude alone
 `;
 
+/** Will this init/sync compile for Claude Code? Mirrors how scaffold picks targets. */
+function claudeTargeted(root, found) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, DIR, "config.json"), "utf8"));
+    return (cfg.targets || []).includes("claude-code");
+  } catch {}
+  const present = found.filter((t) => t.present).map((t) => t.id);
+  return present.includes("claude-code") || !present.length;
+}
+
 function scaffold(root, found) {
   const present = found.filter((t) => t.present).map((t) => t.id);
   mkdirSync(join(root, DIR, "rules"), { recursive: true });
@@ -93,6 +106,17 @@ export async function main(argv) {
 
   if (cmd === "help" || argv.includes("-h") || argv.includes("--help")) { console.log(USAGE); return; }
 
+  // A repository Rulegate owns: init would adopt Rulegate's generated CLAUDE.md and
+  // AGENTS.md as this tool's source, and every write after that fights `rulegate check`.
+  // That happened to Rulegate's own repository (its T112), so both writers stop here.
+  if ((cmd === "init" || cmd === "sync") && existsSync(join(root, ".rulegate"))) {
+    console.error(`\n  This repository uses Rulegate (.rulegate/ exists), which replaces agent-os.`);
+    console.error(`  agent-os ${cmd} would treat Rulegate's generated files as its source. Nothing was written.`);
+    console.error(`\n  Use ${bold("npx rulegate sync")} here instead.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   const found = detect(root);
 
   if (cmd === "detect") {
@@ -139,18 +163,24 @@ export async function main(argv) {
   let adopted = new Set();
 
   let before = null;
+  // The SETUP state is Claude Code's: CLAUDE.md, .claude/settings.json, the
+  // plugin. In a project that does not target Claude Code every item reads
+  // MISSING and the verdict never leaves REPAIR, so it is not shown there.
+  const forClaude = claudeTargeted(root, found);
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
     // Decide fresh vs repair before touching anything, and say which, so a
     // second run on a set-up project reads as a repair rather than a re-init.
     before = setupState(root);
-    for (const l of describeState(before)) console.log(`  ${l}`);
-    console.log({
-      fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
-      repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
-      healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
-    }[before.status]);
-    console.log("");
+    if (forClaude) {
+      for (const l of describeState(before)) console.log(`  ${l}`);
+      console.log({
+        fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
+        repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
+        healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
+      }[before.status]);
+      console.log("");
+    }
     console.log(summarise(found));
     const hadSource = existsSync(join(root, DIR));
     const { present, taken } = scaffold(root, found);
@@ -207,7 +237,7 @@ export async function main(argv) {
       const cur = readIfExists(root, f.path);
       if (cur === null) return true;                       // nothing there yet
       if (cur.includes(BANNER)) return true;               // we wrote it
-      if (TARGETS[f.target]?.merge) return true;           // merged in place, nothing lost
+      if (f.merged) return true;                           // merged in place, nothing lost
       if (adopted.has(f.path)) return true;                // init just took this as the source
       if (matches(root, f.path, f.content) === true) return true; // already identical
       return false;
@@ -267,7 +297,7 @@ Pick one:
     }
 
     if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
-      // Both come from the same marketplace, so it is added or refreshed once:
+      // All come from the same marketplace, so it is added or refreshed once:
       // by the first plugin whose run gets that far.
       let refresh = true;
       for (const plugin of PLUGINS.filter((p) => p === PLUGIN || !argv.includes(`--no-${p}`))) {
@@ -285,10 +315,25 @@ Pick one:
         if (r.reason === "installed" || r.reason === "updated")
           console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
       }
-      console.log(`\n  ${dim("--no-plugin skips this; --no-auto-route skips only the model router")}`);
+      console.log(`\n  ${dim("--no-plugin skips this; --no-auto-route / --no-auto-handoff skip one mod")}`);
+    }
+
+    if (cmd !== "check" && targets.includes("cursor") && cursorEnabled(src.config)) {
+      const n = (re) => files.filter((f) => re.test(f.path)).length;
+      console.log(`\n${bold("Cursor")}  ${dim("agent-os layer, compiled from this package")}\n`);
+      console.log(`  ${n(/^\.cursor\/agents\/agent-os-/)} subagents     agent-os-feature-cartographer, -architect, -builder, -tester, -reviewer, …`);
+      console.log(`  ${n(/^\.cursor\/skills\/agent-os-[^/]+\/SKILL\.md$/)} skills        /agent-os-init, /agent-os-map, /agent-os-memory`);
+      console.log(`  hooks           session start, generated-file guard${src.config.cursor?.gitProtection === false ? "" : ", git write protection"}  ${dim("(.cursor/hooks.json)")}`);
+      console.log(`  agent memory    .claude/agent-memory/agent-os-<agent>/  ${dim("— shared with Claude Code")}`);
+      if (cmd === "init") console.log(`\n  ${dim("Reload the Cursor window, then run /agent-os-init in Agent chat.")}`);
+    }
+
+    if (cmd === "init" && !dry && !forClaude) {
+      const labels = targets.map((t) => TARGETS[t]?.label || t);
+      console.log(`\n${bold("Result")}  ${labels.length ? `compiled for ${labels.join(", ")}` : "AGENTS.md only"}`);
     }
 
-    if (cmd === "init" && !dry) {
+    if (cmd === "init" && !dry && forClaude) {
       const after = setupState(root);
       console.log(`\n${bold("Result")}  ${before.status} → ${after.status}`);
       if (after.missing.length) {

package/src/cursor.mjs

@@ -0,0 +1,167 @@
+/**
+ * The agent-os layer for Cursor: the same agents, skills and hooks the Claude
+ * Code plugin ships, compiled into the places Cursor reads them.
+ *
+ *   .cursor/agents/agent-os-<name>.md        the seven agents, as subagents
+ *   .cursor/skills/agent-os-{init,map,memory}/  the three skills
+ *   .cursor/hooks/agent-os/                  the session and pre-edit hooks, plus
+ *                                            git write protection
+ *   .cursor/hooks.json                       merged: user hooks are kept
+ *   .cursor/rules/agent-os-agents.mdc        when to use which agent, always on
+ *
+ * Everything is generated from this package, never from `.agent-os/`, so `sync`
+ * keeps it current the way `claude plugin update` does for Claude Code.
+ *
+ * Agent memory stays in `.claude/agent-memory/agent-os-<name>/`: the directory
+ * Claude Code's plugin agents use, so a project on both tools has one map.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BANNER, parseFrontmatter } from "./source.mjs";
+import { GIT_DENY } from "../plugins/agent-os/skills/init/scripts/settings.mjs";
+
+const PKG = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const PLUGIN = join(PKG, "plugins/agent-os");
+const OWN = join(PKG, "cursor");
+const HOOKS = ".cursor/hooks/agent-os";
+
+const read = (p) => readFileSync(p, "utf8");
+const md = (fields, body) => `---\n${fields}---\n\n<!-- ${BANNER} -->\n\n${body.trim()}\n`;
+const js = (text) => text.startsWith("#!")
+  ? text.replace(/^(#!.*\n)/, `$1// ${BANNER}\n`)
+  : `// ${BANNER}\n${text}`;
+
+/** `{ "cursor": { "agentOs": false } }` turns the whole layer off. */
+export const enabled = (config) => config?.cursor?.agentOs !== false;
+const gitGuard = (config) => config?.cursor?.gitProtection !== false;
+
+/** Claude Code names and commands, rewritten to what this layer installs. */
+export function translate(text) {
+  return text
+    .replace(/agent-os:([a-z][a-z-]*)/g, "agent-os-$1")
+    .replace(/node "\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/\w+\/scripts\/(\w+)\.mjs"/g, "npx -y @sayansr26/agent-os $1");
+}
+
+/** A description is what the parent reads to pick a subagent, so it names Cursor's files. */
+const describe = (d) => JSON.stringify(translate(String(d || ""))
+  .replace(/CLAUDE\.md/g, "AGENTS.md").replace(/\.claude\/rules\//g, ".cursor/rules/"));
+
+const READ_AS = `> **Running in Cursor.** This text was written for Claude Code. Read it as:
+> \`CLAUDE.md\` → \`AGENTS.md\` (edit \`.agent-os/AGENTS.md\`, then \`npx @sayansr26/agent-os sync\`);
+> \`.claude/rules/\` → \`.cursor/rules/\` (edit \`.agent-os/rules/\`, then sync);
+> an agent \`<name>\` → the \`agent-os-<name>\` subagent; \`/agent-os:<skill>\` → \`/agent-os-<skill>\`;
+> "the Agent tool" or "dispatch" → delegate to that subagent.`;
+
+function agents() {
+  const dir = join(PLUGIN, "agents");
+  return readdirSync(dir).filter((f) => f.endsWith(".md")).sort().map((f) => {
+    const { fields, body } = parseFrontmatter(read(join(dir, f)));
+    const name = `agent-os-${fields.name}`;
+    // Claude Code creates the memory directory and preloads MEMORY.md for an
+    // agent with `memory: project`. Cursor does neither, so the agent is told.
+    const memory = `> **Your memory directory** is \`.claude/agent-memory/${name}/\` at the project root
+> (shared with Claude Code's agent-os agents). Create it if it does not exist. Cursor does
+> not load \`MEMORY.md\` for you — read it yourself before anything else.
+>
+${READ_AS}`;
+    return {
+      path: `.cursor/agents/${name}.md`,
+      content: md(
+        `name: ${name}\ndescription: ${describe(fields.description)}\nmodel: inherit\n`,
+        `${memory}\n\n${translate(body)}`),
+    };
+  });
+}
+
+function skills() {
+  const out = [];
+  const refs = join(PLUGIN, "skills/init/references");
+  // init is rewritten for Cursor; its references are shared, read through the table.
+  {
+    const { fields, body } = parseFrontmatter(read(join(OWN, "skills/agent-os-init/SKILL.md")));
+    out.push({ path: ".cursor/skills/agent-os-init/SKILL.md",
+      content: md(`name: ${fields.name}\ndescription: ${JSON.stringify(fields.description)}\n`, body) });
+    for (const f of readdirSync(refs).filter((f) => f.endsWith(".md")).sort())
+      out.push({ path: `.cursor/skills/agent-os-init/references/${f}`,
+        content: `<!-- ${BANNER} -->\n\n${READ_AS}\n\n${translate(read(join(refs, f))).trim()}\n` });
+  }
+  // map and memory carry over as they are, renamed. Their scripts run through
+  // the CLI, which bundles the same files, so no script is copied.
+  for (const s of ["map", "memory"]) {
+    const { fields, body } = parseFrontmatter(read(join(PLUGIN, "skills", s, "SKILL.md")));
+    out.push({ path: `.cursor/skills/agent-os-${s}/SKILL.md`,
+      content: md(`name: agent-os-${s}\ndescription: ${describe(fields.description)}\n`, `${READ_AS}\n\n${translate(body)}`) });
+  }
+  return out;
+}
+
+function hookScripts(config) {
+  const out = [
+    { path: `${HOOKS}/hooks/session-resume.mjs`, content: js(read(join(PLUGIN, "hooks/session-resume.mjs"))) },
+    { path: `${HOOKS}/hooks/pre-edit.mjs`, content: js(read(join(PLUGIN, "hooks/pre-edit.mjs"))) },
+    { path: `${HOOKS}/lib/features.mjs`, content: js(read(join(PLUGIN, "lib/features.mjs"))) },
+  ];
+  if (gitGuard(config)) out.push(
+    { path: `${HOOKS}/hooks/git-guard.mjs`, content: js(read(join(OWN, "hooks/git-guard.mjs"))) },
+    { path: `${HOOKS}/lib/git-deny.mjs`,
+      content: js(`/** The same rules Claude Code gets as permissions.deny (settings.mjs). */\nexport const GIT_DENY = ${JSON.stringify(GIT_DENY, null, 2)};\n`) },
+  );
+  return out;
+}
+
+/** The agent contract, always on — the Cursor half of CLAUDE.md's Step 4b section. */
+const contract = () => ({
+  path: ".cursor/rules/agent-os-agents.mdc",
+  content: md("description: When to use each agent-os subagent\nalwaysApply: true\n", `## Agents in this project (agent-os)
+
+Delegate to these subagents without being asked:
+
+- Before changing an existing feature: ask \`agent-os-feature-cartographer\` how
+  it is built. In plan mode ask it read-only, and have it file the map as the
+  first step after plan mode ends.
+- New subsystem, cross-module change, shared data model: \`agent-os-architect\` first.
+- Writing the change: \`agent-os-builder\`, given the map and the files to change.
+- Done means: \`agent-os-tester\` verified it and \`agent-os-reviewer\` found no
+  rule violations.
+- Once verified: \`agent-os-documenter\` records it.
+- Work spanning several of these, or that cannot be stated in one sentence:
+  \`agent-os-orchestrator\`.
+
+\`/agent-os-map\` builds the architecture map, \`/agent-os-memory\` inspects agent
+memory, \`/agent-os-init\` sets up or repairs all of this.
+
+Generated files carry a banner. Edit \`.agent-os/\`, then run
+\`npx @sayansr26/agent-os sync\`; never edit the output.`),
+});
+
+/** Every file of the layer except hooks.json. */
+export function cursorFiles(src) {
+  if (!enabled(src.config)) return [];
+  return [...agents(), ...skills(), ...hookScripts(src.config), contract()];
+}
+
+const OURS = (h) => String(h?.command || "").includes(`${HOOKS}/`);
+
+/**
+ * Merge the agent-os hooks into `.cursor/hooks.json`. Hooks the user wrote are
+ * kept; earlier agent-os entries are replaced, so a removed hook goes away.
+ */
+export function mergeHooks(src, existing) {
+  if (!existing && !enabled(src.config)) return [];
+  const cfg = existing ? JSON.parse(existing) : { version: 1, hooks: {} };
+  cfg.version ||= 1;
+  cfg.hooks ||= {};
+  for (const ev of Object.keys(cfg.hooks)) {
+    cfg.hooks[ev] = (cfg.hooks[ev] || []).filter((h) => !OURS(h));
+    if (!cfg.hooks[ev].length) delete cfg.hooks[ev];
+  }
+  if (enabled(src.config)) {
+    const add = (ev, h) => (cfg.hooks[ev] ||= []).push(h);
+    add("sessionStart", { command: `node ${HOOKS}/hooks/session-resume.mjs --cursor` });
+    add("preToolUse", { command: `node ${HOOKS}/hooks/pre-edit.mjs --cursor`, matcher: "Write" });
+    if (gitGuard(src.config))
+      add("beforeShellExecution", { command: `node ${HOOKS}/hooks/git-guard.mjs`, matcher: "\\bgit\\b" });
+  }
+  return [{ path: ".cursor/hooks.json", content: JSON.stringify(cfg, null, 2) + "\n" }];
+}

package/src/plugin.mjs

@@ -2,9 +2,10 @@
  * Install or update the Claude Code half of agent-os during `init`.
  *
  * The CLI compiles rules for every tool. Claude Code additionally gets the
- * agents, skills, per-agent memory and hooks, which ship as a plugin, and
- * auto-route, a mod that picks the model and effort per turn. Both live in
- * this repo's marketplace. `init` brings each to the latest version whatever
+ * agents, skills, per-agent memory and hooks, which ship as a plugin; plus two
+ * mods: auto-route, which picks the model and effort per turn, and
+ * auto-handoff, which hands a full session to a fresh one instead of
+ * compacting. All three live in this repo's marketplace. `init` brings each to the latest version whatever
  * state it finds:
  *
  *   not installed        marketplace add + install, at project scope
@@ -28,7 +29,7 @@ export const MARKETPLACE = "sayansr26/agent-os";
 export const MARKETPLACE_NAME = "sayan-plugins";
 export const PLUGIN = "agent-os";
 // Installed by `init` in this order; each can be skipped with --no-<name>.
-export const PLUGINS = [PLUGIN, "auto-route"];
+export const PLUGINS = [PLUGIN, "auto-route", "auto-handoff"];
 const idOf = (plugin) => `${plugin}@${MARKETPLACE_NAME}`;
 
 const run = (args, cwd) =>

package/src/selftest.mjs

@@ -57,6 +57,39 @@ try {
   ok(read(".claude/skills/demo/SKILL.md") !== null, "skills -> .claude/skills");
   ok(read(".cline/skills/demo/SKILL.md") !== null, "skills -> .cline/skills");
 
+  console.log("\n  Cursor gets the agent-os layer");
+  {
+    const agents = ["architect", "builder", "documenter", "feature-cartographer", "orchestrator", "reviewer", "tester"];
+    ok(agents.every((a) => read(`.cursor/agents/agent-os-${a}.md`)?.startsWith(`---\nname: agent-os-${a}\n`)), "7 subagents in .cursor/agents/, Cursor-legal names");
+    const carto = read(".cursor/agents/agent-os-feature-cartographer.md");
+    ok(carto.includes(".claude/agent-memory/agent-os-feature-cartographer/"), "subagent memory shared with Claude Code's directory");
+    ok(!/agent-os:[a-z]/.test(carto) && !/^memory:|^tools:/m.test(carto), "no Claude-only names or frontmatter left");
+    ok(["init", "map", "memory"].every((s) => read(`.cursor/skills/agent-os-${s}/SKILL.md`)?.includes(`name: agent-os-${s}\n`)), "skills /agent-os-init, -map, -memory");
+    ok(!read(".cursor/skills/agent-os-memory/SKILL.md").includes("CLAUDE_PLUGIN_ROOT"), "skill scripts run through the CLI");
+    ok(read(".cursor/rules/agent-os-agents.mdc")?.includes("alwaysApply: true"), "agent contract is an always-on rule");
+    const hooks = JSON.parse(read(".cursor/hooks.json"));
+    ok(hooks.version === 1 && hooks.hooks.sessionStart && hooks.hooks.preToolUse && hooks.hooks.beforeShellExecution, "hooks.json: sessionStart, preToolUse, beforeShellExecution");
+
+    const hook = (script, args, input) => spawnSync(process.execPath, [join(root, ".cursor/hooks/agent-os/hooks", script), ...args],
+      { cwd: root, encoding: "utf8", input, env: { ...process.env, CURSOR_PROJECT_DIR: root } }).stdout;
+    const start = JSON.parse(hook("session-resume.mjs", ["--cursor"], ""));
+    ok(start.additional_context?.includes("`agent-os-feature-cartographer`"), "session start returns additional_context with Cursor names");
+    const pre = (file) => JSON.parse(hook("pre-edit.mjs", ["--cursor"], JSON.stringify({ tool_input: { file_path: join(root, file) } })));
+    ok(pre(".cursor/rules/api.mdc").permission === "deny", "pre-edit denies an edit to a generated rule");
+    ok(pre(".cursor/agents/agent-os-builder.md").permission === "deny", "pre-edit denies an edit to a generated subagent");
+    ok(pre("src/new.ts").permission === "allow", "pre-edit answers allow, never empty, for everything else");
+    const git = (command) => JSON.parse(hook("git-guard.mjs", [], JSON.stringify({ command }))).permission;
+    ok(git("git status") === "allow" && git("git log --oneline") === "allow", "read-only git allowed");
+    ok(["git push", "git commit -m x", "cd a && git reset --hard", "git -C x add .", "A=1 git rebase main"].every((c) => git(c) === "deny"), "git writes denied, chained and flag forms too");
+
+    writeFileSync(join(root, ".cursor/hooks.json"), JSON.stringify({ version: 1, hooks: { afterFileEdit: [{ command: "./fmt.sh" }] } }));
+    cli(["sync"], root);
+    const merged = JSON.parse(read(".cursor/hooks.json")).hooks;
+    ok(merged.afterFileEdit?.[0]?.command === "./fmt.sh" && merged.sessionStart?.length === 1, "hooks.json merged: user hook kept, ours added once");
+    cli(["sync"], root);
+    ok(JSON.parse(read(".cursor/hooks.json")).hooks.preToolUse.length === 1, "re-sync does not duplicate hooks");
+  }
+
   console.log("\n  drift");
   ok(cli(["check"], root).status === 0, "check passes when in sync");
   // Realistic drift: someone edits the body of a generated file and leaves the
@@ -102,10 +135,14 @@ try {
     ok(/marketplace add sayansr26\/agent-os|plugin marketplace add|not on PATH/.test(pi.stdout),
        "init names the marketplace step or says why it could not run it");
     ok(pi.stdout.includes("auto-route@sayan-plugins"), "init sets up auto-route by default");
+    ok(pi.stdout.includes("auto-handoff@sayan-plugins"), "init sets up auto-handoff by default");
     ok((pi.stdout.match(/marketplace add/g) || []).length <= 1, "the marketplace is added once, not per plugin");
     const na = cli(["init", "--dry-run", "--no-auto-route"], r4);
     ok(!/install auto-route@sayan-plugins/.test(na.stdout) && /install agent-os@sayan-plugins/.test(na.stdout),
        "--no-auto-route keeps agent-os and skips auto-route");
+    const nh = cli(["init", "--dry-run", "--no-auto-handoff"], r4);
+    ok(!/install auto-handoff@sayan-plugins/.test(nh.stdout) && /install auto-route@sayan-plugins/.test(nh.stdout),
+       "--no-auto-handoff skips only auto-handoff");
     rmSync(r4, { recursive: true, force: true });
 
     // A hand-written file at a generated path must survive a sync.
@@ -225,7 +262,34 @@ try {
   const oc = JSON.parse(read("opencode.json"));
   ok(oc.model === "anthropic/x", "existing keys preserved");
   ok(oc.instructions.includes("KEEP.md"), "existing instructions preserved");
-} finally { rmSync(root, { recursive: true, force: true }); rmSync(HOME, { recursive: true, force: true }); }
+} finally { rmSync(root, { recursive: true, force: true }); }
+
+console.log("\n  a Cursor-only init does not report Claude Code items");
+const cu = mkdtempSync(join(tmpdir(), "agent-os-cursor-"));
+try {
+  mkdirSync(join(cu, ".agent-os"), { recursive: true });
+  writeFileSync(join(cu, ".agent-os/config.json"), JSON.stringify({ targets: ["cursor"] }));
+  const r = cli(["init", "--no-global"], cu);
+  ok(r.status === 0, "init exits 0");
+  ok(!r.stdout.includes("SETUP") && !r.stdout.includes("still to do") && !r.stdout.includes("CLAUDE.md"), "no Claude Code SETUP or to-do list");
+  ok(/Result.*compiled for Cursor/.test(r.stdout) && r.stdout.includes("/agent-os-init"), "result names Cursor and the next step");
+  ok(!existsSync(join(cu, ".claude/settings.json")), "nothing written for Claude Code");
+  writeFileSync(join(cu, ".agent-os/config.json"), JSON.stringify({ targets: ["cursor"], cursor: { gitProtection: false } }));
+  cli(["sync"], cu);
+  ok(!JSON.parse(readFileSync(join(cu, ".cursor/hooks.json"), "utf8")).hooks.beforeShellExecution, "gitProtection: false removes the git hook");
+} finally { rmSync(cu, { recursive: true, force: true }); }
+
+console.log("\n  a Rulegate repository is left alone");
+const rg = mkdtempSync(join(tmpdir(), "agent-os-rulegate-"));
+try {
+  mkdirSync(join(rg, ".rulegate/rules"), { recursive: true });
+  writeFileSync(join(rg, "CLAUDE.md"), "<!-- Generated by Rulegate -->\n# Project\n");
+  for (const cmd of ["init", "sync"]) {
+    const r = cli([cmd, "--no-plugin", "--no-global"], rg);
+    ok(r.status === 1 && /uses Rulegate/.test(r.stderr), `${cmd} refuses with .rulegate/ present`);
+  }
+  ok(!existsSync(join(rg, ".agent-os")) && !existsSync(join(rg, "AGENTS.md")), "nothing written");
+} finally { rmSync(rg, { recursive: true, force: true }); rmSync(HOME, { recursive: true, force: true }); }
 
 console.log(`\n${fail ? `FAILED (${fail})` : "PASSED"}\n`);
 process.exit(fail ? 1 : 0);

package/src/targets.mjs

@@ -7,6 +7,7 @@
  * existing JSON config receive the current contents and return the merged file.
  */
 import { BANNER } from "./source.mjs";
+import { cursorFiles, mergeHooks } from "./cursor.mjs";
 
 const hdr = (comment) => `${comment} ${BANNER}\n`;
 const mdHeader = `<!-- ${BANNER} -->\n\n`;
@@ -54,13 +55,19 @@ export const TARGETS = {
   // ---- translate ----------------------------------------------------------
   cursor: {
     label: "Cursor",
-    // .mdc, and a rule without frontmatter is ignored entirely.
-    files: (src) => src.rules.map((r) => ({
-      path: `.cursor/rules/${r.name}.mdc`,
-      content: `---\ndescription: ${r.description || r.name}\n` +
-        (r.always ? "alwaysApply: true\n" : `globs: ${r.paths.join(",")}\nalwaysApply: false\n`) +
-        `---\n\n${mdHeader}${r.body}\n`,
-    })),
+    // .mdc, and a rule without frontmatter is ignored entirely. Then the
+    // agent-os layer — subagents, skills, hooks — which src/cursor.mjs builds.
+    files: (src) => [
+      ...src.rules.map((r) => ({
+        path: `.cursor/rules/${r.name}.mdc`,
+        content: `---\ndescription: ${r.description || r.name}\n` +
+          (r.always ? "alwaysApply: true\n" : `globs: ${r.paths.join(",")}\nalwaysApply: false\n`) +
+          `---\n\n${mdHeader}${r.body}\n`,
+      })),
+      ...cursorFiles(src),
+    ],
+    merge: mergeHooks,
+    mergeFrom: ".cursor/hooks.json",
   },
 
   windsurf: {
@@ -179,10 +186,10 @@ export function compile(src, targetIds, readExisting) {
   for (const id of targetIds) {
     const t = TARGETS[id];
     if (!t) continue;
-    const files = t.merge
-      ? t.merge(src, readExisting(t.mergeFrom))
-      : t.files(src);
-    out.push(...files.map((f) => ({ ...f, target: id })));
+    // A target writes files, merges into one existing config, or both. Merged
+    // files are marked: they are rewritten in place with nothing of the user's lost.
+    if (t.files) out.push(...t.files(src).map((f) => ({ ...f, target: id })));
+    if (t.merge) out.push(...t.merge(src, readExisting(t.mergeFrom)).map((f) => ({ ...f, target: id, merged: true })));
   }
   return out;
 }