the-agency-cli 1.13.7

The Virtual IT Team in Your Pocket. A multi-agent runtime with 50+ AI Personas for enterprise software development.

The Agency

Visit the website | Getting Started | Runtime Docs

Runtime + coordination protocol for multi-agent dev teams 🏢

Hire, fire, and attach to persistent AI agents running in terminal windows — each with their own git worktree, role, and communication channel. Works with any vendor CLI (Claude Code, Gemini, Aider, Codex) or local models via Ollama.

The repo also ships a library of specialized AI Personas (Skills) you can inject into your existing AI editor — but the main bet here is the runtime, not the personas.

⚖️ Why The Agency? (vs. CrewAI, AutoGen, LangGraph)

Unlike traditional agent orchestration frameworks that require you to write hundreds of lines of complex Python code to define state variables, execution graphs, and LLM API hooks, The Agency is purely contextual.

• Zero Code Orchestration: The Agency provides the missing Domain Knowledge, Organizational Chart, and Standard Operating Procedures (SOPs) as modular logic files. You don't need to write connection code.
• Bring Your Own Editor: Instead of running a headless python script, you inject The Agency's Personas directly into the powerful AI tools you already use every day (Cursor, Roo Code, Copilot Workspaces, Gemini CLI, Aider).
• Practical Software Engineering: Other frameworks give you a generic sandbox. The Agency gives you a heavily researched, production-proven IT department ranging from a project_manager and cmo_analyst to a chief_information_security_officer and sre_cloud_architect.

You don't need another orchestration engine. You just need a better team.

Simply inject these personas into your favorite AI tool, or spawn a full autonomous team with agency start.

---

🙋 Prior Art & Name Collision (read me before you star)

Full disclosure: while iterating on this I discovered two sibling projects I wish I'd found earlier. Both are worth a look before picking The Agency:

• the-agency-ai/the-agency — same name, same DNA. Multi-agent Claude Code orchestration with workstreams and principal-based requests. Very active. If you want "convention-over-configuration Claude Code multi-agent," start there.
• msitarzewski/agency-agents — 100+ specialized personas across 12 divisions, 79k+ stars. If you want a broad persona library to drop into Claude Code / Cursor / Aider / Gemini CLI, they've built it and it's excellent.

This repo is a different bet: a runtime + coordination protocol rather than a persona library.

• Per-agent git worktrees — branch isolation across concurrent agents.
• Screen/tmux-hosted persistent windows — hire / fire / attach live.
• Backend-agnostic coordination bus (github / gitlab / local on-disk mailbox).
• Blueprints as org-chart templates (IT today, marketing/startup/etc. pluggable).
• Multi-provider CLI support (claude / gemini / aider / codex).

If you want a ready-made team of personas, use one of the above. If you want the plumbing to run N of them in parallel with real git isolation, lifecycle, and a protocol they can talk over — this.

No hard feelings either way.

---

🏗️ Agency Runtime — Persistent Multi-Agent Teams (NEW)

The Agency now includes a runtime that spawns persistent AI agents in terminal windows, each with their own role, persona, and chain of command. One command bootstraps a full team that hires itself, coordinates via GitHub Issues, and delivers real work.

Quick Start

pipx install the-agency-cli
mkdir my-project && cd my-project && git init

# Bootstrap: init + collab-bus + hire a chief — one command
agency start

# Choose: Safe mode | Autonomous (yolo) | Sandboxed (Docker, coming soon)
# The chief spawns in a screen/tmux window. Attach and give them a task:

screen -r agency    # Ctrl-A " to pick the chief's window

> Build a CLI tool called quicknote with add, list, and search commands.
> Single Python file, local JSON storage. Full pipeline — go.

The chief hires a PO, the PO scopes stories, hires a dev and QA. Each agent works in its own terminal window, coordinates via GitHub Issues, and hands off to the next automatically.

What Happens Under the Hood

agency start
  |
  v
agency init          (installs skills + docs)
  |
  v
agency collab-bus    (installs GitHub Issues as the communication bus)
  |
  v
agency hire chief    (spawns the chief in a screen/tmux window)
  |
  v
Chief hires PO -> PO scopes stories -> PO hires dev + QA
  |
  v
Dev builds -> posts handoff on GitHub Issue -> QA auto-notified
  |
  v
QA verifies -> signs off -> PO closes initiative -> Chief reports to you

Every handoff is an actual GitHub Issue comment with signed authorship and a structured status packet. The notify-on-handoff system automatically pokes the next agent when a comment is posted — no human message-shuttling required.

Key Commands

