Guild

Shared context, memory, and task coordination for AI coding agents across sessions and editors.

Source repo
mathomhaus/guild
Stars
★ 302
Last updated
3d ago
License
Apache-2.0
Primary language
Go

At a glance

How it runs
CLIMCP server
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Go 1.26.9 (only for clone/build or go install)Docker (optional container path)Shell / CLINetwork accessLocal filesystemMCP Server
Typical use
Developers who switch between Claude Code and Codex on the same repository and want the second session to pick up the previous brief and quest state.
Not a fit if
  • Teams needing semantic retrieval on Windows (BM25 keyword search only)
  • Users who need zero outbound embedding text while enabling the Ollama backend
  • Manual workflows with no MCP-capable editor

What does this agent do, and when should you use it?

Guild is a single compiled Go binary that ships a first-class MCP server backed by embedded SQLite, giving AI coding agents persistent shared context instead of amnesia between sessions. It models state with four primitives: Quests (tasks with priority, dependencies, touched files, and an atomic claim), Lore (typed knowledge entries — observation, decision, research, principle, idea — with per-kind auto-stale lifecycles), the Oath (the kind=principle subset auto-loaded at session start), and Briefs (handoff notes for the next session). Search fuses BM25 keyword ranking with vector cosine similarity; the default embedding backend runs locally, while the optional Ollama backend sends embedding text to the configured endpoint. Any MCP client — Claude Code, Codex, Cursor — can act as a gate into the same substrate, and clearing a quest cascade-unblocks whatever depended on it. State sits in SQLite under ~/.guild/, so switching clients needs no export or migration, and the CLI mirrors the MCP verbs with an --agent mode that emits one stable JSON envelope per invocation.

On session start an agent calls guild_session_start(project="myapp") once and receives the oath, the latest brief, and the top quest plus parallel-safe candidates. It claims work with guild quest accept QUEST-42 --owner agent-a, which is atomic so two agents cannot own the same quest. Before researching, it queries with guild lore appraise "token refresh" --all-projects, which combines BM25 with available fresh vectors and returns evidence candidates; findings are written via guild lore inscribe with a kind and topic, and per-quest reasoning goes to guild quest journal. At the end it writes guild quest brief for the next session and clears work with guild quest fulfill QUEST-42 --report, which cascades to unblock dependent quests. The same lore and quest verbs run from the shell: --agent, GUILD_AGENT=1, or auto-detected harness markers (CLAUDECODE, CODEX_SANDBOX, CURSOR_AGENT) switch output to a minimal append-only envelope with ok, command, output/error, and an optional hint, while exit codes stay zero on success. guild hooks install wires session-start briefs, pre-compaction capture, and prompt-time lore injection into <project>/.claude/settings.json or <repo>/.codex/hooks.json, rewriting only hook groups whose commands all begin with guild.

  1. Developers who switch between Claude Code and Codex on the same repository and want the second session to pick up the previous brief and quest state.
  2. Teams running parallel agent sessions that need to divide a task board without duplicate work, relying on the atomic quest claim.
  3. Long-lived projects that want research findings and decisions to accumulate as searchable Lore instead of vanishing at context compaction.
  4. Individual developers who want fully local SQLite state under ~/.guild/ with no account or API key.
  5. Agent harnesses that prefer shelling out to a CLI over MCP tool schemas, needing one predictable JSON envelope per call.
  6. Teams that want containerized state isolation by mounting a named volume at /home/guild/.guild.

How do you install or deploy this agent?

On macOS/Linux, install the pre-built binary with semantic retrieval:

curl -fsSL https://github.com/mathomhaus/guild/releases/latest/download/install.sh | sh
guild --version

Or via Homebrew:

brew install mathomhaus/tap/guild

On Windows, use the PowerShell installer (keyword-only retrieval):

irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
guild --version

Build from a clone to get embedded ONNX assets:

make install

Faster dev build without semantic retrieval:

make install-fast

Via the module proxy (BM25 only):

go install github.com/mathomhaus/guild/cmd/guild@latest

Docker:

make docker-build
docker run --rm -v guild-state:/home/guild/.guild guild:latest --version

How do you use this agent?

Initialize the project first; init registers it, writes an AGENTS.md block, and offers to register guild with each MCP client it detects:

