swarmvault install

Install SwarmVault instructions for an AI coding agent.

Usage

swarmvault install --agent <agent> [--scope project|user]
swarmvault install status --agent <agent>
swarmvault install --agent claude --hook
swarmvault install --agent claude --hook --mcp
swarmvault install --agent claude --hook --scope user
swarmvault install --agent gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent copilot --hook
swarmvault install --agent kilo --hook

Recommended per-repo onboarding for token-saving agent workflows:

cd <repo>
swarmvault init && swarmvault ingest .
swarmvault install --agent claude --hook --mcp
swarmvault hook install        # git-hook refresh on commit/checkout

Options

• --agent <agent> — Target agent. Common direct-rule targets include codex, claude, cursor, goose, pi, gemini, opencode, aider, copilot, trae, claw, droid, kiro, hermes, antigravity, vscode, kilo, and devin; extended coding-agent targets receive a project-level skill bundle at that tool's conventional skills directory.
• --scope <project|user> — Choose project-local or user-level install targets when the agent supports both. The CLI defaults to project scope. For Claude, --scope user installs the skill, hook, and settings once under ~/.claude for all repos; the hook no-ops in repos without a compiled graph report.
• --hook — Install hook or plugin support when the target agent exposes a project hook surface
• --mcp — Register the SwarmVault MCP server in the project's .mcp.json (Claude): {"mcpServers":{"swarmvault":{"command":"swarmvault","args":["mcp"]}}}

What It Does

Installs SwarmVault-aware rules into the agent's configuration file:

The installed rules teach the agent about your vault's structure, how to query it, and how to reference wiki pages.

codex, goose, pi, and opencode intentionally share the same managed AGENTS.md block so one project can support multiple agent CLIs without conflicting rule files.

SwarmVault only owns the managed block inside shared markdown rule files. It keeps the SwarmVault block aligned across targets while preserving user-owned text before or after the block, so rule files for different tools do not need to be byte-identical.

swarmvault install status --agent <agent> reports whether each expected target exists and whether it currently contains the managed SwarmVault block. Use --json with global JSON output for automation.

Host-Project Hygiene

swarmvault install --agent <agent> also keeps the host project clean around the vault artifact directories (raw/, wiki/, state/, agent/, inbox/):

• in git repos, the artifact directories are appended to .gitignore so generated vault state is not committed accidentally
• strict-JSON tsconfig.json files get the artifact directories added to their "exclude" list, so stored source copies under raw/ do not break the host project's typecheck; commented (JSONC) tsconfig files are never rewritten — a warning explains the manual edit instead
• linter configs that still cover the artifact directories produce an advisory warning

All hygiene edits are skipped when SWARMVAULT_OUT keeps the artifact directories outside the repo.

Antigravity installs now use the .agents/ convention. Reinstalling removes older fully managed .agent/ rule/workflow files when their content is still owned by SwarmVault.

Hook-capable agents:

• claude --hook writes .claude/settings.json plus .claude/hooks/swarmvault-graph-first.js
• opencode --hook writes .opencode/plugins/swarmvault-graph-first.js
• gemini --hook writes .gemini/settings.json plus .gemini/hooks/swarmvault-graph-first.js
• copilot --hook writes .github/hooks/swarmvault-graph-first.json plus .github/hooks/swarmvault-graph-first.js
• kilo --hook writes .kilo/plugins/swarmvault.js plus .kilo/kilo.json

aider is intentionally file/config-based in this release rather than hook-based.

The installed hooks guide graph-first reads, with enforcement as an opt-in. The Claude Code hook:

• injects graph-first instructions at session start — answer code-understanding questions with the plain swarmvault graph query|explain|path commands (avoid --json, which produces much larger output), swarmvault query, swarmvault context build, or wiki/graph/report.md, and read source files only when editing them — plus a graph staleness note. swarmvault graph query "<seed>" prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers where-is/what-calls questions without follow-up file reads
• adds a one-time advisory note on the first broad Grep/Glob/Bash search per session by default; with the --graph-first install opt-in, that first search is instead denied once with a guided redirect to those plain graph commands and the inline excerpt they return — repeating the same search is then allowed, so work is never blocked
• spawns a background swarmvault graph update --file <path> refresh after Edit/Write tools so the graph tracks edits
• never intercepts searches scoped to vault artifact directories (wiki/, raw/, state/), single files, or search tools that merely filter piped output

Opt in to enforcement at install time with --graph-first [deny|context|off] (bare flag means deny), which persists the mode as hooks.graphFirst in swarmvault.config.json; the default without opt-in is context (advisory). SWARMVAULT_GRAPH_FIRST=deny|context|off overrides per session. Reinstalling migrates previously installed Claude hook settings entries to the current matcher layout while preserving user-owned hook entries.

The Codex, Gemini, Copilot, OpenCode, and Kilo integrations carry the same graph-first guidance — a session note with staleness information plus a one-time search redirect appropriate to each tool's hook API.

OpenCode's current plugin surface is advisory/log-only, so its plugin nudges rather than blocks.

Copilot's current hook surface is decision-based rather than advisory, so the installed Copilot hook guards broad grep/glob tool use until wiki/graph/report.md has been read in the current session.

Kilo project hooks register the plugin in .kilo/kilo.json. If a project already has .kilo/kilo.jsonc, SwarmVault leaves the JSONC file in place and writes the normalized JSON registration beside it.