Command	What it does
agency start	One-command project bootstrap (init + comms + chief)
agency hire <role>	Spawn a named agent in a screen/tmux window
agency fire <id>	Kill the agent, archive their work
agency status	Show the live org chart with all agents
agency hire dev --task "..."	Hire with an initial task (agent executes immediately)
agency hire dev --yolo	Skip permission prompts (for sandbox use)

Business Blueprints

Roles come from pluggable blueprints. The default IT blueprint ships with:

Role	Caliber	Does	Doesn't
chief	architect	Hires POs, sets RoE, arbitrates	Write code, accept hands-on work
po	senior	Scopes stories, hires team, approves	Write code, merge PRs
architect	senior	Designs plans, reviews PRs	Write production code
security	senior	Reviews for vulnerabilities, audits	Write production code
platform	senior	Installs infra (collab-bus, CI)	Write application code
dev	senior	Implements, opens PRs	Merge without QA sign-off
qa	senior	Tests, signs off on delivery	Write production code

Each agent gets a randomized first name from a role-appropriate pool (executives for chief, crypto names for dev, etc.) and introduces themselves naturally — no robotic status dumps.

Adding a marketing blueprint (CMO, content writer, SEO, designer) is a single Python file with zero runtime changes.

How It's Different from CrewAI / AutoGen / MetaGPT

	CrewAI / AutoGen	MetaGPT / ChatDev	The Agency
Agents	Python functions in a DAG	Simulated in one script	Real persistent terminal sessions
Coordination	In-process message passing	Python dicts in memory	Actual GitHub Issue comments
Pipeline	Hardcoded in Python	Hardcoded roles	Chief decides dynamically
Human access	Can't attach mid-run	Can't attach mid-run	Ctrl-A " to any agent, anytime
Scaling	Fixed agent set	Fixed agent set	Agents hire other agents
State	In memory, lost on exit	In memory, lost on exit	Files + git + GitHub Issues
Tools	Limited Python tool functions	Limited tool functions	Full Claude Code (Bash, Git, etc.)

The Agency is a staffing layer, not an orchestration framework. It gives agents an identity, permissions, and a communication channel — then lets them figure it out.

---

🛡️ Core Value: Prompt Poisoning Defense

As an open-source framework driven purely by contextual markdown, The Agency recognizes that "Prompt Injection" and "Data Poisoning" are the largest unmitigated threats to autonomous agent ecosystems.

We maintain a strict Chain of Trust for all external contributions. Because malicious actors could attempt to submit Pull Requests containing jailbreaks or data exfiltration commands hidden inside a Persona's System Prompt (SKILL.md), this repository treats prompt security as a first-class citizen. All incoming PRs are strictly audited, ensuring that an enterprise using The Agency is never compromised by a poisoned virtual employee.

---

👥 The Organization Chart

The Virtual IT Team comprises specialized "Skills", mapped precisely to a modern tech enterprise:

• Management: project_manager, historian, workspace_manager
• Architecture: solution_architect, cmo_analyst (Digital Twin Owner), sre_cloud_architect
• Development: backend_developer, frontend_developer, coder
• Design: ux_ui_designer
• Data Engineering: relational_dba, graph_database_architect, data_scientist
• Quality Assurance: chief_test_officer, qa_automation_engineer, test_engineer, e2e_journey_tester, test_data_manager, ui_qa_engineer
• Security: chief_information_security_officer, application_security_engineer, security_operations_analyst, cloud_security_engineer, devsecops_engineer, compliance_auditor, penetration_tester
• Deployment: ssdlc_manager
• Infrastructure: iac_engineer
• Process & Methodology: verification_protocol, root_cause_analysis
• Management & Marketing: head_of_marketing, product_marketing_manager, content_copywriter, technical_writer
• Support & AI Ops: customer_support_triage, prompt_engineer, makefile_orchestrator
• Reel Production: reel_creative_director, voiceover_script_writer, storyboard_artist, cinematography_director, remotion_video_producer
• Meta-Skills (The Creators): skill_creator (Organizational Architect), tool_smith (Internal Tooling), collab_bus (Multi-Agent Communication)

(Read each SKILL.md inside the skills/ folder to review the specific heuristics and constraints of that role).

---

🚀 How to Use "The Agency"

Because The Agency defines logic and processes rather than hard-coded python scripts, you can use it conceptually within any environment.

1. The Global Agency CLI (Recommended)

The most powerful way to use "The Agency" is to install it globally on your system path. This allows you to spawn any persona directly into whichever project directory you are currently working in.

# Install the CLI
pip install the-agency-cli

