# 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.dacgroup.com/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. **Choose one installation lane.** Claude Code and Codex normally arrive managed: Codex through the DAC ChatGPT Enterprise workspace (nothing to install) and Claude Code through the DAC Claude team plugin (install the Guild CLI only). Never re-stage a managed plugin or duplicate its MCP registration. Codex desktop uses the DAC workspace plugin when it is available; its advanced CLI fallback stages the Codex plugin from the checksum-verified Guild binary's bundled payload and never clones the private Guild repository. Cursor uses its shipped adapter. Other harnesses register the hosted HTTP endpoint in Tools-only mode. Local Guild stdio is retired and unsupported.
3. **Authenticate the applicable Guild tools.** Use the harness-managed MCP browser OAuth flow for hosted Guild tools. opencode is the exception: it uses GUILD_MCP_TOKEN with oauth=false after a Guild CLI login preflight. After hosted Guild MCP browser consent succeeds, follow get_cli_repair_plan(target="claude_code") and its lifecycle_claim conditions. Only when the plan and local doctor identify a missing or invalid lifecycle credential, call provision_lifecycle_claim(target="claude_code") through the authenticated Guild MCP connection, then run the returned `guild lifecycle claim <claim>` command on this machine. The CLI redeems the single-use claim and writes the trace-only credential without printing the durable credential. Preserve a working credential. Use `guild login --no-browser` only if MCP provisioning is unavailable; skipping both leaves lifecycle tracing degraded, not complete. Cursor uses a separate Guild CLI credential for lifecycle tracing. Codex uses no Guild lifecycle credential; its CLI fallback only carries the plugin payload. Show any interactive authorization page to the user immediately, keep the login command alive, and check its terminal result. Never leave authorization in a hidden browser tab while claiming login is still waiting. Never request broader sandbox or filesystem access for setup. If a required local plugin or lifecycle layer is unavailable, continue in hosted MCP Tools-only mode so core tools still work, but report the missing local capability as degraded rather than calling setup complete.
4. **Prove Guild tools and show value.** Call named Guild tools directly when advertised. In the default code profile, dispatch get_setup_instructions and get_connection_readiness through call_tool(name="<tool>", arguments={...}). Use target=<detected target>, follow the connected-user contract, confirm identity and available systems without dumping scopes or tool inventories, then offer up to three safe prompts matched to what is connected. For Codex, never launch a nested `codex exec` as a substitute for readiness. First test Guild directly in the current task. Check `codex plugin list`, `codex mcp list`, and a Guild skill lookup. If the current task lacks the newly installed tools or guidance, explain that it may retain its initial plugin context and suggest the user start a new Codex task. Provide a copyable handoff containing the user's actual request and verified setup state, without credentials; create a task only if the user explicitly asks. Restart the app only if that new task still does not load the installed plugin or tools. Use target="generic" for an unrecognized MCP client.
5. **Explore Guild skills.** For normal work, call find_skill(query="<the user request>", load_best_match=true) or get_skill for an advertised slug; server-side skills are current without local sync. Plugin-managed skills update through their plugin owner. A selected skill with requires_install uses its returned install args with install_artifact. Only when the user explicitly requests a bulk local export, invoke install_recommended_artifacts(target=<detected target>, response_mode="full"), directly when advertised or through call_tool in the default code profile. Apply every write_plan entry where write=true, read and parse the JSON at the returned inventory_path, then pass that post-write inventory to first_run_smoke through the same profile-aware dispatch. Report Guild tools, plugin/adapter, lifecycle status, and local artifact export separately. ChatGPT has no local artifact sync.
6. **Make Guild yours and try Quickpages.** Offer optional personalization at https://guild.dacgroup.com/my-agent/settings#onboarding: name the agent, generate or upload a photo, choose its personality, and edit personal preferences. Users can revisit Settings or ask for a change anytime, such as 'Always show screenshots inline in monday.com task updates.' Follow get_setup_instructions for the current context read, merge, save, and readback workflow; preserve unrelated preferences and report pending review honestly. Showcase Quickpages with 'Draft a Quickpage project update with an executive summary, screenshots, and next steps.' Discover the current tools or skill, preview first, and confirm the audience before publishing; a demo is not publication consent and DAC access remains the default. This optional personalization path is separate from the governed priorities interview.
7. **Offer governed personalization.** After the user has seen what works now, call find_skill(query="onboarding interview", load_best_match=true) and follow loaded_skill.skill_md. If get_skill is needed and is not advertised directly, dispatch it through call_tool(name="get_skill", arguments={"slug":"onboarding-interview"}). Offer the governed skill's brief, skippable flow exactly; do not substitute or maintain a second hard-coded questionnaire.

