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 gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent copilot --hook
swarmvault install --agent kilo --hook

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.
--hook — Install hook or plugin support when the target agent exposes a project hook surface

What It Does

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

Agent	Target File
`claude`	`CLAUDE.md`
`codex`	`AGENTS.md`
`goose`	`AGENTS.md`
`pi`	`AGENTS.md`
`opencode`	`AGENTS.md`
`gemini`	`GEMINI.md`
`aider`	`CONVENTIONS.md` + `.aider.conf.yml`
`copilot`	`.github/copilot-instructions.md` + `AGENTS.md`
`cursor`	`.cursor/rules/swarmvault.mdc`
`trae`	`.trae/rules/swarmvault.md`
`claw`	`.claw/skills/swarmvault/SKILL.md`
`droid`	`.factory/rules/swarmvault.md`
`kiro`	`.kiro/skills/swarmvault/SKILL.md` + `.kiro/steering/swarmvault.md` (`inclusion: always`)
`hermes`	`~/.hermes/skills/swarmvault/SKILL.md` (user-scope) + `AGENTS.md`
`antigravity`	`.agents/rules/swarmvault.md` (always-on) + `.agents/workflows/swarmvault.md` (`/swarmvault` workflow)
`vscode`	`.github/chatmodes/swarmvault.chatmode.md` (VS Code Copilot Chat) + `.github/copilot-instructions.md`
`kilo`	`AGENTS.md` plus optional `.kilo/plugins/swarmvault.js` and `.kilo/kilo.json`
`devin`	`.devin/skills/swarmvault/SKILL.md`

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.

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.

Claude and Gemini install model-visible advisory hooks: they inject graph-first context through structured hook output rather than printing shell text.

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.