# agency-agents: features, protocols, quickstart

## TL;DR

agency-agents, also titled The Agency, is an MIT-licensed collection of Markdown role definitions for coding agents, grouped into divisions such as engineering, design, marketing and security, by msitarzewski. Scripts convert and install them into Claude Code, Codex, OpenCode and other tools. It also includes NEXUS, written playbooks for running the roles as a team.

## Key facts

| Field | Value |
| --- | --- |
| Type | Orchestrator |
| Languages / SDKs | Markdown, Shell |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Crew / roles |
| GitHub stars | 155,430 (as of 2026-09-30) |
| GitHub forks | 25,076 |
| Last push | 2026-09-29 |
| Latest release | No release published |
| Repository | [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) |
| Documentation | [github.com](https://github.com/msitarzewski/agency-agents/blob/main/README.md) |
| Last verified | 2026-09-30 |

## Key features

- Role definitions as Markdown files in division folders (engineering, design, marketing, security, game development, healthcare and more), each with identity, workflow, deliverables and success criteria. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md))
- `convert.sh` and `install.sh` generate and install the roles for Claude Code, Codex, OpenCode, OpenClaw, Hermes, Gemini CLI, Cursor, Copilot, Aider, Windsurf, Kimi Code and DeepSeek Harness, each in that tool's native format. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-multi-tool-integrations))
- Selective installs by division or by agent name, plus a dry-run flag, to keep the installed set small. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md))
- An Agents Orchestrator role that manages a PM, architecture, developer and QA pipeline with per-task QA loops, retry limits and escalation. ([source](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md))
- NEXUS playbooks: phased operating model with Full, Sprint and Micro modes, quality gates, and a handoff-template set for agent-to-agent work transfer. ([source](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md))
- Worked multi-agent examples showing sequential handoffs and parallel activations, such as a four-week startup MVP. ([source](https://github.com/msitarzewski/agency-agents/blob/main/examples/workflow-startup-mvp.md))
- A Hermes router plugin that exposes search, inspect, load and delegate tools instead of loading hundreds of skills at startup. ([source](https://github.com/msitarzewski/agency-agents/blob/main/integrations/hermes/README.md))
- An optional MCP memory pattern: a prompt section that tells an agent to use remember, recall, rollback and search tools from any MCP memory server the user configures. ([source](https://github.com/msitarzewski/agency-agents/blob/main/integrations/mcp-memory/README.md))

## Architecture and orchestration pattern

Pattern: Crew / roles.

The repository is content plus shell scripts. Each role is a Markdown file with front matter and a prompt-style persona. `convert.sh` writes tool-specific outputs under `integrations/` (for example Codex TOML custom agents, Gemini CLI and OpenCode agent files, Cursor rules, a single Windsurf rules file, an OpenClaw set of SOUL, AGENTS and IDENTITY files), and `install.sh` copies them into each tool's agent or skill directory. Claude Code and Copilot use the Markdown files directly.

No process runs the agents. Coordination is described in prose: the Agents Orchestrator role tells the host to spawn a senior project manager, then architecture, then a dev and QA loop, and NEXUS lays out phases, gates and handoff templates. The human or the host harness performs each activation, and the examples show the user activating roles one at a time, with some steps running in parallel.

State is whatever the host and the files hold: the orchestrator role tracks task and phase status in project files it writes, and the optional MCP memory pattern relies on a memory server the user supplies. The Hermes plugin is the one integration with code of its own; its delegate tool hands work to Hermes' subagent lifecycle.

### Human in the loop

Coordination is manual by default: the README and the example workflows have the user activate each role in the host tool and review its output before the next step. The NEXUS strategy describes gates with named gatekeepers and sign-offs between phases, and the Agents Orchestrator role retries a failing task up to three times before escalating. These are instructions to the host agent rather than enforced controls, and the docs describe no interrupt or approval mechanism beyond what the host harness provides.

### Harnesses it can drive

- Claude Code ([evidence](https://github.com/msitarzewski/agency-agents/blob/main/README.md))
- Codex ([evidence](https://github.com/msitarzewski/agency-agents/blob/main/integrations/codex/README.md))
- OpenCode ([evidence](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-multi-tool-integrations))
- OpenClaw ([evidence](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-multi-tool-integrations))
- Hermes ([evidence](https://github.com/msitarzewski/agency-agents/blob/main/integrations/hermes/README.md))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Partial (checked 2026-09-30) | [link](https://github.com/msitarzewski/agency-agents/blob/main/integrations/mcp-memory/README.md) | Documents an optional pattern where agents call remember, recall, rollback and search tools from any MCP memory server configured in the host's MCP client; the repo ships no MCP server or client itself. |
| A2A | Unknown (checked 2026-09-30) | — | No A2A / Agent2Agent mention in the README; repo code search returned only an identity-and-trust role file and a checksum file, not read as protocol support. |
| AG-UI | Unknown (checked 2026-09-30) | — | No AG-UI mention in the README or repository code search; not checked against a listing in the AG-UI README. |

## Best for

- Coding-agent users who want a large catalog of role personas, including non-engineering ones, in the tool they already use. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Trying a phased multi-role workflow (PM, architect, developer, QA loop) with written playbooks before building any automation. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Teams that switch between coding tools and want the same roster converted to each tool's native agent or rules format.
- Hermes users who want a searchable roster exposed through four lazy-loading tools.

## Not for

- Automated multi-agent runs with state, scheduling or enforced gates; the orchestration is written instructions, not a runtime.
- Building agents in code; there is no SDK, only persona files, converters and docs.
- OpenCode users who want the full roster installed at once; the README says OpenCode registers only about 119 agents.

## Quickstart

```sh
./scripts/install.sh --tool claude-code
```

Install not yet verified by this site.

```bash
# From a clone of the repo
git clone https://github.com/msitarzewski/agency-agents.git && cd agency-agents

# Claude Code: copy roles into ~/.claude/agents/
./scripts/install.sh --tool claude-code

# Only some divisions
./scripts/install.sh --tool claude-code --division engineering,security

# Other tools: generate integration files first, then install
./scripts/convert.sh
./scripts/install.sh --tool codex

# Desktop installer (macOS)
brew install --cask msitarzewski/agency-agents/agency-agents

# Then, in Claude Code:
# "Activate Frontend Developer mode and help me build a React component"
```

### Common pitfalls

- Generated integration files do not exist on a fresh clone; run `./scripts/convert.sh` before installing for tools other than Claude Code.
- OpenCode silently drops agents beyond roughly 119 (upstream OpenCode bug linked from the README); install a subset with `--division`.
- The README recommends the separate Agency Agents desktop app (own repository and releases) as the main install path; the scripts install the same roles.
- The MCP memory pattern needs you to run and configure an MCP memory server exposing remember, recall, rollback and search; none is provided.
- The repository publishes no GitHub releases, so installs track the main branch.

Official quickstart: https://github.com/msitarzewski/agency-agents/blob/main/README.md#-quick-start

## Pros

- Roles can be installed by division or by agent name, with a dry-run option, so the installed set can stay small. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md))
- One roster converted into the native format of more than a dozen tools, with a per-tool integration README. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-multi-tool-integrations))
- NEXUS gives written phases, gates and handoff templates that can be followed without any tooling. ([source](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md))
- The Hermes plugin keeps the tool surface to four tools and loads role bodies on demand. ([source](https://github.com/msitarzewski/agency-agents/blob/main/integrations/hermes/README.md))
- MIT licensed; the separate desktop app is also MIT with no accounts or telemetry, according to its site. ([source](https://agencyagents.app))

## Cons

- No GitHub releases are published, so there are no version tags to pin. ([source](https://github.com/msitarzewski/agency-agents/releases))
- Orchestration is prompt-level: the Agents Orchestrator role asks the host to spawn other roles and keeps no runtime state of its own. ([source](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md))
- OpenCode registers only about 119 agents and silently drops the rest, per a note in the README. ([source](https://github.com/msitarzewski/agency-agents/blob/main/README.md))
- The MCP memory integration is a prompt pattern that depends on a memory server the user must supply. ([source](https://github.com/msitarzewski/agency-agents/blob/main/integrations/mcp-memory/README.md))
- The tracker has an open issue coordinating further installer and metadata hardening fixes. ([source](https://github.com/msitarzewski/agency-agents/issues/917))

## Alternatives

- [wshobson/agents](https://multiagentguide.top/tools/wshobson-agents.md)
- [Superpowers](https://multiagentguide.top/tools/superpowers.md)
- [ECC](https://multiagentguide.top/tools/ecc.md)
- [gstack](https://multiagentguide.top/tools/gstack.md)
- [BMad Method](https://multiagentguide.top/tools/bmad-method.md)

## FAQ

### Does agency-agents support MCP?

Only as a documented pattern. An integration guide shows agents using remember, recall, rollback and search tools from an MCP memory server that you configure in your host tool. The repo ships no MCP server or client, so the cell is partial.

### Does it run agents itself?

No. It supplies role files, converters and playbooks. The host tool runs the agents, and the Agents Orchestrator role and NEXUS docs are instructions the host follows.

### Which tools can install the roles?

The README lists Claude Code, Codex, OpenCode, OpenClaw and Hermes among others, including Copilot, Gemini CLI, Cursor, Aider, Windsurf, Kimi Code, Qwen Code and DeepSeek Harness.

### Is it free?

Yes. The repository is MIT licensed and no paid product is documented; the README links a sponsor page only.

### How many agents are there?

The README's stats section says 230+, while the Hermes integration notes count 279 generated agents. The number changes as roles are added, so check the repository.

## Sources

- [agency-agents README](https://github.com/msitarzewski/agency-agents/blob/main/README.md)
- [agency-agents README, multi-tool integrations](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-multi-tool-integrations)
- [Agents Orchestrator role file](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md)
- [NEXUS strategy playbook](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md)
- [Startup MVP multi-agent workflow example](https://github.com/msitarzewski/agency-agents/blob/main/examples/workflow-startup-mvp.md)
- [Hermes integration README](https://github.com/msitarzewski/agency-agents/blob/main/integrations/hermes/README.md)
- [MCP memory integration README](https://github.com/msitarzewski/agency-agents/blob/main/integrations/mcp-memory/README.md)
- [Agency Agents desktop app site](https://agencyagents.app)
- [agency-agents releases page (empty)](https://github.com/msitarzewski/agency-agents/releases)
- [Issue 917: installer and metadata hardening fixes](https://github.com/msitarzewski/agency-agents/issues/917)
- [Codex integration README](https://github.com/msitarzewski/agency-agents/blob/main/integrations/codex/README.md)
- [agency-agents README, quick start](https://github.com/msitarzewski/agency-agents/blob/main/README.md#-quick-start)
- [msitarzewski/agency-agents GitHub repository](https://github.com/msitarzewski/agency-agents)

## Unknown fields

protocols.a2a: no mention in the README; code search hits (an identity-and-trust role file and a checksum file) were not read as A2A support. protocols.agui: no mention found. Agent counts differ between the README (230+) and the Hermes integration doc (279).

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/agency-agents