## Choose one setup path for your harness

### Claude Code
- The DAC Guild plugin is pushed to Claude Code as a team-managed plugin, so it installs and updates itself. Treat it as owned by that channel: do not run `guild plugin install claude_code` over it, add a second Guild MCP registration, or write your own hooks.json. The remaining step is the public Guild CLI, which the plugin needs locally. This installs the CLI only. Windows x64 PowerShell: iwr https://guild.dacgroup.com/api/v1/install.ps1 -UseBasicParsing | iex. macOS Apple silicon or Linux x64: curl -fsSL https://guild.dacgroup.com/api/v1/install.sh | sh.
- Restart Claude Code once after a fresh CLI install so the hook process picks up the new PATH. Complete the hosted Guild MCP consent in a visible browser and keep the flow alive until it finishes. Then After hosted Guild MCP browser consent succeeds, follow get_cli_repair_plan(target="claude_code") and its lifecycle_claim conditions. Only when the plan and local doctor identify a missing or invalid lifecycle credential, call provision_lifecycle_claim(target="claude_code") through the authenticated Guild MCP connection, then run the returned `guild lifecycle claim <claim>` command on this machine. The CLI redeems the single-use claim and writes the trace-only credential without printing the durable credential. Preserve a working credential. Use `guild login --no-browser` only if MCP provisioning is unavailable; skipping both leaves lifecycle tracing degraded, not complete. If local installation is blocked, continue temporarily in degraded Tools-only mode with claude mcp add --transport http --scope user guild https://mcp.guild.dacgroup.com/mcp and report that lifecycle tracing is not active.
- Rare unmanaged case only — a personal Claude account, API-key auth, or any install where Claude lists no Guild plugin at all: stage it yourself with `guild plugin install claude_code` after the CLI is on PATH. Confirm the plugin is genuinely absent first.

### Codex
- On a DAC ChatGPT Enterprise workspace there is normally nothing to install: DAC Guild is workspace-managed, so start a task and ask Guild for something. First test Guild directly in the current task. Check `codex plugin list`, `codex mcp list`, and a Guild skill lookup. If the current task lacks the newly installed tools or guidance, explain that it may retain its initial plugin context and suggest the user start a new Codex task. Provide a copyable handoff containing the user's actual request and verified setup state, without credentials; create a task only if the user explicitly asks. Restart the app only if that new task still does not load the installed plugin or tools.
- If the entry is missing or disconnected: In Codex desktop, select the DAC workspace and open Plugins. If DAC Guild is available in the workspace-provided section, install or enable it and use its connection control. The workspace plugin supplies Guild skills and its connection; Compliance API ingestion supplies tracing with no local hooks and no Guild CLI.
- Advanced fallback for remote, scripted, or UI-blocked environments: install the checksum-verified public Guild CLI and stage its bundled Codex plugin payload. Windows x64 PowerShell: iwr https://guild.dacgroup.com/api/v1/install.ps1 -UseBasicParsing | iex; & $installPath plugin install codex. macOS Apple silicon or Linux x64: curl -fsSL https://guild.dacgroup.com/api/v1/install.sh | sh && "$HOME/.local/bin/guild" plugin install codex. This path does not clone the private Guild repository, install Guild lifecycle hooks, or require a separate guild login. Authenticate its hosted MCP registration with codex mcp login guild.
- If plugin installation is blocked, use Tools-only mode: run codex mcp add guild --url https://mcp.guild.dacgroup.com/mcp, then codex mcp login guild. Hosted tools and Compliance API tracing still work; report packaged local plugin skills separately.

