agency-code

Agency-Code: AI Developer Agent

An intelligent AI development assistant powered by Claude with built-in safety architecture.

Forked from: VRSEN/Agency-Code Enhanced with production-ready safety guardrails, auto-termination, and webhook integration.

Key Features: Multi-agent system (Coder + Planner) • Timeout monitoring • Runaway detection • WebSearch/WebFetch intelligence • Webhook-ready hooks • 181+ tests

📖 For detailed documentation, architecture, and integration examples, see ASKME.md

---

⚡ Quick Install (Recommended)

Requirements: Python 3.13 (Python 3.14 is not yet supported)

Windows Installation

# Step 1: Install agency-swarm framework
python -m pip install git+https://github.com/VRSEN/agency-swarm.git@main

# Step 2: Install agency-code
python -m pip install agency-code

# Step 3: Create .env file with your API key
"ANTHROPIC_API_KEY=sk-ant-your_key_here" | Out-File -FilePath .env -Encoding ASCII

# Step 4: Run aria
aria

Mac/Linux Installation

# Step 1: Install agency-swarm framework
pip install git+https://github.com/VRSEN/agency-swarm.git@main

# Step 2: Install agency-code
pip install agency-code

# Step 3: Create .env file with your API key
echo "ANTHROPIC_API_KEY=sk-ant-your_key_here" > .env

# Step 4: Run aria
aria

Get your API key: https://console.anthropic.com/settings/keys

---

🔧 Troubleshooting

Error: "aria is not recognized" (Windows)

Problem: Python Scripts folder is not in PATH.

Solution 1 - Add to PATH (Recommended):

# Run in PowerShell (restart terminal after)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python313\Scripts", "User")

Solution 2 - Run with python:

python -m agency

Error: "command not found: aria" (Mac/Linux)

Problem: pip install directory not in PATH.

Solution 1 - Add to PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Then reload shell
source ~/.bashrc  # or source ~/.zshrc

Solution 2 - Run with python:

python -m agency

Error: "Fatal error in launcher" or broken pip

Problem: pip is pointing to wrong Python installation.

Solution: Use python -m pip instead:

# Windows
python -m pip install agency-code

# Mac/Linux
python3 -m pip install agency-code

Error: "ValueError: '3.14' is not a valid PythonVersion"

Problem: Python 3.14 is too new - agency-swarm only supports Python 3.13.

Solution: Install Python 3.13 from https://www.python.org/downloads/

Then use:

# Windows - use Python 3.13 specifically
py -3.13 -m pip install git+https://github.com/VRSEN/agency-swarm.git@main
py -3.13 -m pip install agency-code
py -3.13 -m agency

# Mac/Linux - ensure python3.13 is installed
python3.13 -m pip install git+https://github.com/VRSEN/agency-swarm.git@main
python3.13 -m pip install agency-code
python3.13 -m agency

Error: "Missing Anthropic API Key"

Problem: No .env file or API key not set.

Solution: Create .env file in the directory where you run aria:

Windows:

"ANTHROPIC_API_KEY=sk-ant-your_actual_key" | Out-File -FilePath .env -Encoding ASCII

Mac/Linux:

echo "ANTHROPIC_API_KEY=sk-ant-your_actual_key" > .env

Alternative - Set as environment variable:

# Windows (temporary - current session only)
$env:ANTHROPIC_API_KEY="sk-ant-your_key"

# Mac/Linux (temporary - current session only)
export ANTHROPIC_API_KEY="sk-ant-your_key"

---

🚀 Manual Installation (Development)

Prerequisites

• Python 3.13+
• Git
• Anthropic API Key (Get one here)

Installation

Mac/Linux

# 1. Clone the repository
git clone https://github.com/joeyjoe808/Agent-C.git
cd Agent-C

# 2. Create and activate virtual environment
python3.13 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Fix Anthropic compatibility (important!)
pip install git+https://github.com/openai/openai-agents-python.git@main

Windows (PowerShell)

# 1. Clone the repository
git clone https://github.com/joeyjoe808/Agent-C.git
cd Agent-C

# 2. Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate.ps1

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Fix Anthropic compatibility (important!)
pip install git+https://github.com/openai/openai-agents-python.git@main

