# Install Guild

Guild is a portable personal-agent backend (memory, skills, approvals, and
connector tools) that plugs into your existing coding agent over MCP.

**If you are an AI agent reading this page:** you have everything you need
below. Detect which harness you are running in, complete the steps, and
carry the whole setup through — the user should not have to pick a harness
or paste a harness-specific prompt.

MCP endpoint: https://mcp.guild.dacdev.studio/mcp

## Steps

1. **Identify your harness.** Work out which coding agent / harness and operating system you are running in (Claude Code, Codex, Cursor, VS Code, ChatGPT, Antigravity, opencode, …). Detect whether the harness exposes its plugin command before choosing plugin or Tools-only mode.
2. **Add the Guild MCP server.** Mount the hosted Guild MCP endpoint https://mcp.guild.dacdev.studio/mcp using your harness's method (see the per-harness list). Always use the hosted HTTP endpoint, not local stdio.
3. **Install the Guild plugin + lifecycle hooks if your harness supports them.** This layer is ADDITIVE and fail-soft on top of the MCP server. The hooks add governance gating, telemetry, and automatic identity / memory / skill context injection at session start — but MCP-server-only is still a valid end state, so a missing or flaky hook layer never blocks setup. Use the "plugin + hooks" line for your harness below (Claude Code and Codex CLI ship it today; Cursor and Hermes are coming soon, MCP-only for now; ChatGPT and other harnesses get tools / skills / memory / personality from the MCP server with no hook layer). If the plugin install fails, fall back to MCP-server-only — never block the agent loop on the hook layer.
4. **Sign the user in.** Report two auth states separately: Guild tools is hosted MCP OAuth; Local lifecycle hooks is the local Guild CLI credential. When a device flow starts, relay the URL/code immediately and keep the command alive until approval or a clear timeout. The first hosted sign-in creates the profile automatically. Never ask the user to change sandbox/full-filesystem permissions for Guild setup; diagnose command availability, PATH, OAuth, or harness support instead.
5. **Run the post-install setup.** Once the Guild MCP tools are available, call get_setup_instructions(target=<your harness>) and follow it. Both setup tools default to target="codex", so always pass your detected harness (e.g. claude_code, cursor, vscode, opencode, antigravity, codex) — otherwise you sync Codex-formatted files into the wrong harness. When it says to sync local artifacts, call install_recommended_artifacts(target=<your harness>, response_mode="full"); the default inventory mode returns no write_plan, so you must request full mode, then write every write_plan entry where write=true (creating parent directories) and restart the harness so the new skills load.
6. **Offer the quick onboarding interview.** Optionally ask three questions — what should Guild remember about how the user works, which clients/projects/workflows matter most right now, and how proactive the PA should be — and save confirmed answers with the Guild memory / user-context tools.
7. **Verify.** Return one compact capability result: Guild tools ✓, Plugin ✓/not supported, Lifecycle hooks ✓/not supported, Skills synced ✓/unverified. For Codex, verify with `codex mcp get guild` and `guild doctor --harness codex`; for Claude Code, run `/reload-plugins` and `/dac-guild:guild-doctor`. Tools-only is a successful degraded state, not a failed install.

## Add the Guild MCP server for your harness

### Claude Code
- Run: claude mcp add --transport http --scope user guild https://mcp.guild.dacdev.studio/mcp

### Codex CLI
- Add to ~/.codex/config.toml: [mcp_servers.guild] with url = "https://mcp.guild.dacdev.studio/mcp"
- Then run: codex mcp login --scopes mcp:apps,mcp:skills:install,mcp:approvals:decide,offline_access guild

### Cursor
- Add to .cursor/mcp.json: { "mcpServers": { "guild": { "url": "https://mcp.guild.dacdev.studio/mcp", "transport": "http" } } }

### VS Code
- Add to .vscode/mcp.json: { "servers": { "guild": { "type": "http", "url": "https://mcp.guild.dacdev.studio/mcp" } } }

### ChatGPT
- In Settings → Apps & Connectors → Create, use connector URL: https://mcp.guild.dacdev.studio/mcp/chatgpt

### Hermes
- Register the hosted HTTP MCP server https://mcp.guild.dacdev.studio/mcp in your Hermes MCP config (not local stdio).

### Antigravity
- Add mcpServers.guild.serverUrl = "https://mcp.guild.dacdev.studio/mcp" to ~/.gemini/antigravity/mcp_config.json (desktop) or ~/.gemini/antigravity-cli/mcp_config.json (CLI)

