feat(installer): add Kiro CLI/IDE target (#385) (#473)

`codegraph install` now detects and configures Kiro alongside the
existing seven agents. Writes `mcpServers.codegraph` to
`~/.kiro/settings/mcp.json` (global) or `./.kiro/settings/mcp.json`
(local), plus a dedicated `~/.kiro/steering/codegraph.md` /
`./.kiro/steering/codegraph.md` instruction file — Kiro's steering
system loads every `*.md` file in `steering/` as agent context, so a
dedicated file is the natural surface (no marker-based merging needed).

Sibling MCP servers in `mcp.json` and unrelated steering files
(`product.md`, `tech.md`, etc.) are preserved across install and
uninstall. Validated end-to-end on macOS, Linux (Docker node:22-bookworm
arm64), and Windows 11 (Parallels VM, Node 24): full installer-targets
suite passes (132 tests) on all three platforms, and live install /
idempotent re-run / uninstall round-trip works as expected.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -36,6 +36,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - The IDE shares `GEMINI.md` with Gemini CLI, so the two targets compose naturally when both are installed; the antigravity target deliberately doesn't touch `GEMINI.md` so uninstalling Antigravity alone leaves CLI instructions intact.
 
   Both targets are tested on the same parameterized contract as the existing five agents (idempotent install, sibling preservation, install/uninstall round-trip), with extra coverage for migration-marker detection, legacy → unified entry migration, sibling `disabled` field preservation, and the cross-target case where Gemini CLI and Antigravity IDE coexist in the same `~/.gemini/`. Closes #399.
+- **Installer target for Kiro (CLI + IDE).** `codegraph install` now detects and configures Kiro out of the box on macOS, Linux, and Windows. Writes `mcpServers.codegraph` to `~/.kiro/settings/mcp.json` (global) or `./.kiro/settings/mcp.json` (local), and the codegraph usage block into a dedicated `~/.kiro/steering/codegraph.md` / `./.kiro/steering/codegraph.md` — Kiro's steering system loads every `*.md` file in `steering/` as agent context, so a dedicated file is the natural surface (no marker-based merging required). Sibling MCP servers in `mcp.json` and unrelated steering files (`product.md`, `tech.md`, etc.) are preserved across install / uninstall. Tested on the same parameterized contract as the other agent targets (idempotent install, sibling preservation, install/uninstall round-trip). Closes #385.
 
 ## [0.9.5] - 2026-05-25
 

__tests__/installer-targets.test.ts

@@ -390,6 +390,84 @@ describe('Installer targets — partial-state idempotency', () => {
     expect(body).not.toContain('codegraph_callers');
   });
 
+  it('kiro: install writes settings/mcp.json (mcpServers.codegraph) and steering/codegraph.md', () => {
+    const kiro = getTarget('kiro')!;
+    const result = kiro.install('global', { autoAllow: true });
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    const steering = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    expect(result.files.some((f) => f.path === mcp)).toBe(true);
+    expect(result.files.some((f) => f.path === steering)).toBe(true);
+
+    const cfg = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toEqual({ type: 'stdio', command: 'codegraph', args: ['serve', '--mcp'] });
+
+    const md = fs.readFileSync(steering, 'utf-8');
+    expect(md).toContain('codegraph_callers');
+    expect(md).toContain('CodeGraph MCP server');
+  });
+
+  it('kiro: install preserves a pre-existing sibling MCP server in mcp.json', () => {
+    const kiro = getTarget('kiro')!;
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    fs.mkdirSync(path.dirname(mcp), { recursive: true });
+    fs.writeFileSync(mcp, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    kiro.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('kiro: uninstall strips codegraph but leaves sibling MCP servers intact', () => {
+    const kiro = getTarget('kiro')!;
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    fs.mkdirSync(path.dirname(mcp), { recursive: true });
+    fs.writeFileSync(mcp, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    kiro.install('global', { autoAllow: true });
+    kiro.uninstall('global');
+
+    const after = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeUndefined();
+  });
+
+  it('kiro: uninstall removes the steering codegraph.md file outright', () => {
+    const kiro = getTarget('kiro')!;
+    kiro.install('global', { autoAllow: true });
+    const steering = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    expect(fs.existsSync(steering)).toBe(true);
+
+    kiro.uninstall('global');
+    expect(fs.existsSync(steering)).toBe(false);
+  });
+
+  it('kiro: uninstall leaves a sibling steering file (product.md) untouched', () => {
+    const kiro = getTarget('kiro')!;
+    const sibling = path.join(tmpHome, '.kiro', 'steering', 'product.md');
+    fs.mkdirSync(path.dirname(sibling), { recursive: true });
+    fs.writeFileSync(sibling, '# Product\n\nMy team practices.\n');
+
+    kiro.install('global', { autoAllow: true });
+    kiro.uninstall('global');
+
+    expect(fs.existsSync(sibling)).toBe(true);
+    expect(fs.readFileSync(sibling, 'utf-8')).toContain('My team practices.');
+  });
+
+  it('kiro: local install writes ./.kiro/settings/mcp.json and ./.kiro/steering/codegraph.md', () => {
+    const kiro = getTarget('kiro')!;
+    const result = kiro.install('local', { autoAllow: true });
+    const paths = result.files.map((f) => f.path.replace(/\\/g, '/'));
+    expect(paths.some((p) => p.endsWith('/.kiro/settings/mcp.json'))).toBe(true);
+    expect(paths.some((p) => p.endsWith('/.kiro/steering/codegraph.md'))).toBe(true);
+  });
+
   it('antigravity: install writes to LEGACY ~/.gemini/antigravity/mcp_config.json when no migration marker', () => {
     const antigravity = getTarget('antigravity')!;
     antigravity.install('global', { autoAllow: true });
@@ -970,6 +1048,7 @@ describe('Installer targets — registry', () => {
     expect(getTarget('hermes')?.id).toBe('hermes');
     expect(getTarget('gemini')?.id).toBe('gemini');
     expect(getTarget('antigravity')?.id).toBe('antigravity');
+    expect(getTarget('kiro')?.id).toBe('kiro');
     expect(getTarget('not-a-real-target')).toBeUndefined();
   });
 

src/installer/index.ts

@@ -317,8 +317,8 @@ export async function runUninstaller(opts: RunUninstallerOptions): Promise<void>
     const sel = await clack.select({
       message: 'Remove CodeGraph from all your projects, or just this one?',
       options: [
-        { value: 'global' as const, label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes, ~/.gemini' },
-        { value: 'local'  as const, label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc, ./.gemini' },
+        { value: 'global' as const, label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes, ~/.gemini, ~/.kiro' },
+        { value: 'local'  as const, label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc, ./.gemini, ./.kiro' },
       ],
       initialValue: 'global' as const,
     });

src/installer/targets/kiro.ts

@@ -0,0 +1,177 @@
+/**
+ * Kiro CLI / IDE target. Writes:
+ *
+ *   - MCP server entry to `~/.kiro/settings/mcp.json` (global) or
+ *     `./.kiro/settings/mcp.json` (local). Standard `mcpServers.codegraph`
+ *     shape, same as Claude / Cursor / Gemini.
+ *   - Instructions to `~/.kiro/steering/codegraph.md` (global) or
+ *     `./.kiro/steering/codegraph.md` (local). Kiro's "steering" system
+ *     loads every `*.md` file in the steering dir as agent context, so
+ *     a dedicated `codegraph.md` is the natural surface — we own the
+ *     whole file outright (no marker-based merging needed) and delete
+ *     it on uninstall.
+ *
+ * No permissions concept — Kiro gates tool invocations through its own
+ * UI prompts rather than an external allowlist. `autoAllow` is silently
+ * ignored.
+ *
+ * Paths are identical on macOS / Linux / Windows because Kiro resolves
+ * its config root from `os.homedir()` on all three (Windows `~` →
+ * `%USERPROFILE%\.kiro`).
+ *
+ * Docs: https://kiro.dev/docs/cli/mcp/
+ *       https://kiro.dev/docs/cli/steering/
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import {
+  atomicWriteFileSync,
+  getMcpServerConfig,
+  jsonDeepEqual,
+  readJsonFile,
+  writeJsonFile,
+} from './shared';
+import { INSTRUCTIONS_TEMPLATE } from '../instructions-template';
+
+function configDir(loc: Location): string {
+  return loc === 'global'
+    ? path.join(os.homedir(), '.kiro')
+    : path.join(process.cwd(), '.kiro');
+}
+function mcpJsonPath(loc: Location): string {
+  return path.join(configDir(loc), 'settings', 'mcp.json');
+}
+function steeringPath(loc: Location): string {
+  return path.join(configDir(loc), 'steering', 'codegraph.md');
+}
+
+class KiroTarget implements AgentTarget {
+  readonly id = 'kiro' as const;
+  readonly displayName = 'Kiro';
+  readonly docsUrl = 'https://kiro.dev/docs/cli/mcp/';
+
+  supportsLocation(_loc: Location): boolean {
+    return true;
+  }
+
+  detect(loc: Location): DetectionResult {
+    const file = mcpJsonPath(loc);
+    const config = readJsonFile(file);
+    const alreadyConfigured = !!config.mcpServers?.codegraph;
+    const installed = loc === 'global'
+      ? fs.existsSync(configDir('global')) || fs.existsSync(file)
+      : fs.existsSync(file) || fs.existsSync(configDir('local'));
+    return { installed, alreadyConfigured, configPath: file };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    const files: WriteResult['files'] = [];
+    files.push(writeMcpEntry(loc));
+    files.push(writeSteeringEntry(loc));
+    return {
+      files,
+      notes: ['Restart Kiro for MCP changes to take effect.'],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    const files: WriteResult['files'] = [];
+
+    const file = mcpJsonPath(loc);
+    const config = readJsonFile(file);
+    if (config.mcpServers?.codegraph) {
+      delete config.mcpServers.codegraph;
+      if (Object.keys(config.mcpServers).length === 0) {
+        delete config.mcpServers;
+      }
+      writeJsonFile(file, config);
+      files.push({ path: file, action: 'removed' });
+    } else {
+      files.push({ path: file, action: 'not-found' });
+    }
+
+    files.push(removeSteeringEntry(loc));
+
+    return { files };
+  }
+
+  printConfig(loc: Location): string {
+    const target = mcpJsonPath(loc);
+    const snippet = JSON.stringify({ mcpServers: { codegraph: getMcpServerConfig() } }, null, 2);
+    return `# Add to ${target}\n\n${snippet}\n`;
+  }
+
+  describePaths(loc: Location): string[] {
+    return [mcpJsonPath(loc), steeringPath(loc)];
+  }
+}
+
+function writeMcpEntry(loc: Location): WriteResult['files'][number] {
+  const file = mcpJsonPath(loc);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(file);
+  const before = existing.mcpServers?.codegraph;
+  const after = getMcpServerConfig();
+
+  if (jsonDeepEqual(before, after)) {
+    return { path: file, action: 'unchanged' };
+  }
+  const action: 'created' | 'updated' =
+    before ? 'updated' : (fs.existsSync(file) ? 'updated' : 'created');
+  if (!existing.mcpServers) existing.mcpServers = {};
+  existing.mcpServers.codegraph = after;
+  writeJsonFile(file, existing);
+  return { path: file, action };
+}
+
+/**
+ * Write the dedicated steering file. Unlike CLAUDE.md / GEMINI.md
+ * (shared files where codegraph owns a marker-delimited section),
+ * Kiro's steering dir loads every `*.md` as a discrete document — so
+ * `codegraph.md` is ours outright. Byte-equality short-circuits
+ * idempotent re-runs; mismatched content gets a clean rewrite.
+ */
+function writeSteeringEntry(loc: Location): WriteResult['files'][number] {
+  const file = steeringPath(loc);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const body = INSTRUCTIONS_TEMPLATE + '\n';
+
+  if (!fs.existsSync(file)) {
+    atomicWriteFileSync(file, body);
+    return { path: file, action: 'created' };
+  }
+  const existing = fs.readFileSync(file, 'utf-8');
+  if (existing === body) {
+    return { path: file, action: 'unchanged' };
+  }
+  atomicWriteFileSync(file, body);
+  return { path: file, action: 'updated' };
+}
+
+/**
+ * Delete the steering file we own. If a user has hand-edited the file
+ * out of recognition we still remove it — codegraph.md is a name we
+ * claim, and a partial install leaving the file behind is worse than
+ * a clean delete.
+ */
+function removeSteeringEntry(loc: Location): WriteResult['files'][number] {
+  const file = steeringPath(loc);
+  if (!fs.existsSync(file)) return { path: file, action: 'not-found' };
+  try { fs.unlinkSync(file); } catch { /* ignore */ }
+  return { path: file, action: 'removed' };
+}
+
+export const kiroTarget: AgentTarget = new KiroTarget();

src/installer/targets/registry.ts

@@ -15,6 +15,7 @@ import { opencodeTarget } from './opencode';
 import { hermesTarget } from './hermes';
 import { geminiTarget } from './gemini';
 import { antigravityTarget } from './antigravity';
+import { kiroTarget } from './kiro';
 
 export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([
   claudeTarget,
@@ -24,6 +25,7 @@ export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([
   hermesTarget,
   geminiTarget,
   antigravityTarget,
+  kiroTarget,
 ]);
 
 export function getTarget(id: string): AgentTarget | undefined {

src/installer/targets/types.ts

@@ -19,7 +19,7 @@ export type Location = 'global' | 'local';
  * lookup. New targets add a value here when they're added to the
  * registry. Keep these short and lowercase.
  */
-export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity';
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro';
 
 /**
  * Result of `target.detect(location)`.