Get Started with Guild

Guild gives your Claude Code session a structured team of 14 domain specialists — architect, backend, frontend, security, copywriter, and more — running a 7-step lifecycle: brainstorm, plan, execute, review, verify. Install it once; type /guild:guild "your task" to start.

Install

claude plugin marketplace add lookatitude/guild
claude plugin marketplace update guild
claude plugin install guild@guild

Restart Claude Code after installation. Commands, skills, agents, hooks, and MCP servers load at session startup — a newly installed plugin is not active until the next session.

Installing from source:

git clone https://github.com/lookatitude/guild.git
cd guild
claude plugin marketplace add .
claude plugin marketplace update guild
claude plugin install guild@guild --scope project

Restart Claude Code before running /guild:guild from the project directory.

Verify the plugin loaded

A SessionStart bootstrap card appears at the start of each session. It lists the Guild version, available slash commands, optional MCP servers, and doc entry points. If the card does not appear after restart:

/guild:audit

This inspects hooks/hooks.json in the installed plugin and reports what is missing.

First run

/guild:guild "Build a Stripe subscription flow, add tests, update the docs, draft a launch email."

Or run with no brief and let the brainstorm skill prompt you:

/guild:guild

Guild runs in phases. You confirm at three gates; the rest runs with minimal interruption:

The first run writes durable state under .guild/:

.guild/
├── spec/           # approved task spec
├── team/           # resolved specialist team
├── plan/           # per-specialist lane plan
├── context/        # per-run specialist context bundles
├── runs/           # telemetry, handoff receipts, assumptions
└── reflections/    # proposed skill and specialist improvements

Verify hooks are firing

After installation, confirm hook events are being recorded:

1. Start a fresh Claude Code session in a project where Guild is installed.
2. Confirm the bootstrap card appears.
3. Run a small /guild:guild "..." task.
4. Check for .guild/runs/<run-id>/events.ndjson.

If no .guild/runs/ files are written:

/guild:audit

Guild inspects hooks/hooks.json and reports what is missing.

If a run fails or telemetry looks inconsistent:

/guild:fix <run-id>

Guild reads recent .guild/runs evidence, writes a diagnosis and fix plan, and asks before applying any edits.

Environment variables

Optional MCP servers

Two MCP servers ship under mcp-servers/ but are not required — Guild runs end-to-end without them:

• guild-memory — BM25 search over .guild/wiki/. Add it once the wiki crosses ~200 pages.
• guild-telemetry — Structured trace queries over .guild/runs/. Useful for cost breakdowns by tier, specialist, or phase.

Both ship pre-bundled and start under plain node — no npm install step on first use.

Commands at a glance

Next steps

• How Guild works — phase-by-phase breakdown of what happens when you run /guild:guild.
• Architecture & Lifecycle — 4-layer architecture, three execution backends, 10 hook events.
• Configuration reference — full settings.json reference for agent_mode, model tiers, and security policy.