# Or use pipx for an isolated install (if you have pipx)
# pipx install the-agency-cli

# Navigate to any of your completely separate projects
cd /my/super/secret/startup/

# Launch the interactive CLI right there
agency

The CLI will guide you through:

• Initialize & Configure: Automatically scans for AI assistants — Cursor (.cursorrules), Gemini CLI (.gemini/GEMINI.md), Roo Code / Cline (.clinerules), Claude Code (CLAUDE.md), Aider (.aider.conf.yml), GitHub Copilot (.github/ directory or copilot-instructions.md), and Windsurf (.windsurfrules). It installs the Agency skills into your .agency/ folder and injects a full skill directory with workflow guidance into your AI tool's project memory file so it can immediately navigate and employ the Virtual IT Team.
• Browse Skills: View the organizational chart and understand what every department does.
• Run Skill: Choose a specific skill, paste a task, and the agent will immediately context-switch into your codebase to start working.

2. In Any AI Coding Tool (Cursor, Roo Code, Copilot, Claude, Gemini…)

After running agency init, your tool's config file already contains the full skill directory. Simply ask your assistant: "Act as the frontend_developer skill and complete this task." It will read .agency/skills/frontend_developer/SKILL.md and adopt the persona automatically.

3. Pure Makefiles & Terminal Piping

If you prefer raw execution, you can completely ignore .agency.py and run sequential generation using the Makefile pattern.

See the example Makefile in the root directory for a proof-of-concept pipeline.

# Example: Generate an application schema using a local 8B model
make build-schema 

4. Supercharging Skills with Tools

While skills have "Brains", they need "Hands" to affect the local machine. By installing common CLI tools globally on your terminal (e.g., semgrep, docker, playwright), you empower the agents to use those tools automatically via run_command capabilities.

Read the Recommended Tools Architecture to see which open-source CLIs pair best with which Virtual Employee. If a tool you need doesn't exist, spawn the tool_smith meta-skill to write a custom wrapper!

---

📦 Integrating into an Existing Project

If you are not starting from scratch, you can easily drop "The Agency" into a mature, existing repository.

1. Call agency init (or just agency) and select "Initialize" The init step does two things:

• Copies the entire skills library into .agency/skills/ in your project.
• Injects a full skill directory + workflow guide into your AI tool's config file (.cursorrules, CLAUDE.md, .github/copilot-instructions.md, GEMINI.md, etc.) so the assistant immediately knows how to navigate and use the Virtual IT Team without any extra prompting.

2. Initialize the "Digital Twin" (The Most Important Step) AI agents hallucinate when they don't know your existing architecture. Before asking the Agency to write new code for your existing app, you must map your current state. From the agency initialization menu, select "Map Digital Twin":

• The historian reads your files to summarize the project's purpose.
• The solution_architect maps the src/ hierarchy to build a system architecture.
• The cmo_analyst aggregates this into a master "Digital Twin" state document at docs/cmo_state.md.

3. Resume Normal Operations Once properly mapped and configured, your native AI editor (like Cursor or Gemini) naturally understands your new virtual employees and the structure of your application. Ask your IDE directly: "Tell the backend_developer to build a new auth route according to the architecture."

---

🏗️ The Project Lifecycle

If you elect to use the full agency, follow the routing lifecycle governed by the project_manager:

1. Discovery: cmo_analyst checks the system's "Digital Twin" constraints (docs/).
2. Design Blueprint: ux_ui_designer maps the wireframes; prompt_engineer maps the LLM context flow.
3. Architecture: solution_architect defines the data models and component structure.
4. Security Check: ciso reviews the architecture for vulnerabilities. (Must pass before coding).
5. Implementation: Specialized backend_developer and frontend_developer write the code.
6. Testing: chief_test_officer coordinates unit, integration, and E2E tests.
7. Deployment: sre_cloud_architect dictates topology, and ssdlc_manager routes it to production.
8. Launch: The Marketing division generates go-to-market copy while the technical_writer builds the public APIs.

---

📜 Legacy Assets

Older, hard-coded Python SDK variants of this agentic framework have been archived in the legacy/ folder for historical reference. The future of The Agency is agnostic, prompt-driven markdown injected into powerful local or cloud execution layers.

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Want to add a new role to the IT Team?

1. Copy an existing SKILL.md inside skills/.
2. Define their Core Responsibilities and Workflow Integration in the markdown.
3. Submit a Pull Request.

🐛 Issues and Support

If you encounter any bugs, have feature requests, or need help integrating The Agency into your workflow, please open an issue on GitHub.

📄 License

Distributed under the MIT License. See LICENSE for more information.