cd ~/projects/myapp
guild init

Then tell your editor's agent to start a guild session for the project. A typical agent loop:

guild quest accept QUEST-42 --owner agent-a
guild lore appraise "token refresh" --all-projects
guild lore inscribe "token refresh window" --kind observation --summary "tokens expire at 1h; refresh by 55m to avoid race" --topic auth
guild quest journal QUEST-42 "switched to exponential backoff after mock-clock test"
guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
guild quest fulfill QUEST-42 --report "done, shipped in abc1234"

Optionally install lifecycle hooks so context arrives proactively:

guild hooks install
guild hooks list
guild hooks sync

Enable structured agent output explicitly on any verb:

guild quest post "wire the cache layer" --agent
guild quest accept QUEST-99 --agent

What are this agent's strengths and limitations?

Pros
  • State is genuinely shared across sessions and clients: one SQLite store serves Claude Code, Codex, and Cursor with no export or migration step.
  • Quest claims are atomic, so parallel agent sessions cannot collide on the same task.
  • Retrieval fuses BM25 with vector cosine using rank fusion, preserving strong matches from either arm, and appraise enforces search-before-research.
  • Install is one command via the release script or Homebrew, with no account or API key and a local default embedding backend.
  • Agent mode offers a minimal append-only JSON envelope contract, useful for harnesses avoiding MCP tool-schema token overhead.
Limitations
  • Semantic retrieval is disabled on Windows because onnxruntime-purego has no Windows Dlopen surface; only BM25 runs there.
  • Full semantic retrieval requires a -tags=withembed build; go install @latest cannot embed assets and yields keyword-only search.
  • Enabling the optional Ollama backend sends embedding text to the configured endpoint, so data is no longer strictly local.
  • Evidence is largely the README and demo GIFs; there are no third-party benchmarks for retrieval quality or coordination overhead.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
Guild This agent 50 · Major gaps CLIFree ★ 302 3d ago Go Codex · Claude Code
myc Local Agent Memory 87 · Good CLIFree ★ 14 11d ago TypeScript Codex · Claude Code
Mnemo Cortex 75 · Good Self-hosted serviceFree ★ 159 4d ago Python Codex · Claude Code · Claude.ai
Caura 70 · Some gaps Self-hosted serviceFreemium ★ 541 1d ago Python Codex · Claude Code · Claude.ai

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
50/ 100 5-point scale 2.5 / 5
Trust 12/29
Reliability 8/14
Adaptability 10/18
Convention 10/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust12 / 29 · 2.1/5

README states local-first operation, on-machine default embedding, and that optional Ollama sends embedding text to a configured endpoint, giving decent data-flow transparency (2). least_privilege scores 1: `guild hooks install` rewrites editor settings files and injects lifecycle hooks; it claims to only rewrite guild-prefixed command groups, but this is write access to user config with no explicit least-privilege constraint. user_confirmation scores 1: init is guided with prompts, but confirmation boundaries for hook installation and MCP client auto-registration are vague. sensitive_data_handling scores 1: SECURITY.md points to a README Privacy section that is absent from the evidence, so usage.log contents and opt-out cannot be verified. external_effects scores 1: writes to settings files, PATH, and ~/.guild state exist, with rollback only referenced via a link (docs/runtime-and-upgrades.md not provided). rollback scores 1: only a claim of rollback docs, no concrete mechanism. dependency_security scores 1: go.mod pins recent versions but there is no checksum verification, SBOM, or dependency audit evidence; onnxruntime-purego is a pseudo-version commit. source_attribution scores 2: LICENSE carries a copyright line and the model workflow emits a MANIFEST recording BAAI provenance and tool versions, but publisher identity is unverified.

Reliability8 / 14 · 2.9/5

README is internally consistent: install paths, retrieval degradation, and Windows limitations align (2). dependency_availability scores 1: requires the unusual Go 1.26.9 and an untagged pseudo-version of onnxruntime-purego, posing availability risk; no vendoring or checksum notes. failure_messages scores 2: agent mode defines an ok/error/hint envelope with exit codes, and embedder failure degrades with a reported reason, but no actual output samples are verified.

Adaptability10 / 18 · 2.8/5

