A Guild Stack plugin for AI coding hosts that gives you self-evolving teams of specialist agents.
Guild turns a single coding session into a disciplined guild: /guild "<task>"
runs intake, binds a workflow class, composes a team, writes per-specialist plans,
assembles tight context bundles, dispatches specialists, reviews, verifies, and
reflects. Every significant question becomes a structured decision. Every skill
edit replaces a named span and keeps a compact history for rollback. Harvest is
the only automatic writer; everything else waits for a gate.
- 15 specialist templates + 4 machinery agents — 15 domain type templates
across three groups (engineering: architect, researcher, backend, frontend,
devops, qa, mobile, security; content & communication: copywriter, doc-writer,
technical-writer, social-media, seo; commercial: marketing, sales), one
templates/specialists/*.mdper role, minted on demand into your project's.guild/agents/by team composition — plus the 4 machinery agents the plugin registers directly (advisor, context-manager, developer, team-lead; oneagents/*.mdeach). - 76 skills, of which 17 are indexed — the host's catalog is exactly 17
assembler skills (using-guild, init, brainstorm, plan, team-compose,
execute-plan, quality, operations, learn, wiki, initiative, review, diagnose,
evolve, create-skill, create-specialist, reflect). Everything else still ships
but stays off the index: L3 chapters live in their parent assembler's
references/, the 58 specialist starter recipes live underskills/specialists/, and the dashboard launcher lives underskills/playbooks/dashboard/. - 13 dispatching command files — bare
/guild [brief], the phase verbs/guild:init|ideate|plan|build|qa|ops,/guild:learn, the nouns/guild:wiki|initiative,/guild:status,/guild:config, and/guild:maintain. Sub-verbs are arguments, never files. The dropped v2.6 command files (adopt,audit,dashboard,evolve,fix,goal,migrate,models,resume,rollback,stats) are print-only aliases that name the new spelling. The:plugin namespace stays (Claude Code requires it); every command is/guild:<verb>(v1→v2:https://guildstack.dev/docs/migration-v1-to-v2). - One runtime shape — bare
/guildis the T0 orchestrator session: with no verb it runs intake and binds one of five class graphs (product · research · debug · ops · init);research,debug, and--class=bind the class directly. Work runs in three tiers (T0 → a Team Lead per TaskCell → specialists) that report only throughguild.goal_status.v1andguild.handoff.v2. Each cell runs one inner loop (recall → research-on-miss → implement → verify → harvest) under an enforced budget (advisorRounds, optional token/usd caps). The critic is the advisor machinery agent; productqais the one review gate. - Two context sizes — a specialist's on-disk bundle is at most 6k tokens; a
parent sees only the lane bundle of at most 1,200 tokens of citations, of which
matching
.guild/wiki/glossary.mdterms take at most 200. The full glossary is never always-on. - One promotion law — harvest promotes decision-shaped verdicts to this
cwd's wiki and span-replaces project playbooks through
scrubbedWrite, and never commits.wiki.autopromotedefaults on;falsemakes the root candidates-only. Specialists never write the wiki. The per-phase checkpoint is a domain function that only classifies. Wikilabels.concernuses the shipped enum: architecture · security · performance · reliability · data · api · ux · build · ops. - 16 supported hosts, one adapter contract — Guild runs across 16 canonical
hosts (Claude Code CLI/Desktop/Web, Codex CLI/app, Pi, Antigravity, Cursor,
GitHub Copilot, opencode, Rovo Dev, Kiro/Qoder/Trae via AGENTS-file, and the
Claude.ai connector) through a single host-adapter contract. Support is
described with an honest two-field model — the presentation Support label
(
Supported/Supported (beta)/Supported (app)/Supported (connector)) is kept separate from the receipt-derived Public State; no host is ever claimed beyond its verified evidence. Missing capabilities degrade to a lesser substrate — the phase still runs and the degradation is written to disk. See the Guild docs site →https://guildstack.dev/hosts. - 10 hook events wired —
SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,PreCompact,SubagentStop,Stop,TaskCreated,TaskCompleted,TeammateIdle. - Tooling scripts — evolution, rollback, telemetry summary, audit-log
summary, Codex review-trail validation, and the opt-in tmux agent-team
launcher live under
scripts/. - 2 optional MCP servers —
guild-memory(BM25 over the wiki once it crosses ~200 pages) andguild-telemetry(structured trace query), two ids of one compiledruntime/guild-mcp.jsbuilt fromsrc/runtime/mcp/. Both stdio-only, no network. Guild runs without them. - Three execution backends (D5
agent_modeladder) — tmux visible panes (in-session or detached);InProcessTeamBackend(implemented: orchestrator consumes a declarativedispatchPlan, each specialist runs as an independent Agent-tool call, no tmux required); remote cross-host SSH dispatch;SUBAGENTlast resort for CI / fresh installs. See the Guild docs site →https://guildstack.dev/docs/architecture. - Cost-aware model tiering — cheap / mid / powerful, auto-scored per lane
from deterministic signals, with advisor escalation for uncertainty.
Zero-config stable. See the Guild docs site →
https://guildstack.dev/docs/configuration(models.*). - Recall —
recall.backend: bm25 | hybrid(defaultbm25). Embeddings are cache only; a missing embedding model fails open to BM25. A lazy SQLite read-through cache sits on platform state, off the repo (index: "auto", default; disable withindex: "off"). - Policy-only config, session-bound hosts — durable config holds policy keys only. The host family and the models bind per session on the run record; an unknown host never defaults to Claude.
- O-3 short-output advisor — fires when a lane's output token count falls
below calibrated p10 floors (
models.shortOutputThreshold). Calibrate with thecalibrate-o3-clitool in the separateguild-benchmarkrepo. See the Guild docs site →https://guildstack.dev/docs/configuration. - Security + observability —
security.bypass_permissions_policy(capability-scope enforcement), 3-stage secrets redaction (secrets_policy.*), and structured trace cost rollup via theguild-telemetryMCP (trace_cost_rollup). See the Guild docs site →https://guildstack.dev/docs/configuration.
The quickest path is the installer script (install.sh at this repo's root —
detects your AI coding hosts, runs the marketplace commands below, never uses
sudo, never edits shell profiles):
curl -fsSL https://guildstack.dev/install.sh | bashDomain unavailable? The same script ships in this repo:
curl -fsSL https://raw.githubusercontent.com/lookatitude/guild/main/install.sh | bashPreview host-specific install paths without changing anything:
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host claude-code-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host codex-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host pi-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host antigravity-cli
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --dry-run --host agents-fileInstalling manually into Claude Code does exactly the same thing:
claude plugin marketplace add lookatitude/guild
claude plugin marketplace update guild
claude plugin install guild@guildBranches are distribution channels: main is stable (released versions —
what the commands above install) and next is beta — merged work still
being tested ahead of the next release. To follow the beta channel:
# Claude Code — pin the marketplace to the next branch:
claude plugin marketplace add lookatitude/guild@next
# marketplace update keeps tracking the pinned next ref:
claude plugin marketplace update guild
claude plugin install guild@guild
# install.sh (any supported host) — same selector:
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel betaSwitch back to stable by re-adding the marketplace without the @next pin (or
--channel stable). Beta may contain unreleased behavior; release notes only
cover what has reached main.
Guild detects updates per channel and never phones home during session start:
a SessionStart hook reads a machine-level cache (refreshed in the background at
most once per defaults.update.cadence_hours, default 24) and prints a one-line
signal with the exact update command when your channel has moved — new release
tag on stable, new next commit on beta. defaults.update.mode controls it:
notify (default), auto (stages the update headlessly; applies next
session), or off. Dev checkouts are never touched.
Applying updates per host — the full 16-host registry:
# claude-code-cli (marketplace-managed):
claude plugin marketplace update guild && claude plugin update guild@guild
# Wrapper-package hosts — pi-cli, antigravity-cli, cursor, github-copilot,
# opencode, rovo-dev (installer-managed; needs the receipt):
guild-run update
# codex-cli — Codex OWNS its installed plugin cache, so Guild never swaps it
# (guild-run update refuses and names this instead). Receipted installs
# re-render; host-native installs are detected and told the precise codex
# command for their registered source type:
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update
# File-surface hosts — agents-file, kiro, qoder, trae (snapshot copies):
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update
# …then re-copy the refreshed dist/agents tree into the project.
# Everything with an install receipt, in one go (any host mix):
curl -fsSL https://guildstack.dev/install.sh | bash -s -- --updateThe four app/connector surfaces (claude-code-app, claude-code-web,
codex-app, claude-ai-connector) take no install and therefore no update
command; codex-app follows whatever its shared Codex CLI registration does.
Each install writes a guild.install_receipt.v1 (host, channel, ref, commit)
under ~/.guild/receipts/ — that receipt is what --update and guild-run update re-render from, keeping every host on the channel it was installed
from. A host-native install (e.g. a hand-run codex plugin add) writes no
machine receipt: --update will detect it and name that host's real command.
The session-start update check mints a package-local receipt for
IDENTIFICATION — its channel field is an assumed default, marked as such, and
nothing ever clones from it.
Installing manually into Codex CLI uses Codex's plugin manager:
npx tsx scripts/build-host-packages.ts --root . --out dist --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
codex plugin marketplace remove guild || true
codex plugin marketplace add ./dist/codex-marketplace
codex plugin add guild@guildRestart Claude Code after installation so commands, skills, agents, hooks, and MCP servers are loaded into the next session.
Local development:
git clone https://github.com/lookatitude/guild.git
cd guild
(cd scripts && npm ci && npm run sync:claude-install)
claude plugin marketplace add ./dist/claude-code
claude plugin marketplace update guild
claude plugin install guild@guild --scope projectUse the generated Claude package for development sessions. A dependency-populated
checkout contains ignored executable files and is intentionally not accepted as an
exact runtime package. Re-run npm run sync:claude-install after changing plugin
source so the generated package and its complete identity stay aligned.
Restart Claude Code before running /guild from the project. Claude Code loads
plugin commands, agents, skills, hooks, and optional MCP entries at session
startup; a newly installed or edited plugin is not fully visible until the next
session.
Run /guild with a brief, or with no arguments. A verb is optional: bare
/guild runs intake, classifies the work, and proposes the next step for you to
confirm:
/guild "Build a Stripe subscription flow, add tests, update the docs, draft a launch email."
/guild
The first visible sign that the plugin loaded is the SessionStart bootstrap card:
it lists the Guild version, slash commands, optional MCP servers, and doc entry
points. In a Guild root the bootstrap always loads; if the root's .guild/ layout
is older, the first write-capable entry upgrades it. The lifecycle starts when
you invoke /guild.
The first /guild run writes durable state under .guild/: spec, team, plan,
context bundles, run handoffs, review, verification, telemetry, and reflections.
You confirm after brainstorm, team-compose, and plan; the later phases run from
the approved plan with minimal interruption.
To verify hooks and audit logs are firing after restart:
- Start a fresh Claude Code session in a project where Guild is installed.
- Confirm the bootstrap card appears.
- Run a small
/guild "..."task, or use any workflow that dispatches tools. - Check for
.guild/runs/<run-id>/events.ndjson. - For v1.4 audit logging, check
.guild/runs/<run-id>/logs/v1.4-events.jsonlforhook_eventand, after tool use,tool_callrows.
Older Claude Code hosts may skip newer hook events such as PreToolUse and
PreCompact; the handlers are designed to fall through without breaking the
session. If the bootstrap card appears but no .guild/runs/ files are written,
run /guild:maintain audit and inspect hooks/hooks.json in the installed plugin.
If a Guild run failed or telemetry looks inconsistent, run /guild:maintain fix
with the run id or a short symptom; it reads recent .guild/runs evidence,
writes a diagnosis/fix plan, and asks before applying any edits.
| Variable | Default | Meaning |
|---|---|---|
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS |
unset | Set to 1 to allow Guild's experimental tmux agent-team backend. Subagents via Agent remain the default. |
GUILD_LOOP_CAP |
unset | Display/override signal for the per-lane adversarial-loop cap. The authoritative cap is the loop_cap key in .guild/settings.json (default 16, clamped to [1, 256]); CLI --loop-cap overrides per run. |
GUILD_ENABLE_DEVTEAM_REFLECT |
unset/off | Developer-team reflection gate for hooks/maybe-reflect.ts. Set to 1 only when working on Guild's own dev-team reflection workflow. |
The agent-team backend is experimental. Enable it only when teammates need to coordinate directly:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1Benchmark live runs live in the separate guild-benchmark repo, which owns its
own safety gate for spawning the real claude CLI (dry-run first). See that
repo for setup, and /guild:status dashboard to launch the benchmark UI against
the live project. The plugin only produces the data that UI reads (inventory and
run traces); it ships no UI pages of its own.
guild-memory and guild-telemetry ship as stdio MCP servers under
mcp-servers/ but are optional — Guild works end-to-end without them.
Both ship pre-bundled in runtime/guild-mcp.js, so they cold-start under plain
node with no npm install step on first use.
Use guild-memory when the wiki crosses ~200 pages (ripgrep gets slow);
use guild-telemetry for structured trace queries over .guild/runs/.
/guild "Build a Stripe subscription flow, add tests, update the docs, draft a launch email."
The session will:
- Brainstorm the spec and ask blocking questions.
- Propose a team — gaps become auto-create / skip / substitute / from-scratch prompts.
- Write per-specialist lanes with
depends-on:. - Assemble one context bundle per specialist under
.guild/context/<run-id>/. - Dispatch through the Agent tool (or, with approval, an agent-team tmux session).
- Review (spec match → quality), verify (tests / scope / success criteria).
- Reflect on skill gaps; queue evolution proposals.
You confirm after brainstorm, team-compose, and plan. Post-plan runs with minimal interruption.
If you register a new specialist with guild:create-specialist, restart or
reload the plugin before expecting /guild:plan (team is composed as a plan sub-step) or future /guild runs to
route to it. Claude Code snapshots plugin agent and skill manifests at session
startup.
Codex adversarial review is a Guild development discipline, not a default
consumer /guild loop. Review trails live under
.guild/runs/<run-id>/codex-review/*.md and can be checked with
npx tsx scripts/verify-codex-review-trail.ts <codex-review-dir>. The validator
currently requires each file's frontmatter to include final_status: satisfied or
final_status: skipped-codex-unavailable.
Every command is /guild:<verb> (the : plugin namespace is required by Claude
Code). There are 13 dispatching command files plus 11 print-only aliases; sub-verbs
are positional arguments.
| Command | Purpose |
|---|---|
/guild [brief] [research|debug] [--class=…] |
T0 orchestrator session. No verb runs intake and proposes the class and phase for you to confirm; research, debug, and --class= bind the class |
/guild:init [--learn] | adopt … |
Initialize Guild in a repo (wiki + brownfield cheap-scan map; --learn runs the full learn pipeline); adopt localizes shipped capability |
/guild:ideate |
Socratic spec — brainstorm the task into .guild/spec/<slug>.md |
/guild:plan | goal … |
Compose the per-phase team + write per-specialist lane plans; goal emits guild.goal.v1 goals from the spec |
/guild:build |
Assemble per-specialist context, dispatch the lanes, review handoffs |
/guild:qa |
The one review gate over the run |
/guild:ops |
Operations phase — release, monitoring, incident, rollback, maintenance runbooks |
/guild:learn [map|graph|knowledge|onboard|diff|explain] |
Understand-everything engine; explicit Stage-2 runs extract-structural.ts |
/guild:status [resume|stats|dashboard] |
Read-only run state; resume continues a run, stats reports usage, dashboard launches the benchmark UI |
/guild:wiki <ingest <path>|query "..."|lint> |
Project knowledge over .guild/knowledge/sources/ and .guild/wiki/ |
/guild:initiative <new|status|list|resume|update|archive|restore|close> |
Durable multi-run work (opt-in; a one-off /guild never creates one) |
/guild:config <init|reconcile|show|set|role|ui|validate|providers|models|migrate> |
Policy config; config set rejects host family, host id, and concrete model names |
/guild:maintain <evolve|rollback|audit|fix|gc|wiki revert> |
Self-heal and RSI; rollback walks a skill back through its compact history |
Documentation: https://guildstack.dev/docs
The canonical docs live at the Guild docs site (https://guildstack.dev).
https://guildstack.dev/docs/getting-started— install, first run, and basic configuration.https://guildstack.dev/docs/architecture— shipped plugin architecture, directory layout, the v2 single-verb lifecycle phases, hook inventory, backend options.https://guildstack.dev/docs/specialist-roster— the 15 domain specialist templates + the 4 machinery agents (advisor, context-manager, developer, team-lead), their triggers, DO NOT TRIGGER boundaries, and owned skills.https://guildstack.dev/docs/context-assembly— three-layer context contract, role mapping, ambient-context caveat.https://guildstack.dev/docs/wiki-pattern— categorized project memory, sources vs synthesized, decision capture, scale transition.https://guildstack.dev/docs/self-evolution— the triggers, the evolve pipeline, promotion gate, compact history + rollback.https://guildstack.dev/docs/configuration— the policy config reference:agent_mode, model tiering, SQLite index, security / secrets policy, O-3 calibration, cross-host dispatch.
Four layers: the orchestrator session, the installed plugin (skills, machinery
agents, specialist templates, commands, hooks, scripts, MCPs), the composed
specialist team in worktree isolation, and project-local state under .guild/
(including the minted specialist instances).
Diagrams and the full walkthroughs — lifecycle, skill taxonomy, project memory, context assembly, team composition, self-evolution, and specialist creation — live on the docs site: https://guildstack.dev/docs.
All project-created Guild state lives under the active root's .guild/ (never
committed by Guild itself):
.guild/
├── guild.yaml # root identity: workspace or project
├── config/project.json # durable policy only; host and models bind per session
├── settings.json # reconcile-owned settings surface (/guild:config)
├── agents/ # project-created specialists (files = source of truth)
├── skills/ # project-created skills
├── workflows/ # derived index; the five class graphs are the workflow runtime
├── loops/ # derived index; not authored truth
├── wiki/ # synthesized knowledge, decisions, standards
├── knowledge/ # graph, indexes, sources/ (ingested blobs), candidates
├── memory/ # summaries, lessons, recall index
├── initiatives/ # initiative registry, active, archived
├── teams/ # reusable team definitions
├── artifacts/ # reports, audits, handoffs, generated outputs
├── indexes/ # codebase map + compatibility indexes
├── runs/ # run traces, handoff receipts, review, verification
├── spec/ # approved specs
├── plan/ # per-task plans
├── team/ # resolved specialist teams (<slug>.<phase>.yaml)
├── context/ # per-run specialist context bundles
├── reflections/ # proposed learnings and improvements
└── evolve/ # shadow-mode eval runs and reports
Files here are latest-only. Evolve replaces the wrong span and keeps a compact
history on platform state, so there is no skill-versions/ tree. Caches and
scratch live off the repo.
Every Guild specialist inherits the same operating prelude, folded into the
using-guild skill:
- Think before doing.
- Simplicity first.
- Surgical changes.
- Goal-driven execution.
- Evidence over claims.
MIT