Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/itdar/ai-agency

One command to give any AI agent instant project understanding. Auto-generates AGENTS.md + context for Claude Code, Codex, Cursor, Copilot, and more.
https://github.com/itdar/ai-agency

agents-md ai-agents ai-coding ai-context aider automation claude-code cli codex copilot cursor developer-tools multi-agent project-setup windsurf

Last synced: 14 days ago
JSON representation

One command to give any AI agent instant project understanding. Auto-generates AGENTS.md + context for Claude Code, Codex, Cursor, Copilot, and more.

Awesome Lists containing this project

README 

          
🌐 [English](README.md) | [ν•œκ΅­μ–΄](docs/README_ko.md) | [δΈ­ζ–‡](docs/README_zh.md) | [ζ—₯本θͺž](docs/README_ja.md) | [EspaΓ±ol](docs/README_es.md) | [PortuguΓͺs](docs/README_pt.md)






# ai-agency



**Your own AI agency, built around your goals.**



Build your context once β€” never explain it again.

Dev, planning, business, design β€” specialist agents share the same knowledge and collaborate.

No more wasted tokens. Just orchestrated teamwork toward your objectives.



[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red?logo=github)](https://github.com/sponsors/itdar)






---



## What is ai-agency?



Every AI session starts from scratch. Your agent doesn't know your APIs, your team rules, or your business goals. You explain the same things over and over β€” burning time and money.



**ai-agency** builds persistent context for your organization and orchestrates AI specialists on top of it:



1. **Context once, forever** β€” Build your project's knowledge layer once. Every agent starts fully briefed β€” codebase, conventions, business rules, team structure. No repeated token costs, no wasted warm-up time.



2. **Orchestrated specialists** β€” Not just one agent on one repo. Dev, planning, business, design, QA, operations β€” each specialist shares the same context and collaborates. A PM agent coordinates them to tackle tasks, solve problems, and deliver results across your organization.



Whether it's a single service or an entire company's workflow β€” ai-agency orchestrates the right experts with the right context.



Works with any AI tool: Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, Aider.



---



## Install



### Homebrew (recommended)



```bash

brew install itdar/tap/ai-agency

```



### Without Homebrew



```bash

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

```



### Per-project only



```bash

cd /path/to/your-project

curl -fsSL https://raw.githubusercontent.com/itdar/ai-agency/main/src/install.sh | bash

```



---



## Getting Started



### 1. Initialize your project



```bash

cd ~/my-project

ai-agency init

```



Or from anywhere: `ai-agency init ~/my-project`



This does three things automatically:

1. **Scans** your directory structure and classifies each directory (backend, frontend, infra, business, etc.)

2. **Generates** `AGENTS.md` files and `.ai-agents/` context for each area

3. **Validates** the generated files for completeness



You pick your AI tool (Claude Code, Codex, or Gemini) and language. The AI then analyzes your project and builds the context. This is a one-time setup β€” it takes a few minutes but saves hours later.



### 2. Launch an agent session



```bash

ai-agency

```



That's it. Pick an agent from the interactive menu and start working. The agent already knows your project.



### 3. Daily use



Your daily workflow doesn't change. Just run `ai-agency` instead of launching your AI tool directly.



```bash

ai-agency                     # Pick agent interactively

ai-agency --agent api         # Jump straight to the API agent

```



When you select a top-level agent (PM, Domain Coordinator), it automatically spawns and coordinates sub-agents as needed β€” you don't have to manage them yourself.



For running multiple independent agents side-by-side in tmux split panes:



```bash

ai-agency --multi             # Select which agents to run in parallel

```



---



## Why You Need This



### Without ai-agency



Every session starts from zero. The AI spends time (and your tokens) figuring out your project:



- "What framework is this?" β€” reads 20 files to figure out

- "What are the API endpoints?" β€” scans every controller

- "What are the team conventions?" β€” has no idea, guesses wrong

- "Who approves deploys?" β€” doesn't know, skips the step



> Research (ETH Zurich, 2026): AI agents that re-analyze a known project waste **20% more tokens** and produce **worse results** than agents with pre-built context.



### With ai-agency



The AI loads everything in seconds and starts working immediately:



```

Session Start

  β†’ Reads AGENTS.md            "I'm the backend expert for order-api"

  β†’ Loads .ai-agents/context/  "I know the APIs, data models, team rules"

  β†’ Starts working             No exploration phase needed

```



---



## What Gets Generated



When you run `ai-agency init`, three layers of context are created:



```

your-project/

β”œβ”€β”€ AGENTS.md                    # Who am I? (role, rules, permissions)

β”œβ”€β”€ .ai-agents/

β”‚   β”œβ”€β”€ context/                 # What do I know? (domain knowledge)

β”‚   β”‚   β”œβ”€β”€ domain-overview.md   #   Business purpose, policies, constraints

β”‚   β”‚   β”œβ”€β”€ api-spec.json        #   API endpoints map

β”‚   β”‚   β”œβ”€β”€ data-model.md        #   Entities and relationships

β”‚   β”‚   └── ...                  #   (generated based on your project type)

β”‚   β”œβ”€β”€ skills/                  # How do I work? (workflow standards)

β”‚   β”‚   β”œβ”€β”€ develop/SKILL.md     #   Dev: analyze β†’ implement β†’ test β†’ PR

β”‚   β”‚   └── review/SKILL.md      #   Review: security, performance checklist

β”‚   └── roles/                   # Role-specific loading strategies

β”‚       β”œβ”€β”€ pm.md

β”‚       └── backend.md

β”œβ”€β”€ apps/

β”‚   β”œβ”€β”€ api/AGENTS.md            # Per-service agent

β”‚   └── web/AGENTS.md

└── infra/AGENTS.md

```



**Only non-obvious information is stored.** Things the AI can figure out by reading code (like "this is a React app") are excluded. Things it can't infer (like "we use squash merge" or "QA approval is required before deploy") are included.



---



## Project Structure Examples



ai-agency adapts to your project's shape. The directory where you run `ai-agency init` becomes the PM (coordinator).



### Simple product



```

my-app/               ← PM agent

β”œβ”€β”€ api/              ← Backend agent

β”œβ”€β”€ web/              ← Frontend agent

└── infra/            ← Infra agent

```



### Product + business teams



```

my-product/            ← PM agent

β”œβ”€β”€ api/              ← Backend agent

β”œβ”€β”€ web/              ← Frontend agent

β”œβ”€β”€ business/         ← Business Analyst agent

β”œβ”€β”€ planning/         ← Planner agent

└── infra/            ← Infra agent

```



Not just code β€” business, planning, QA, operations, and more. Each area gets its own specialized agent.



### Multi-domain platform



```

platform/              ← PM agent

β”œβ”€β”€ commerce/         ← Domain Coordinator (auto-detected)

β”‚   β”œβ”€β”€ order-api/    ← Backend agent

β”‚   └── storefront/   ← Frontend agent

β”œβ”€β”€ social/           ← Domain Coordinator (auto-detected)

β”‚   β”œβ”€β”€ feed-api/     ← Backend agent

β”‚   └── chat-api/     ← Backend agent

└── infra/            ← Infra agent

```



Domains are detected automatically when a directory contains 2+ subdirectories with their own build files.



---



## Team Mode



Run a PM agent that coordinates sub-agents, or launch multiple agents in parallel.



### Coordinated team (Claude Code)



The PM agent delegates tasks to specialists via Claude Code's native agent teams:



```bash

ai-agency                     # Select "team" mode from the menu

```



### Parallel agents (any AI tool)



Launch multiple agents in tmux split panes. Each agent works independently with file-based coordination:



```bash

ai-agency --multi             # Select agents, they run in split panes

```



Agents coordinate through `.ai-agents/coordination/` β€” a shared task board and message log that works across any AI tool.



---



## Keeping Context Fresh



Context files are updated automatically during AI sessions β€” each AGENTS.md includes maintenance triggers that tell the agent when to update what.



After a session, ai-agency checks if code changed but context wasn't updated, and warns you:



```

[ai-agency] Code changes detected but no context files updated.

  Run: ai-agency verify --staleness

```



You can also check manually:



```bash

ai-agency verify              # Validate structure and completeness

ai-agency verify --staleness  # Check if context is up-to-date with code

```



For major changes, re-run init in incremental mode β€” it only generates context for new directories:



```bash

ai-agency init                # Select "incremental" when prompted

```



---



## Supported AI Tools



ai-agency is vendor-neutral. AGENTS.md works with any tool, and bootstrap files are auto-generated for tools that need them.



| Tool | Works out of the box | Auto-bootstrap |

|---|---|---|

| **OpenAI Codex** | Yes | Not needed |

| **Claude Code** | Yes | `CLAUDE.md` generated |

| **Cursor** | Via rules | `.cursor/rules/` generated |

| **GitHub Copilot** | Via instructions | `.github/copilot-instructions.md` generated |

| **Windsurf** | Via rules | `.windsurfrules` generated |

| **Aider** | Via config | `.aider.conf.yml` updated |

| **Gemini CLI** | Yes | Not needed |



Bootstrap files are only generated for tools you actually use. Nothing is created for tools you don't have.



---



## CLI Reference



```bash

# Setup

ai-agency init [path]           # Initialize a project (scan, generate, validate)

ai-agency classify [path]       # Preview directory classification without generating



# Daily use

ai-agency                       # Interactive agent launcher

ai-agency --agent      # Launch specific agent

ai-agency --multi               # Parallel agents in tmux split panes

ai-agency --tool  # Specify AI tool

ai-agency --lang          # Set UI language (en ko ja zh es fr de ru hi ar)



# Project management

ai-agency register [path]       # Register a project

ai-agency scan [dir]            # Auto-discover projects with AGENTS.md

ai-agency list                  # List registered projects

ai-agency unregister [path]     # Remove from registry



# Maintenance

ai-agency verify [path]         # Validate generated files

ai-agency verify --staleness    # Check context freshness

ai-agency clear [path]          # Remove all generated files

```



---



## How It Works (Under the Hood)



For those curious about the internals:



1. **classify-dirs.sh** scans your project and applies 19 priority rules to classify each directory (k8s-workload, frontend, backend-go, business, etc.)

2. **scaffold.sh** creates the `.ai-agents/` directory structure with placeholder files

3. **setup.sh** launches your chosen AI tool with `HOW_TO_AGENTS.md` β€” a meta-instruction that guides the AI through a 7-step analysis and generation process

4. **validate.sh** checks the generated files for structural integrity (required sections, token limits, reference completeness)

5. **sync-ai-rules.sh** creates vendor-specific bootstrap files pointing to AGENTS.md

6. **ai-agency.sh** manages the interactive agent selection CUI and session lifecycle, including context checksum tracking and multi-agent coordination



> **Token notice:** Initial setup analyzes the full project and may consume tens of thousands of tokens. This is a one-time cost β€” subsequent sessions load pre-built context instantly.



---



## References



- [AGENTS.md Standard](https://agents.md/) β€” The vendor-neutral agent instruction standard this project builds on

- [ETH Zurich Research](https://www.infoq.com/news/2026/03/agents-context-file-value-review/) β€” "Only document what cannot be inferred"

- [Kurly OMS Team AI Workflow](https://helloworld.kurly.com/blog/oms-claude-ai-workflow/) β€” Inspiration for the context design



---



## License



MIT



---





  Stop re-explaining your project to AI. Set up once, work forever.