Targets coding agents across multiple MCP clients (Claude Code, Codex, Cursor) with concrete scenarios (2). capability_boundaries scores 2: clearly separates journal/lore/brief write surfaces and notes Windows lacks semantic retrieval and go install lacks embedding. trigger_precision scores 1: session start relies on the agent interpreting natural-language instructions, and hook triggering depends on environment-variable detection, so precision depends on external harness behavior with insufficient evidence. environment_fit scores 2: covers macOS/Linux/Windows/Docker, but Windows is feature-limited and the Go version requirement is strict, hence the deduction.

Convention10 / 18 · 2.8/5

README is well-structured with clear sections pointing to docs/ and examples/ (2). install_notes scores 3: installation is thorough, covering curl, brew, PowerShell, make, go install, and Docker with trade-offs for each. naming_stability scores 1: heavy bespoke terminology (quest/lore/oath/brief/guildmaster), and the agent-mode envelope claims append-only but carries no version number, so stability evidence is weak. examples_and_faq scores 1: only links to an examples/ directory not shown in evidence, and no FAQ. known_limitations scores 2: explicitly lists Windows lacking semantic retrieval, go install limits, and Codex lacking compaction lifecycle. license scores 3: full Apache-2.0 text with copyright line. versioning_changelog scores 1: SECURITY.md says pre-1.0, no CHANGELOG, no versioning policy detail. maintenance_responsibility scores 1: publisher unverified, only SECURITY.md mentions response timelines, ownership unclear.

Effectiveness7 / 13 · 2.7/5

Agent mode emits a single JSON envelope with clear fields, easy for programs to consume (2). marginal_value scores 2: cross-agent shared context and atomic task claiming have real value, but many similar MCP memory solutions exist and differentiation evidence is limited. cost_benefit scores 1: requires an embedded ONNX runtime, ~127MB model download, and a specific Go version, so deployment cost is high while benefit is unquantified.

Verifiability3 / 8 · 1.9/5

README claims CI badges, Docker tests, and retrieval evaluation docs, but evidence shows only workflow files, no test results or evaluation data (1). cross_source_corroboration scores 1: README partially aligns with SECURITY.md and go.mod, but the Privacy section is missing and examples/docs content is not provided, limiting corroboration. fact_inference_separation scores 1: docs blend factual description with mythic narrative, and performance/retrieval-quality claims lack supporting data, blurring fact and inference.

Risks and how to mitigate them
  • `guild hooks install` rewrites editor settings files and injects hooks; review its write scope and rollback before installing.
  • The README Privacy section referenced by SECURITY.md is absent from the evidence, so usage.log contents and opt-out cannot be verified.
  • Depends on Go 1.26.9 and an untagged onnxruntime-purego pseudo-version, posing build reproducibility and dependency availability risks.
  • Publisher identity is unverified; maintenance responsibility and update path are unclear.
  • Semantic retrieval requires a ~127MB model download and is unsupported on Windows; assess deployment cost and platform differences.
Evidence confidence: Low Reviewed Oct 29, 2026 Reviewed revision 13130ff34aec
See the full review method →

FAQ

Does it cost anything or need API keys?
No. The README states no account and no API key are required, and the install script and Homebrew both deliver a pre-built binary whose default embedding backend runs on your machine.
What changes on Windows?
Vector retrieval is currently disabled there because onnxruntime-purego lacks a Windows Dlopen surface, so search runs the BM25 keyword arm only. Quests, lore, briefs, the MCP server, and SQLite state under ~\.guild\ all work as on macOS/Linux.
Do my agents have to speak MCP?
MCP is the primary surface, but the lore and quest verbs also run from the CLI and can emit a stable JSON envelope via --agent or GUILD_AGENT=1. Note that four older verbs (quest journal, quest orders, quest campfire, quest summon) use --agent for agent identity, so reach agent mode through the environment toggle for those.
Will guild hooks install overwrite my editor settings?
It only rewrites hook groups whose every command starts with guild; everything else in your settings files is preserved, and guild never edits ~/.codex/config.toml itself.
Where is state stored, and does Docker touch my host?
State lives in SQLite under ~/.guild/. In the container HOME is /home/guild and all state sits under /home/guild/.guild, so only a mounted volume persists and the host ~/.guild is never touched.
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related agents