agent-guild

A ready-made multi-agent setup for Claude Code, Cursor and Codex, installed into a project with one command. (The Sonnet/Opus/Haiku tiering below is Claude Code's; Cursor and Codex agents inherit the session model.) A Sonnet orchestrator delegates to specialist subagents (Opus architect and grader, Sonnet coders, Haiku utility), and three features come wired in:

• Multiple agents: architect, coder (parallel-safe), code-grader and utility, plus the orchestrator rules that decide who does what: routing, briefs and reports. See development-workflow.md.
• Memory, in two layers, so context survives between sessions:
  • memory-bank: current state (what's being worked on, decisions, progress), in a git-tracked memory/ folder.
  • jev-mem: long-term facts, recalled by relevance through an MCP server and session hooks.
• Spec-Driven Development (SDD), via sdd-feature: specs, design, interfaces, implementation and grading, with approval gates between phases. Included by default; omit it with --without sdd.

uvx agent-guild /path/to/project

                         user
                          │  approvals (chat only)
                          ▼
              ┌──────────────────────┐   reads/writes   memory/ (state, gate status)
              │ orchestrator (Sonnet)│ ───────────────▶ jevmem (facts)      ← single writer
              └──────────────────────┘                  specs/, wireframes/
        plans │      chunks │       grade │      chores │
              ▼             ▼             ▼             ▼
        architect        coder ×N     code-grader     utility
        (Opus, RO)      (Sonnet)      (Opus, RO)      (Haiku)
              └── all read specs/, memory/, jevmem recall; report memory candidates + friction ──┘

Not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

Files

These are the Claude Code sources; the installer converts them for Cursor and Codex.

Install

Quick: the installer (per project)

agent-guild copies everything into a project (plain copies, not links, so the project can edit them) and is safe to re-run: existing files that differ from the selected source are skipped unless you pass --force. It resolves and validates all sources and configuration in an in-memory plan before writing project files. --dry-run builds the same plan (including downloads into a temporary directory), without writing to the project. Preflight failures leave the project unchanged; filesystem errors during the final writes can still leave a partial install.

uvx agent-guild /path/to/project --dry-run

uvx agent-guild /path/to/project

It does, in the project, for each coding tool it finds (see Tools below):

• copies the agents in that tool's format and folder (.claude/agents/*.md; .cursor/agents/*.md with readonly instead of disallowedTools; .codex/agents/*.toml), and one shared .agents/development-workflow.md, explicitly read by Claude Code, Cursor and Codex;
• copies the memory-bank, jev-memory and sdd-feature skills into that tool's skills folder (.claude/skills/, .cursor/skills/, .agents/skills/ for Codex), cloned from GitHub, or from local clones with --sources-dir DIR;
• adds three removable sections: Agents and delegation, Memory bank and Phase Gate Protocol. If AGENTS.md exists, that is the target. If only CLAUDE.md exists and only Claude Code is selected, it is the target instead. Otherwise, creates AGENTS.md. Existing sections in the target are preserved; conflicts with sections in the other instruction file produce warnings. No developer rules are moved, deleted or migrated between files. Modern Claude Code (v2.1.277+, with built-in AGENTS support enabled) can read AGENTS.md directly when no project/local CLAUDE.md takes precedence. Use --claude-compat to add an @AGENTS.md import for older versions or sessions that prefer CLAUDE.md; meaningful existing Claude content is retained. With both files present, the installer warns if Claude may not load the new shared instructions. See Claude's instruction loading docs;
• adds the pinned jevmem server to the tool's MCP config (.mcp.json, .cursor/mcp.json, .codex/config.toml), merging into existing files. New Codex servers reuse matching project entries from .mcp.json, then .cursor/mcp.json, before falling back to defaults; existing Codex entries always win;
• for Claude Code only: adds the jevmem hooks to .claude/settings.json. It preserves existing project/local model and auto-memory preferences; only absent preferences default to sonnet and autoMemoryEnabled: false. --model and --disable-auto-memory explicitly override the corresponding destination settings.

Tools. The installer detects what the project uses: .claude/ or CLAUDE.md → Claude Code, .cursor/ → Cursor, .codex/ or .agents/skills/ → Codex; with several, it installs for all of them, and with none, for Claude Code. Override with --tools claude,cursor,codex. Cursor and Codex agents don't carry the Claude model tiering (Cursor gets model: inherit, Codex inherits the session model) and Codex has no read-only switch for an agent, so the read-only agents say it in their instructions. Cursor also reads .claude/ and .agents/ folders, so with several tools installed it may list a skill twice.

Still per machine, once: uvx jevmem config init and uvx --from jevmem jevmem warmup.

Prefer to do it by hand, or want the per-machine variant (agents and memory in ~/.claude for every project)? See docs/manual_installation.md.

Development

git clone https://github.com/illescasDaniel/agent-guild && cd agent-guild
uv run pytest
uv run agent-guild /path/to/project --dry-run

From a checkout, the CLI reads agents/, templates/ and development-workflow.md at the repo root; the published wheel bundles them.

Adding it to a project that already has its own setup

The installer never overwrites a file that differs from the shipped one (and skips rules sections that AGENTS.md or CLAUDE.md already has), so it is safe to run on a project with its own agents, skills and rules. After it runs:

• Skipped files are yours. Anything the log marks skipped ... differs keeps your version. If it is an older or customised copy of a shipped one (the sdd-feature skill, code-grader, jev-memory), diff it against the shipped file and merge what you want by hand. --force replaces it instead.
• All tools reuse project sources. For agents, choose the first existing copy in Claude, Cursor, Codex order; convert it for missing tool copies. Language coders inherit the project's generic coder body. For skills, choose .claude/skills, .cursor/skills, .agents/skills, then legacy .codex/skills, and use that source for every tool. Full supporting trees are copied. Existing divergent copies stay protected and produce drift warnings. The selected source is printed, including in dry-runs. These are plain copies; later edits are not synchronized. --force deliberately uses shipped sources instead. Codex discovers project skills under .agents/skills.
• Upstream skills are pinned. Each release selects exact Git commits in SKILL_REVISIONS; fetching verifies the resolved commit. .agents/skill-sources.json records the upstream URLs, revisions and content hashes. --sources-dir records local plus content hashes instead, so local edits are visible in provenance.
• New files can land next to yours. A skill folder you already have keeps its SKILL.md, but the shipped files that are missing (templates, scripts) are added beside it. If .claude/skills is a symlink to .cursor/skills, the log says so, and the skills are written there.
• Cursor reads .claude/agents/ too. The agents installed here work in Cursor without copies in .cursor/agents/ (.cursor/agents/ wins on a name clash). Cursor ignores tools, disallowedTools and effort, so the read-only agents are not read-only there. If your project has a test that requires every .claude/agents/*.md to have a .cursor/agents/ twin, relax it to require the twin only for the Cursor agents.
• Skip what you already have with --without memory-bank / jevmem / sdd, for example when your own memory-bank skill has a different name.

Design choices

• The orchestrator is the only writer of memory. Parallel coders writing memory/ would conflict, and someone has to decide what is worth remembering. Subagents can read memory, including jevmem recall, and return Memory candidates and Friction sections in their reports.
• Subagents don't get the jevmem hooks. The SessionStart and UserPromptSubmit hooks fire in the main session only. So the agents that need history (architect, coder, grader) can call memory_recall themselves.
• The files on disk are the hand-off. Once a wireframe, SPEC.md or interfaces exist, briefs point to them instead of restating them. That solves the cold-start problem without long prompts.
• disallowedTools instead of a tools allowlist for architect, coder and grader. They inherit project MCP servers (e.g. code-navigation MCPs) without per-project edits, while jevmem writes and file edits stay blocked where needed. utility keeps a plain allowlist.
• Language coders are separate, opt-in agents with an allowlist. A generic coder only inherits the project's navigation MCPs; in practice it still reached for grep and sed, because the MCP tools arrive deferred (name only) and the brief or its own habits point elsewhere. coder-python, coder-swift and coder-typescript (--with) are generated from coder.md plus a navigation section that names the MCP's tools, and list those tools in tools: so they load up front. An AGENTS.md rule routes that language's work to them. Without --with, nothing changes.
• The grader runs on Opus. The code it grades was written by Sonnet coders, so a different, stronger model gives a more independent review.
• SDD is included by default. A standard installation adds its skill, grader and Phase Gate Protocol. Pass --without sdd to omit those additions. Existing developer-owned files and rules are not removed by this flag. The workflow activates SDD when the project adopts the protocol or explicitly invokes the skill.
• Gates and gate status. SDD gates stay between the orchestrator and the user. The gate status is recorded in memory/activeContext.md, so a new session resumes at the right gate.

License

MIT