agency-cli

Agency CLI

English | 中文

A modular AI coding agent framework that brings autonomous coding capabilities to your terminal. With support for multiple LLM providers, MCP plugins, fine-grained permission control, and team collaboration, Agency transforms how developers interact with AI assistants.

Overview

Agency is an intelligent command-line agent that leverages Large Language Models to autonomously execute development tasks. Unlike traditional chat-based AI assistants, Agency integrates deeply with your filesystem, git repository, and development tools, enabling it to understand context, manage tasks, and perform complex multi-step operations.

Key Differentiators

Installation

pip install agency-cli

Prerequisites

• Python 3.9 or higher
• An LLM API key (Anthropic, OpenAI, or compatible gateway)

Quick Start

1. Configure API Credentials

# Interactive configuration wizard
agency config init --workspace /path/to/your/project

# Or set values directly
agency config set \
  --provider anthropic \
  --model claude-3-5-sonnet-20241022 \
  --api-key your-api-key

2. Launch the Agent

# Start in current directory
agency

# Start in specific workspace
agency run --workspace /path/to/project

# Plan mode (read-only, no modifications)
agency run --workspace /path/to/project --permission-mode plan

3. Example Interactions

❯ Fix the authentication bug in src/auth.py

❯ Create a new REST API endpoint for user management

❯ Write unit tests for the payment module

❯ Refactor the database layer to use transactions

Core Features

Multi-LLM Support

Connect to various LLM providers through a unified interface:

# Anthropic (recommended)
agency config set --provider anthropic --model claude-3-5-sonnet-20241022

# OpenAI
agency config set --provider litellm --model gpt-4-turbo

# Local Ollama
agency config set --provider litellm --model ollama/llama3 --base-url http://localhost:11434

Permission Modes

Agency provides three permission modes to control agent behavior:

agency run --permission-mode auto

Built-in Tools (30+)

File Operations

• read_file - Read file contents with optional line limits
• write_file - Create or overwrite files
• edit_file - Intelligent file editing with text matching

Command Execution

• bash - Run shell commands with security validation
• background_run - Execute long-running commands in background
• background_list / background_get - Manage background tasks

Task Management

• task_create - Create tasks with descriptions and roles
• task_list / task_get / task_update - Full task lifecycle management
• todo_write - Session-level plan tracking

Scheduling

• schedule_create - Cron-based task scheduling
• schedule_list / schedule_delete - Manage scheduled tasks

Memory & Skills

• save_memory - Persist project knowledge across sessions
• load_skill - Load reusable skill modules

Team Collaboration

• teammate_spawn - Spawn additional AI agents
• teammate_list - View active teammates
• message_send / inbox_read - Inter-agent communication
• broadcast - Send messages to multiple teammates
• shutdown_request / shutdown_respond - Teammate lifecycle management

Plan Approval

• plan_approval_request - Request approval for implementation plans
• plan_approval_respond - Respond to approval requests

Git Worktree

• worktree_create - Create isolated Git worktrees
• worktree_list / worktree_bind / worktree_closeout - Worktree lifecycle

MCP Plugin Integration

Extend Agency's capabilities by connecting MCP (Model Context Protocol) servers. Configure plugins in .claude-plugin/plugin.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

Bash Security

Agency validates all shell commands before execution:

• Dangerous patterns: rm -rf, sudo, shell metacharacter injection
• Risk classification: read / write / high-risk
• Confirmation prompts: High-risk operations require explicit user approval

Architecture

agency/
├── cli.py                      # CLI entry point
├── runtime/
│   ├── agent_loop.py           # Core REPL loop with streaming support
│   └── bootstrap.py            # Agent factory
├── core/
│   ├── config.py               # Environment configuration
│   ├── compact.py              # Context compaction & output persistence
│   ├── managers.py             # TodoManager for plan tracking
│   ├── hooks/                  # PreToolUse, PostToolUse, SessionStart
│   ├── permissions/           # CapabilityPermissionGate, BashSecurityValidator
│   └── prompt/                 # System prompt construction
├── capabilities/
│   ├── background/            # Background task service
│   ├── memory/                # Persistent memory with dream() interface
│   ├── scheduler/             # Cron-based task scheduler
│   ├── skills/               # Skill loading system
│   ├── tasks/                # Task state machine
│   ├── team/                 # Multi-agent communication protocol
│   └── worktree/            # Git worktree management
├── connectors/
│   ├── fs/                   # Safe file system operations
│   ├── llm/                  # LLM provider adapters
│   ├── mcp/                  # MCP protocol client
│   └── shell/                # Shell command execution
├── tools/
│   ├── registry.py           # Tool definitions
│   └── dispatcher.py         # Tool call dispatcher
└── ui/
    ├── completer.py          # Tab completion
    ├── input.py             # Key bindings
    ├── pager.py             # Paginated output
    └── progress.py          # Progress indicators

Configuration

Environment Variables

Workspace Structure

When running, Agency creates the following directories:

CLI Commands

agency run [options]              Start interactive agent
  --permission-mode MODE           default | plan | auto (default: default)
  --model MODEL                    Override default model
  --workspace PATH                Working directory (default: current)

agency config set                  Write settings to .env
  --provider PROVIDER             litellm | anthropic
  --model MODEL                   Model identifier
  --api-key KEY                   API key
  --base-url URL                  Custom gateway URL

agency config show                 Display current configuration
agency config init                Interactive configuration wizard
agency config unset               Remove settings from .env

REPL Commands

Hooks System

Extend Agency's behavior with custom hooks:

{
  "PreToolUse": {
    "command": "python check_permission.py"
  },
  "PostToolUse": {
    "command": "python log_tool.py"
  },
  "SessionStart": {
    "command": "python on_start.py"
  }
}

Development

Local Setup

git clone <repository>
cd agency
pip install -e .

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type check
mypy src/

# Run tests
pytest tests/

Publish New Version

# Update version in pyproject.toml
git add .
git commit -m "Release v0.2.0"
git tag v0.2.0
git push origin v0.2.0

The GitHub Actions workflow will automatically build and publish to PyPI.

Dependencies

anthropic>=0.54.0       # Anthropic API SDK
python-dotenv>=1.0.1    # .env file support
litellm>=1.48.0        # Multi-LLM provider adapter
rich>=13.9.0           # Terminal output formatting
prompt_toolkit>=3.0.41 # REPL interface
blessed>=1.19.0        # Terminal capabilities

License

MIT License - see LICENSE for details.

Disclaimer

Agency executes file writes, edits, and shell commands. Use only in trusted environments and carefully confirm all high-risk operations.