AgentCairn setup

Set up the full AgentCairn integration by delegating to AgentCairn's native,
preview-first installer. Treat this skill as a management layer only: installing
this skill does not install the AgentCairn runtime, MCP server, plugin, or hooks.

Preserve the boundary

• Use uvx --from agentcairn cairn install as the source of truth for supported
  hosts and generated configuration.
• Do not copy plugin files, write MCP configuration by hand, or reproduce the
  installer's host-specific logic.
• Do not claim AgentCairn is ready merely because this setup skill is present.
• Do not use plain uvx cairn; that resolves an unrelated package. Use
  uvx --from agentcairn cairn ....
• Use --vault only for MCP hosts. Configure plugin-host vaults through the
  plugin or AgentCairn's shared configuration.
• Do not install or repair every detected host unless the user explicitly asks.
• Do not write a test memory without the user's approval.

1. Establish the target

Check whether AgentCairn's recall and remember MCP tools are already loaded.
If they are available and the user did not request an upgrade or repair, report
that the full integration is active and move to verification.

Identify the current or requested host. Use these installer IDs:

Host	Installer ID	Integration
Claude Code	claude-code	Native plugin, MCP tools, skill, and hooks
Codex	codex	Native plugin, MCP tools, skill, and hooks
Cursor	cursor	MCP configuration and memory skill
OpenCode	opencode	MCP configuration, commands, and native plugin
Antigravity	antigravity	Native plugin; requires a local plugin source
VS Code / Copilot	vscode	MCP configuration
Claude Desktop	claude-desktop	MCP configuration
Gemini CLI	gemini	MCP configuration

Treat Hermes Agent separately because it uses a native MemoryProvider, not
cairn install:

hermes plugins install ccf/agentcairn/integrations/hermes
hermes memory setup agentcairn

If the target is still ambiguous after inspecting the current harness and
installed CLIs, ask the user which one to configure. Never choose --all as a
shortcut.

2. Check the prerequisite

Run:

uvx --version

If uvx is missing, explain that AgentCairn uses Astral's uv and ask before
installing a system-level prerequisite. Do not silently run a remote installer.

Confirm the AgentCairn package and CLI resolve:

uvx --from agentcairn cairn --version

3. Preview without changing host configuration

Use discovery mode to list detected hosts. It writes no AgentCairn host
configuration, but detection proves only that a host is present—not that
AgentCairn is installed or healthy:

uvx --from agentcairn cairn install

For a plugin host, preview the exact target:

uvx --from agentcairn cairn install <host> --print

This prints only the native plugin commands. For MCP hosts, the same --print
operation prints the complete merged configuration and may include credentials
from unrelated MCP servers. Do not run it directly through a chat-visible tool
or paste its output into an agent transcript. Ask the user to review it in
their own terminal, or redirect it to a mode-0600 temporary file, inspect only
the AgentCairn entry locally, and remove the temporary file.

For Antigravity, first locate a local checkout of the AgentCairn plugin and
preview with its path:

uvx --from agentcairn cairn install antigravity --source <repo>/plugin --print

Summarize the plugin commands or configuration path shown by the preview
without exposing unrelated configuration values. If the user has not already
authorized the installation or repair, get approval before continuing.

4. Apply one targeted installation

Run the same operation without --print:

uvx --from agentcairn cairn install <host>

For Antigravity, retain the reviewed local source:

uvx --from agentcairn cairn install antigravity --source <repo>/plugin

For Claude Code and Codex, let the installer delegate to the host's plugin CLI.
Confirm the requested plugin host's CLI is available before applying. For MCP
hosts, let the installer perform its backup-first, merge-preserving
configuration write. Treat a failed command as a failed install; report its
last useful error instead of continuing as though setup succeeded.

5. Verify the full integration

Verify each layer that the host supports:

1. Confirm the install command exited successfully.
2. For Claude Code, run claude plugin list --json; for Codex, run
   codex plugin list --json. Confirm agentcairn is installed and enabled.
3. For an MCP-configured host, confirm its AgentCairn entry matches the
   privately reviewed targeted --print preview without removing unrelated
   configuration.
4. Restart the host. A running session cannot reliably hot-load a new plugin,
   MCP server, skill, or hook.
5. In a fresh session, confirm the AgentCairn search, recall,
   build_context, recent, and remember tools are present. Use recent or
   a focused read-only recall to exercise the MCP server. Ask before writing
   and recalling a synthetic memory.
6. If a vault index already exists, optionally run
   uvx --from agentcairn cairn doctor --vault <vault> to check index health.
   Do not treat an empty, not-yet-indexed vault as a plugin failure.

Report partial support honestly. MCP tools working does not prove ambient hooks
loaded; a setup skill loading does not prove the MCP tools exist.

Repair or upgrade

Start again from the targeted --print preview and preserve the same host ID
and vault. For MCP hosts, rerun the targeted installer; its writes are
idempotent, backup-first, and preserve unrelated servers.

For native plugin hosts, refresh through the host's own plugin manager before
restarting:

# Codex
codex plugin marketplace upgrade agentcairn
codex plugin add agentcairn@agentcairn

# Claude Code
claude plugin marketplace update agentcairn
claude plugin update agentcairn@agentcairn

Do not remove an existing integration, delete a vault, or overwrite a malformed
configuration as a repair shortcut. Surface the conflict and ask before any
destructive recovery.