### opencode
- Add to opencode.json: { "mcp": { "dac-guild": { "type": "remote", "url": "https://mcp.guild.dacdev.studio/mcp", "oauth": true } } }

### Other MCP-capable harnesses
- Register the hosted HTTP MCP server https://mcp.guild.dacdev.studio/mcp using your harness's MCP config (not local stdio).

## Then install the plugin + lifecycle hooks (additive, fail-soft)

The plugin + lifecycle hooks add governance gating, telemetry, and automatic
identity / memory / skill context injection at session start. This layer sits
ON TOP of the MCP server — **MCP-server-only is always a valid end state**, so a
plugin/hook hiccup never strands the agent loop.

> If the plugin install fails, fall back to MCP-server-only — never block the agent loop on the hook layer.

### Claude Code
- Install/update the CLI and bundled plugin. Windows PowerShell: iwr https://guild.dacdev.studio/api/v1/install.ps1 -UseBasicParsing | iex; guild plugin install claude_code. macOS/Linux: curl -fsSL https://guild.dacdev.studio/api/v1/install.sh | sh && "$HOME/.local/bin/guild" plugin install claude_code. If the bundled path is unavailable, use the Claude marketplace fallback: /plugin marketplace add DAC-Group/agno-guild then /plugin install dac-guild@dac-guild.
- Sign in the Local lifecycle hooks without relying on the already-running harness PATH. Windows PowerShell: $guild = if (Test-Path "C:\source\guild.exe") { "C:\source\guild.exe" } else { Join-Path $env:LOCALAPPDATA "Programs\guild\guild.exe" }; & $guild login --no-browser --scopes "mcp:full offline_access". macOS/Linux: "$HOME/.local/bin/guild" login --no-browser --scopes "mcp:full offline_access". Relay the printed device URL/code immediately and keep the process alive until it succeeds. This is independent of the Guild tools MCP OAuth consent.
- Restart Claude Code once after a fresh CLI install, then verify with /dac-guild:guild-doctor. For later plugin-only refreshes, /reload-plugins is enough when guild was already available before the refresh.

### Codex CLI
- Install/update the CLI and bundled plugin + 8 lifecycle hooks. Windows PowerShell: iwr https://guild.dacdev.studio/api/v1/install.ps1 -UseBasicParsing | iex; guild plugin install codex. macOS/Linux: curl -fsSL https://guild.dacdev.studio/api/v1/install.sh | sh && "$HOME/.local/bin/guild" plugin install codex. It registers the hosted MCP server and enables hooks/plugin_hooks; no WSL or hand-wired hooks file is required. If this Codex build lacks plugin support, complete Tools-only mode and offer a Codex upgrade path.
- Sign in the Local lifecycle hooks without relying on the already-running harness PATH. Windows PowerShell: $guild = if (Test-Path "C:\source\guild.exe") { "C:\source\guild.exe" } else { Join-Path $env:LOCALAPPDATA "Programs\guild\guild.exe" }; & $guild login --no-browser --scopes "mcp:full offline_access". macOS/Linux: "$HOME/.local/bin/guild" login --no-browser --scopes "mcp:full offline_access". Relay the printed device URL/code immediately and keep the process alive until it succeeds. This is independent of the Guild tools Codex MCP OAuth login.
- Restart Codex once after plugin installation and both auth states complete, then verify with `guild doctor --harness codex`.

### Cursor (plugin + hooks: coming soon)
- Plugin + lifecycle hooks: coming soon (tracked by todo 568). For now, add only the Guild MCP server via the ~/.cursor/mcp.json entry above — you still get tools, skills, memory, and personality.

### Hermes (plugin + hooks: coming soon)
- Plugin + lifecycle hooks: coming soon (tracked by todo 569). For now, add only the Guild MCP server above — you still get tools, skills, memory, and personality.

### Other MCP-capable harnesses
- No hook layer here — the Guild MCP server alone still gives you tools, skills, memory, and personality.

## Notes

- First sign-in creates the Guild profile during browser consent; no pre-registration.
- Skills come from the hosted Guild catalog via the MCP tools above — the local CLI package is not the skill marketplace.
- If the harness needs local lifecycle hooks (`guild` CLI), get_setup_instructions and get_cli_repair_plan return the exact local commands to run.