### Cursor
- Preferred: install/update the public Guild CLI and the shipped Cursor adapter. Windows x64 PowerShell: iwr https://guild.dacgroup.com/api/v1/install.ps1 -UseBasicParsing | iex; & $installPath plugin install cursor. macOS Apple silicon or Linux x64: curl -fsSL https://guild.dacgroup.com/api/v1/install.sh | sh && "$HOME/.local/bin/guild" plugin install cursor. This writes both ~/.cursor/mcp.json and ~/.cursor/hooks.json.
- If the adapter is unavailable, continue temporarily in degraded Tools-only mode and report that lifecycle tracing is not active: add { "mcpServers": { "guild": { "url": "https://mcp.guild.dacgroup.com/mcp", "transport": "http" } } } to ~/.cursor/mcp.json.

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

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

### Hermes
- Register the hosted HTTP MCP server https://mcp.guild.dacgroup.com/mcp in your Hermes MCP config. Local Guild stdio is retired.

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

### opencode
- Install or update the public Guild CLI, then log in from a shell. Windows x64 PowerShell: iwr https://guild.dacgroup.com/api/v1/install.ps1 -UseBasicParsing | iex; & $installPath login. macOS Apple silicon or Linux x64: curl -fsSL https://guild.dacgroup.com/api/v1/install.sh | sh && "$HOME/.local/bin/guild" login. Load GUILD_MCP_TOKEN from ~/.guild-mcp/credentials.json without printing it, then add to opencode.json: { "mcp": { "dac-guild": { "type": "remote", "url": "https://mcp.guild.dacgroup.com/mcp", "headers": { "Authorization": "Bearer {env:GUILD_MCP_TOKEN}" }, "oauth": false } } }.

### Other MCP-capable harnesses
- Register the hosted HTTP MCP server https://mcp.guild.dacgroup.com/mcp using your harness's MCP config. Local Guild stdio is retired.

## Local lifecycle layers

Hosted MCP is the only Guild tool transport. The local Guild CLI credential is
used for doctor, lifecycle hooks, trace delivery, and explicit CLI utilities. It is part
of full Claude Code and Cursor setup, but not Codex setup. Keep its credential separate
from harness-managed MCP OAuth; the hooks remain fail-safe if local state is unavailable.

> If a required local plugin or lifecycle layer is unavailable, continue in hosted MCP Tools-only mode so core tools still work, but report the missing local capability as degraded rather than calling setup complete.

### Claude Code
- Fallback local tracing login only when MCP provisioning is unavailable. Windows x64 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 Apple silicon or Linux x64: "$HOME/.local/bin/guild" login --no-browser --scopes "mcp:full offline_access".
- Verify with /dac-guild:guild-doctor. /reload-plugins is enough only for a later plugin-only refresh when `guild` was already available.
- Diagnose a faulty install with `guild doctor --harness claude_code --verbose`. Preserve a team-managed or marketplace plugin: run `guild plugin install claude_code` only when Claude reports no Guild plugin at all. Do not add the private Guild Git repository as a Claude marketplace.

### Cursor
- The shipped adapter command is guild plugin install cursor. Restart Cursor and verify the Guild MCP server and lifecycle-hook entries load.
- Local tracing login, required for full Cursor setup. Windows x64 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 Apple silicon or Linux x64: "$HOME/.local/bin/guild" login --no-browser --scopes "mcp:full offline_access". The hooks fail safely, but report missing lifecycle tracing as degraded rather than complete.

### Hermes (local adapter: 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

- Most DAC colleagues are on a managed path: Codex on DAC ChatGPT Enterprise needs no install at all, and Claude Code on the DAC Claude team needs the Guild CLI only. Everything else on this page is for unmanaged or advanced cases.
- Guild is currently for DAC colleagues using their DAC Microsoft account.
- 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.
- The public CLI installer installs the Guild CLI only; it never installs or replaces a harness plugin. It is required for the full Claude Code and Cursor lifecycle experience and optional for opencode compatibility. Codex needs no Guild CLI on its normal workspace path, though the binary carries a bundled Codex plugin payload for recovery when that UI is unavailable.
- When a harness uses the local lifecycle layer (`guild` CLI), get_setup_instructions and get_cli_repair_plan return the exact commands to run.