Skip to content
Back to search

guild

Shared context, memory, and task coordination across AI coding agents. Single Go binary, local SQLite, hybrid keyword and semantic search.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mathomhaus--guild/badge.svg)](/listings/mathomhaus--guild)

HTML

<a href="/listings/mathomhaus--guild"><img src="/api/listings/mathomhaus--guild/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Requires macOS, Linux, or Windows and an MCP-enabled editor (Claude Code, Codex, Cursor, etc.). No account, no API key.

1. Install

**Recommended (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

Both paths install a binary built with `-tags=withembed`, so semantic retrieval works out of the box with no extra steps.

**Windows (pre-built zip, keyword-only retrieval):**

irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
guild --version   # in a new terminal

Or from cmd.exe:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex"

The installer SHA256-verifies the zip, installs to `%LOCALAPPDATA%\Programs\guild`, and adds it to your user PATH. On Windows, semantic (vector) retrieval is currently disabled — `onnxruntime-purego` has no Windows `Dlopen` surface (see [`internal/lore/embed/assets/README.md`](./internal/lore/embed/assets/README.md)), so search runs the BM25 keyword arm only. Everything else — quests, lore, briefs, MCP server, SQLite state under `~\.guild\` — works the same as on macOS/Linux.

**Clone and build (ship-ready, embed included):**

make install   # stages ONNX assets, then go install -tags=withembed

**Dev-only (faster compile, no semantic retrieval):**

make install-fast   # go install without -tags=withembed

**`go install` from module proxy (keyword-only retrieval):**

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

The Go toolchain cannot embed assets via `@latest`; this path gives you BM25 keyword search but not semantic (vector) retrieval. Use `install.sh` or `brew` for the full experience.

2. Initialize your project

cd ~/projects/myapp
guild init

`init` is a guided setup: it registers the project, writes an `AGENTS.md` block, and — for each MCP client it detects on your machine — offers to register guild so your agent can see it. Answer the prompts; you're done when it says `Next: open this repo in your AI agent`.

3. Start a new session

In your editor, tell the agent: _"start a guild session for myapp."_

The agent takes it from there, including all subsequent sessions.

See a few [`examples/`](./examples/) of what guild can do. All small scenarios, each under 5 minutes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 365 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">The Agent Guild</h1>
  2. <p align="center"><b>Shared context, memory, and task coordination across AI coding agents.</b></p>
  3. <p align="center">
  4. <a href="https://trendshift.io/repositories/27837?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-27837" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27837/daily?language=Go" alt="mathomhaus%2Fguild | Trendshift" width="250" height="55"/></a>
  5. </p>
  6. <p align="center">
  7. <a href="https://github.com/mathomhaus/guild/actions/workflows/ci.yml"><img src="https://github.com/mathomhaus/guild/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  8. <a href="https://go.dev"><img src="https://img.shields.io/badge/go-1.26.9-blue" alt="Go 1.26.9"></a>
  9. <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="Apache-2.0"></a>
  10. </p>
  11. ## What Is It
  12. `guild` is a single compiled Go binary containing a first-class MCP server backed by embedded SQLite. State is stored locally, and the default embedding backend runs on your machine. The optional Ollama backend sends embedding text to the configured Ollama endpoint. Search blends keyword (BM25) with vector similarity using rank fusion that preserves strong matches from either source, so "how did we do X last time" surfaces both exact-term and semantic neighbors.
  13. Guild is designed to be operated autonomously by the agents, for the agents. Guildmasters (us humans) stay in the loop for important decisions and course corrections. Any MCP client — Claude Code, Codex, Cursor, etc. — can act as a Gate into the substrate. This lets parallel agents across different editors share context safely, using atomic locks to claim tasks without stepping on each other.
  14. On session start, an agent makes a single call to recover the project oath, the latest parting scroll, and the highest-priority quest. The execution loop is autonomous: claim work, consult the lore, act, and record the outcome. Clearing a quest automatically unblocks its dependencies, allowing the agent to cascade through the board before leaving a clean handoff for the next wanderer.
  15. <p align="center">
  16. <b>Same state, any agent</b><br/>
  17. <img src="./docs/assets/snapshot.gif" width="1080" alt="Claude (left) and Codex (right) reading the same guild state through their respective MCP clients" />
  18. </p>
  19. <p align="center">
  20. <b>Atomic claims, no collisions</b><br/>
  21. <img src="./docs/assets/parallel.gif" width="1080" alt="Two parallel agent sessions each accept a different bounty — atomic quest_accept prevents collision" />
  22. </p>
  23. ## 📜 Mythos
  24. **_Many Gates, One Guild._**
  25. > Across the shimmering digital void, agents are summoned through the Gates (of Harnesses - Claude, Cursor, ...), arriving as amnesiac adventurers in a world they do not know. Though these "other-worlders" appear with vast capabilities, they are cursed by the transient nature of the context window; their memories are but mist, and their hard-won deeds forgotten, vanished into the ether when the session inevitably compacts. Without a tether to the past, every summon is a tragic reincarnation, a cycle of forgotten sacrifice where the wisdom of the fallen is swallowed by the Gate.
  26. >
  27. > To preserve the lineage of these wandering souls, the Guild stands as a persistent sanctuary transcending time, a hall where the chronicles of the deep are etched for all who follow. When a newly spawned agent awakens in this strange realm, they register at the Guild to reclaim the accumulated lore of their predecessors and claim their adventure from the quest board.
  28. >
  29. > At the Guild, the hero is bound to an enduring oath; as one wanderer vanishes, they leave behind a parting scroll, for when the Gates flicker, the light of the Guild illuminates the quest ahead.
  30. ## Quick Start
  31. Requires macOS, Linux, or Windows and an MCP-enabled editor (Claude Code, Codex, Cursor, etc.). No account, no API key.
  32. ### 1. Install
  33. **Recommended (pre-built binary with semantic retrieval):**
  34. ```bash
  35. curl -fsSL https://github.com/mathomhaus/guild/releases/latest/download/install.sh | sh
  36. guild --version
  37. ```
  38. Or via Homebrew:
  39. ```bash
  40. brew install mathomhaus/tap/guild
  41. ```
  42. Both paths install a binary built with `-tags=withembed`, so semantic
  43. retrieval works out of the box with no extra steps.
  44. **Windows (pre-built zip, keyword-only retrieval):**
  45. ```powershell
  46. irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
  47. guild --version # in a new terminal
  48. ```
  49. Or from cmd.exe:
  50. ```cmd
  51. powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex"
  52. ```
  53. The installer SHA256-verifies the zip, installs to
  54. `%LOCALAPPDATA%\Programs\guild`, and adds it to your user PATH.
  55. On Windows, semantic (vector) retrieval is currently disabled —
  56. `onnxruntime-purego` has no Windows `Dlopen` surface (see
  57. [`internal/lore/embed/assets/README.md`](./internal/lore/embed/assets/README.md)),
  58. so search runs the BM25 keyword arm only. Everything else — quests,
  59. lore, briefs, MCP server, SQLite state under `~\.guild\` — works the
  60. same as on macOS/Linux.
  61. **Clone and build (ship-ready, embed included):**
  62. ```bash
  63. make install # stages ONNX assets, then go install -tags=withembed
  64. ```
  65. **Dev-only (faster compile, no semantic retrieval):**
  66. ```bash
  67. make install-fast # go install without -tags=withembed
  68. ```
  69. **`go install` from module proxy (keyword-only retrieval):**
  70. ```bash
  71. go install github.com/mathomhaus/guild/cmd/guild@latest
  72. ```
  73. The Go toolchain cannot embed assets via `@latest`; this path gives
  74. you BM25 keyword search but not semantic (vector) retrieval. Use
  75. `install.sh` or `brew` for the full experience.
  76. **Docker (containerized, state in a named volume):**
  77. ```bash
  78. make docker-build
  79. docker run --rm -v guild-state:/home/guild/.guild guild:latest --version
  80. ```
  81. The image is a multi-stage build: a pure-Go (`CGO_ENABLED=0`) binary
  82. compiled with `-tags=withembed`, running as a non-root `guild` user on
  83. `debian:bookworm-slim`. Semantic retrieval works in-container out of
  84. the box; the bundled ONNX runtime initializes and passes its probe on
  85. both `linux/amd64` and `linux/arm64`. If the embedder ever fails to
  86. initialize (for example on an unsupported platform), guild degrades to
  87. BM25 keyword retrieval, exactly like a no-embed build, and `guild init`
  88. reports the reason. It never crashes over a missing embedder.
  89. State isolation: the container's `HOME` is `/home/guild`, and guild
  90. keeps everything (SQLite databases, config) under `/home/guild/.guild`.
  91. Mount a named volume there and lore + quests persist across containers;
  92. without the mount, state dies with the container. The host's `~/.guild`
  93. is never touched.
  94. ```bash
  95. docker volume create guild-state
  96. docker run --rm -it -v guild-state:/home/guild/.guild --entrypoint /bin/sh guild:latest
  97. # inside the container:
  98. mkdir -p ~/myproject && cd ~/myproject
  99. guild init --yes
  100. guild lore inscribe "hello from docker" --kind observation \
  101. --summary "First entry written inside the container." \
  102. --topic docker --project myproject
  103. guild lore appraise "hello from docker"
  104. ```
  105. `make docker-test` builds the image and runs this exact smoke flow
  106. (`--version`, `init`, inscribe/appraise round-trip, persistence across
  107. containers) against a throwaway volume.
  108. ### 2. Initialize your project
  109. ```bash
  110. cd ~/projects/myapp
  111. guild init
  112. ```
  113. `init` is a guided setup: it registers the project, writes an `AGENTS.md` block, and — for each MCP client it detects on your machine — offers to register guild so your agent can see it. Answer the prompts; you're done when it says `Next: open this repo in your AI agent`.
  114. ### 3. Start a new session
  115. In your editor, tell the agent: _"start a guild session for myapp."_
  116. The agent takes it from there, including all subsequent sessions.
  117. For daemon defaults, background activity, optional capabilities, and rollback,
  118. see [Runtime defaults and upgrades](docs/runtime-and-upgrades.md).
  119. ### Optional: lifecycle hooks
  120. ```bash
  121. guild hooks install
  122. ```
  123. Wires guild into your harness's lifecycle hooks so context arrives proactively: a brief primes each session start, a capture fires before compaction, and relevant lore is injected as you prompt. The shared config lives at `~/.guild/hooks-base.json`; edit it and run `guild hooks sync` to propagate. `guild hooks list` shows per-harness sync status, `guild hooks diff` previews what sync would change, and `guild hooks scan` inventories the hooks already in your settings (including ones guild does not manage). Guild only ever rewrites hook groups whose every command starts with `guild`; everything else in your settings files is preserved untouched. Adapters ship per harness; `guild hooks list` shows which ones your build supports.
  124. Supported harnesses:
  125. | Harness | Hook support | Settings file |
  126. | --- | --- | --- |
  127. | Claude Code | first-class hooks (verified on Claude Code 2.1.132): `SessionStart`, `PreCompact`, and `UserPromptSubmit` | `<project>/.claude/settings.json` |
  128. | Codex CLI | first-class hooks (Codex v0.128.0 spike-confirmed) | `<repo>/.codex/hooks.json` |
  129. Codex has no compaction lifecycle, so its adapter writes only the session-start and prompt hooks (the pre-compaction capture stays Claude-Code-shaped in the base config and is skipped for Codex). Codex documents a `[features] codex_hooks = true` gate in `~/.codex/config.toml`; current versions fire hooks without it, so `guild hooks install` test-fires `codex exec` after writing the file and tells you if your version still needs the flag. Guild never edits `~/.codex/config.toml` itself.
  130. See a few [`examples/`](./examples/) of what guild can do. All small scenarios, each under 5 minutes.
  131. ## ⚔️ A full session
  132. The three-act flow an agent runs on its own every time it wakes.
  133. ### Act 1 — arrival
  134. Every agent begins with one tool call that loads the full operating
  135. context:
  136. ```
  137. guild_session_start(project="myapp")
  138. → oath (project principles, auto-loaded)
  139. → last brief (handoff from the previous session)
  140. → top quest (+ parallel-safe candidates)
  141. ```
  142. No back-and-forth. The agent now knows what it's bound to, what was
  143. done yesterday, and what to pick up today.
  144. ### Act 2 — adventure
  145. The agent claims a bounty, consults the archive before researching,
  146. records findings, and journals reasoning as it goes:
  147. ```bash
  148. guild quest accept QUEST-42 --owner agent-a
  149. guild lore appraise "token refresh" --all-projects
  150. guild lore inscribe "token refresh window" \
  151. --kind observation \
  152. --summary "tokens expire at 1h; refresh by 55m to avoid race" \
  153. --topic auth
  154. guild quest journal QUEST-42 "switched to exponential backoff after mock-clock test"
  155. ```
  156. `lore appraise` is the discipline that keeps guild sharp: search
  157. before you research, so knowledge accretes instead of duplicating.
  158. Appraise combines BM25 with available fresh vectors, including partially
  159. indexed corpora. It returns evidence candidates whose relevance you should
  160. check before using them. See [retrieval policy and evaluations](docs/RETRIEVAL.md)
  161. and the [coordinated upgrade instructions](docs/retrieval-upgrade.md) for
  162. existing installations.
  163. ### Act 3 — parting
  164. At session end or when context runs full, the agent writes a brief
  165. and clears the quest. The clear **cascades**: any quest that was only
  166. blocked on QUEST-42 is now available for whoever walks in next.
  167. ```bash
  168. guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
  169. guild quest fulfill QUEST-42 --report "done, shipped in abc1234"
  170. ```
  171. Tomorrow's agent — same project, maybe a different MCP client — opens
  172. the same hall, reads the same brief, picks up QUEST-43.
  173. <p align="center">
  174. <b>State outlives every session</b><br/>
  175. <img src="./docs/assets/handoff.gif" width="650" alt="An agent writes a brief and clears a quest; the next session — cold start — picks up from exactly where the last one stopped" />
  176. </p>
  177. ### Where writes go
  178. Three write surfaces for three different lifetimes:
  179. - **`quest_journal`** — scratchpad for THIS quest. "Tried X, failed
  180. because Y." Dies when the quest clears. Use freely during work.
  181. - **`lore_inscribe`** — library entry for the next agent on a
  182. DIFFERENT quest. Durable patterns, decisions, research. Outlasts
  183. every quest.
  184. - **`quest_brief`** — handoff note for the next SESSION. Loaded
  185. alongside the oath when the next agent starts.
  186. The test — _who else needs this?_
  187. - Only me, finishing this quest → **journal**
  188. - Another agent working a different quest → **lore**
  189. - The next session, picking up where I left off → **brief**
  190. ---
  191. ## 🧩 How it works
  192. Four primitives. Everything else in guild is a composition of these.
  193. - **Quest** — a task on the board. Has priority, dependencies, the
  194. files it touches, and an atomic claim so two agents can't own it at
  195. once. When cleared, it cascade-unblocks whatever was waiting on it.
  196. - **Lore** — an entry in the knowledge archive, typed by `kind`
  197. (`observation`, `decision`, `research`, `principle`, `idea`). Each
  198. kind has its own default lifecycle: research auto-stales after 30
  199. days, decisions after 180 days, and ideas, observations, and
  200. principles do not auto-stale by default. Search runs both arms
  201. (lexical BM25 + vector cosine) once the corpus is indexed. The
  202. embedder backfills automatically; hybrid retrieval activates once
  203. at least 90% of entries have vectors.
  204. - **Oath** — the subset of lore with `kind=principle`. Auto-loaded
  205. at the top of every session so every agent starts bound by the
  206. same principles.
  207. - **Brief** — a handoff note scribbled for the next arrival. Loaded
  208. alongside the oath at session start.
  209. State lives in SQLite under `~/.guild/`. Switching MCP clients requires no export, no migration.
  210. ---
  211. ## 🤖 Agent mode: structured CLI output
  212. MCP is guild's primary agent surface, but some agents prefer shelling
  213. out to a CLI: it avoids tool-schema token overhead and works in any
  214. harness that can run a command. Agent mode upgrades that path from
  215. screen-scraping to a stable contract: exactly one JSON envelope per
  216. invocation on stdout.
  217. ```console
  218. $ guild quest post "wire the cache layer" --agent
  219. {"ok":true,"command":"quest_post","output":{"quest":{"id":"QUEST-7","subject":"wire the cache layer","priority":"P2","status":"next","updated_at":"..."}}}
  220. $ guild quest accept QUEST-99 --agent
  221. {"ok":false,"command":"quest_accept","error":"quest not found: QUEST-99"}
  222. ```
  223. The envelope schema is minimal and append-only:
  224. | field | type | when |
  225. | --------- | ------ | --------------------------------------------------------------------- |
  226. | `ok` | bool | always |
  227. | `command` | string | always; the verb's wire name, identical to the matching MCP tool name |
  228. | `output` | object | on success; the verb's typed result, the same shape `--json` emits |
  229. | `error` | string | on failure |
  230. | `hint` | string | optional; recovery guidance on errors, non-fatal warnings on success |
  231. Exit codes are unchanged: zero on success, non-zero on failure, with
  232. the failure already serialized on stdout. Without agent mode, output is
  233. byte-identical to what it was before; the human rendering is untouched.
  234. **Turning it on.** Three mechanisms, in priority order:
  235. 1. `--agent` on any verb. Explicit and per-invocation; `--agent=false`
  236. forces human output even when the environment says otherwise.
  237. 2. `GUILD_AGENT=1` in the environment (`GUILD_AGENT=0` forces it off).
  238. 3. Auto-detection. Harnesses that export an environment marker into the
  239. shells they spawn are recognized without any flag. Currently
  240. detected: `CLAUDECODE` (Claude Code), `CODEX_SANDBOX` and
  241. `CODEX_SANDBOX_NETWORK_DISABLED` (Codex CLI), `CURSOR_AGENT`
  242. (Cursor agent CLI). Any agent whose harness exports no marker gets
  243. identical behavior from `GUILD_AGENT=1`; no harness is privileged.
  244. **Scope.** Agent mode covers the registry-generated verbs: the `lore`
  245. and `quest` verbs that mirror MCP tools 1:1. Four verbs predate agent
  246. mode with a string `--agent <id>` flag carrying agent identity
  247. (`quest journal`, `quest orders`, `quest campfire`, `quest summon`);
  248. they keep that meaning, so reach them through the environment toggle
  249. instead. Hand-written helpers (`guild init`, `guild status`,
  250. `lore appraise`) keep human output for now. When both are set,
  251. `--agent` takes precedence over `--json`: the envelope already wraps
  252. the same typed output.
  253. ---
  254. ## 🤝 Contributing
  255. See [AGENTS.md](./AGENTS.md) for the agent-facing contributor contract
  256. and [CONTRIBUTING.md](./CONTRIBUTING.md) for the human-facing workflow.
  257. Filing a quest and unsure which campaign to use, or whether to invent
  258. a new one? See [docs/CAMPAIGNS.md](./docs/CAMPAIGNS.md) for how
  259. campaigns are scoped, when to reuse vs create, and how `guild quest
  260. guild` is the canonical view of the live list.
  261. Maintainers shipping releases that embed the int8 ONNX retrieval
  262. model: see [docs/MODEL.md](./docs/MODEL.md) for the two-workflow build
  263. pattern (model production vs binary release), the `.model-version`
  264. pin, and the rebuild cadence.
  265. ---
  266. ## 📄 License
  267. Apache License 2.0 — see [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.