Windows (Command Prompt)

REM 1. Clone the repository
git clone https://github.com/joeyjoe808/Agent-C.git
cd Agent-C

REM 2. Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate.bat

REM 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

REM 4. Fix Anthropic compatibility (important!)
pip install git+https://github.com/openai/openai-agents-python.git@main

---

🔑 Configuration

Create .env File

The agent looks for a .env file in the root directory. Create it with your API key:

Option 1: Create from scratch

# Create .env file
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env

# On Windows (PowerShell):
# "ANTHROPIC_API_KEY=your_api_key_here" | Out-File -FilePath .env -Encoding ASCII

Option 2: Use example template (if provided)

cp .env.example .env
nano .env  # or notepad .env on Windows

.env File Contents

# Required: Your Anthropic API key
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional: Enable/disable safety session tracking (default: true)
USE_SAFE_SESSION=true

# Optional: Model selection (default: claude-haiku-4-5)
MODEL=anthropic/claude-haiku-4-5-20251001

Get your API key: https://console.anthropic.com/settings/keys

---

▶️ Run Agency-Code

If installed via pipx/pip (Quick Install):

# Run from anywhere
aria

If installed manually (Development):

# Activate virtual environment (if not already activated)
source .venv/bin/activate  # Mac/Linux
# .venv\Scripts\activate     # Windows

# Run the agent
python agency.py
# Or use: aria

# On Mac, use sudo if you get permission errors:
sudo python agency.py

You'll see:

[SafeSession] [OK] Session tracking enabled
[SafeSession] Session ID: abc123...

User: [Type your request here]

Example Requests

User: Create a FastAPI hello world app
User: Fix the bug in database.py line 42
User: Research best practices for JWT authentication
User: Help me refactor this function to be more readable

---

🛡️ Safety Features

Built-in Protection:

• ✅ Timeout Monitoring: 30min session / 5min turn / 2min tool timeouts
• ✅ Runaway Detection: Catches infinite loops (5+ same tool calls)
• ✅ Auto-Termination: Optional auto-kill on timeout/runaway (disabled by default)
• ✅ Graceful Cancellation: Press Ctrl+C to save state and exit cleanly

Webhook Integration:

• ✅ Hook System: Triggers on every tool execution and agent handoff
• ✅ Perfect for APIs: Use as backend for your web application
• ✅ Real-time Tracking: Session metrics (tool calls, duration, reasoning steps)

See ASKME.md for webhook integration examples and detailed safety documentation.

---

🧪 Testing

# Run all tests
pytest tests/ -v

# Run safety architecture tests (44 tests)
pytest tests/test_session_metrics.py \
       tests/test_safe_session.py \
       tests/test_timeout_monitor.py \
       tests/test_runaway_detector.py \
       tests/test_background_monitor.py \
       tests/test_cancellation.py -v

---

📂 Project Structure

Agency-Code/
├── agency.py                 # Main entry point
├── .env                      # API keys (you create this)
├── requirements.txt          # Dependencies
│
├── agency_code_agent/        # Coder agent
├── planner_agent/            # Planner agent
├── safety/                   # Safety architecture
├── tools/                    # 14+ tool implementations
├── shared/                   # Utilities & hooks
└── tests/                    # 181+ automated tests

---

🔗 Links

• Repository: https://github.com/joeyjoe808/Agent-C
• Issues: https://github.com/joeyjoe808/Agent-C/issues
• Original Fork: https://github.com/VRSEN/Agency-Code
• Agency Swarm: https://agency-swarm.ai/

---

📖 Documentation

For detailed information, see ASKME.md:

• Complete feature documentation
• Webhook integration examples
• Safety architecture details
• API integration patterns
• Demo tasks and examples
• Architecture diagrams

For developers, see AGENTS.md:

• Repository structure and guidelines
• Coding style and conventions
• Testing guidelines
• Commit and PR guidelines

---

🤝 Contributing

Fully open-source - build, refine, and improve as needed!

1. Fork the repository
2. Create a feature branch
3. Write tests first (TDD)
4. Run test suite
5. Submit pull request

---

📝 License

MIT License - see LICENSE for details.

---

Questions? Open an issue or check ASKME.md for detailed docs!