🌐 English | 한국어 | 日本語 | 中文 | Español

ai-agency

Stop re-explaining your project to AI.

A vendor-neutral CLI that builds a persistent context layer for your project — so every AI session (Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, Aider) starts already knowing your codebase, conventions, and business rules.

_{Pick PM from the menu, pick which specialists to bring — panes spawn and coordinate through a shared task-board.md.}

---

Try it in 60 seconds

brew install itdar/tap/ai-agency

cd ~/your-project
ai-agency init      # scans, generates AGENTS.md + .ai-agents/ context
ai-agency           # pick an agent — it's already briefed

No Homebrew? curl -fsSL https://raw.githubusercontent.com/itdar/ai-agency/main/src/install.sh | bash -s -- --global

Works on macOS and Linux. Don't like it? ai-agency uninstall removes the tool, and ai-agency clear removes everything it generated — no residue.

---

Why

Every new AI session starts from zero. The model burns tokens figuring out:

• "What framework is this?" — reads 20 files
• "What are the team conventions?" — guesses wrong
• "Who approves deploys?" — skips the step

Research (ETH Zurich, reviewed 2026-03): agents re-analyzing a known project waste ~20% more tokens and produce worse results than agents primed with a curated context file. Review article ↗

ai-agency writes that context file once — vendor-neutral, under 300 tokens per agent — and your AI tool of choice loads it on every session.

---

What actually gets built

When you run ai-agency init, the tool classifies each directory, then generates a layered context:

your-project/
├── AGENTS.md                     # Who am I? — role, rules, permissions (≤300 tokens)
├── .ai-agents/
│   ├── context/                  # What do I know? — only non-inferable facts
│   │   ├── domain-overview.md    #   business purpose, policies, constraints
│   │   ├── api-spec.json         #   endpoints map (JSON DSL — ~3× cheaper than prose)
│   │   ├── data-model.md         #   entities + relationships
│   │   ├── business-metrics.md   #   KPIs, OKRs
│   │   ├── stakeholder-map.md    #   RACI, approval flows
│   │   └── planning-roadmap.md   #   milestones, decisions log
│   ├── skills/                   # How do I work? — loaded on demand
│   │   └── develop/SKILL.md
│   ├── roles/                    # Role-specific loading strategies
│   │   ├── pm.md
│   │   └── backend.md
│   └── coordination/             # Cross-vendor task board (multi-agent mode)
│       ├── task-board.md
│       ├── messages.md
│       └── agent-status.json
├── apps/
│   ├── api/AGENTS.md             # per-service agent
│   └── web/AGENTS.md
└── infra/AGENTS.md

Only what the AI can't derive from code gets stored. "This is a React app" is obvious from package.json. "We squash-merge and require QA approval before deploy" is not — that goes in.

---

It's not just code

Most AI tooling stops at the repo boundary. ai-agency treats your whole organization as the project:

my-product/              ← PM agent (coordinator)
├── api/                 ← Backend agent
├── web/                 ← Frontend agent
├── planning/            ← Technical Writer (specs, ADRs, roadmap)
├── business/            ← Business Analyst (GTM, KPIs, stakeholders)
└── infra/               ← Infra agent

The PM agent delegates to whichever specialist fits the task — code changes to backend, pricing questions to business, spec drafts to planning. Each specialist loads only its own context, so token usage stays predictable.

For multi-domain platforms, domains are auto-detected when a directory has 2+ sub-projects with their own build files:

platform/
├── commerce/           ← Domain Coordinator (auto-detected)
│   ├── order-api/
│   └── storefront/
├── social/             ← Domain Coordinator (auto-detected)
│   ├── feed-api/
│   └── chat-api/
└── infra/

---

Running agents

ai-agency                       # interactive menu
ai-agency --agent api           # jump straight to one agent
ai-agency --multi               # several agents in parallel tmux panes
ai-agency --detach              # background tmux session — survives SSH disconnects

Three session modes:

• Single — pick any agent (e.g. backend, frontend) and it runs in your current terminal. No tmux needed.
• Team — pick a coordinator (root PM or a domain coordinator), choose which specialists to bring along, and the PM spawns one tmux pane per teammate and delegates work. Uses Claude Code's native agent teams (Claude Code only for now).
• Multi — pick any set of agents; each gets its own tmux pane, coordinating through .ai-agents/coordination/ — a plain-text task board, message log, and status JSON. Because everything is Markdown + JSON, a Claude Code agent in one pane can hand work off to a Codex agent in another. No proprietary protocol; just files.

Add --detach to any tmux mode and the session keeps running after you close the terminal — reattach with tmux attach -t <name>.

---

Supported AI tools

ai-agency writes AGENTS.md (the open standard) plus per-vendor bootstrap files:

Tool	Reads context via	Bootstrap file
OpenAI Codex	AGENTS.md natively	—
Gemini CLI	AGENTS.md natively	—
Claude Code	bootstrap → AGENTS.md	CLAUDE.md (always generated)
Cursor	bootstrap → AGENTS.md	.cursor/rules/agents.mdc (always generated)
GitHub Copilot	bootstrap → AGENTS.md	.github/copilot-instructions.md (if .github/ exists)
Windsurf	bootstrap → AGENTS.md	.windsurfrules (if already present)
Aider	bootstrap → AGENTS.md	.aider.conf.yml (read directive appended)

If a bootstrap target already exists with your own content, it's backed up to <file>.pre-agents.bak first (and *.pre-agents.bak is added to .gitignore).

Switch tools anytime — the context layer doesn't change.

---

Keeping context fresh

Each AGENTS.md embeds maintenance triggers ("if the API contract changes, update api-spec.json"). The AI updates context in-session.

After each session, ai-agency compares a checksum of your code against the context files and warns if they drifted:

[ai-agency] Code changes detected but no context files updated.
  Run: ai-agency verify --staleness

Manual checks:

ai-agency verify                # structure + completeness
ai-agency verify --staleness    # drift between code and context

For major refactors, re-run ai-agency init — it offers an incremental mode that only regenerates context for new/changed directories.

---

CLI reference

# Setup
ai-agency init [path]            # scan → classify → generate → validate
ai-agency classify [path]        # preview classification without generating

# Daily use
ai-agency                        # interactive launcher (single / team / multi)
ai-agency --agent <keyword>      # launch a specific agent without the menu
ai-agency --multi                # multi-agent tmux session (pick agents, one pane each)
ai-agency --detach               # detached tmux session; reattach with tmux attach
ai-agency --tool <claude|codex|gemini>
ai-agency --lang [code]          # UI language: en ko ja zh es fr de ru hi ar
ai-agency --list                 # print detected agents and exit

# Project registry (launch from anywhere)
ai-agency register [path]
ai-agency scan [dir]
ai-agency list
ai-agency unregister [path]

# Maintenance
ai-agency verify [path]          # validate structure + token budgets
ai-agency verify --staleness     # detect drift between code and context
ai-agency clear [path]           # remove generated files (interactive, per-directory)
ai-agency update                 # update ai-agency itself (brew / global / local)
ai-agency uninstall              # remove ai-agency from your system
ai-agency --version              # print installed version

---

Requirements

• macOS or Linux — Bash 3.2+ (the stock macOS Bash works)
• curl — for install and self-update
• tmux — optional; only needed for --multi, team mode, and --detach
• At least one AI CLI — Claude Code, Codex CLI, or Gemini CLI

No runtime dependencies beyond that — it's plain Bash. Nothing to compile, no Node/Python required.

---

Updating & uninstalling

ai-agency update                 # updates whichever install you have (brew / global / local)
ai-agency uninstall              # removes the tool + project registry (asks first)
ai-agency uninstall --keep-config  # keep the project registry
ai-agency clear                  # remove generated AGENTS.md / .ai-agents/ from a project

uninstall never touches your projects — generated AGENTS.md and .ai-agents/ files stay until you remove them with ai-agency clear (or keep them; they're plain Markdown and useful on their own).

---

FAQ

Does my code get sent anywhere? ai-agency itself makes no network calls except downloading its own files on install/update — no telemetry, no analytics. Context generation runs through whichever AI CLI you choose, under that tool's account and policies.

How much does init cost? The initial generation scans the whole project and can run into tens of thousands of tokens. That cost is paid once; every subsequent session loads the prebuilt context (≤300 tokens per agent) instead of re-analyzing the codebase.

I already have a CLAUDE.md / Cursor rules. Will they be overwritten? Your original is backed up to <file>.pre-agents.bak before the bootstrap pointer is written, and the backup is git-ignored. Merge anything you want to keep into AGENTS.md — that's the single source of truth all tools share.

ai-agency: command not found after install? The curl installer puts the binary in ~/.local/bin. Add it to your PATH: export PATH="$HOME/.local/bin:$PATH" (the installer prints this when needed).

Do I need tmux? Only for multi-pane modes (--multi, team, --detach). Single-agent sessions run in your current terminal with no extra dependencies.

Can I undo everything? Yes — ai-agency clear interactively removes generated AGENTS.md / .ai-agents/ files per directory, and your pre-existing vendor files can be restored from their *.pre-agents.bak backups. ai-agency uninstall removes the tool itself.

---

Design principles

• Vendor-neutral. AGENTS.md is the shared standard; bootstrap files are thin pointers.
• Only non-inferable facts. If the AI can learn it by reading the code, it doesn't belong in context.
• Token budgets. Each AGENTS.md stays under ~300 tokens after template substitution. API/event specs use JSON DSL (~3× cheaper than prose).
• Separation of knowledge / behavior / role. Context (always loaded), skills (on demand), roles (per-agent loading strategy) — mixing them makes token usage unpredictable.
• File-based coordination. Multi-agent handoffs use plain Markdown + JSON in .ai-agents/coordination/, so any tool can participate.
• No lock-in, no phone-home. Plain Bash + plain text files. Delete the tool and your context still works.

---

How it works (internals)

1. classify-dirs.sh applies 19 file-pattern rules to hint at each directory's type. The AI makes the final call.
2. scaffold.sh creates .ai-agents/ at root and per sub-project.
3. setup.sh launches your AI tool with HOW_TO_AGENTS.md — a 7-step meta-instruction that drives the generation.
4. validate.sh enforces required sections, token limits, and reference integrity.
5. sync-ai-rules.sh emits vendor bootstrap files (backing up anything it would replace).
6. ai-agency.sh runs the interactive CUI, tracks session checksums, and injects the coordination protocol into multi-agent sessions.

---

Contributing

Bug reports, feature requests, and PRs are welcome — especially:

• New vendor bootstraps (one function in sync-ai-rules.sh)
• Classification rules for more stacks (classify-dirs.sh)
• Translations — README and UI strings for more languages

Keep shell changes shellcheck-clean and set -euo pipefail-safe. Open an issue first for anything structural.

If ai-agency saves you tokens, a ⭐ helps others find it.

---

References

• AGENTS.md — the vendor-neutral standard this builds on
• ETH Zurich context-file review (InfoQ, 2026-03) — "only document what cannot be inferred"
• Kurly OMS team workflow — inspiration for the context design

---

License

MIT

---

_{Set up once. Work forever.}