Metadata-Version: 2.4
Name: agency-cli
Version: 0.1.1
Summary: A modular AI coding agent framework with multi-LLM support, MCP plugins, and team collaboration
Author-email: Agency <805399080@qq.com>
License: MIT
Keywords: ai,agent,coding,llm,mcp,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.54.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: litellm>=1.48.0
Requires-Dist: rich>=13.9.0
Requires-Dist: prompt_toolkit>=3.0.41
Requires-Dist: blessed>=1.19.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Agency CLI

<p align="center">
  <img src="https://img.shields.io/badge/version-0.1.1-blue.svg" alt="version">
  <img src="https://img.shields.io/badge/python-3.9+-green.svg" alt="python">
  <img src="https://img.shields.io/badge/license-MIT-orange.svg" alt="license">
</p>

> 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

| Feature                  | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| **Autonomous Execution** | Execute multiple tool calls in sequence without repeated user input      |
| **Multi-Provider LLM**   | Seamlessly switch between Anthropic, OpenAI, Ollama, and custom gateways |
| **MCP Integration**      | Extend capabilities via the Model Context Protocol plugin ecosystem      |
| **Team Collaboration**   | Spawn multiple AI teammates that communicate and coordinate              |
| **Git Worktree**         | Parallel task execution in isolated Git branches                         |
| **Risk-Aware**           | Intelligent permission system with Bash command validation               |

## Installation

```bash
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

```bash
# 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

```bash
# 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:

```bash
# 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:

| Mode      | Behavior                                                                     |
| --------- | ---------------------------------------------------------------------------- |
| `default` | Write operations require confirmation; high-risk operations always prompt    |
| `plan`    | Read-only mode; no file modifications or command execution                   |
| `auto`    | Auto-execute non-high-risk operations; high-risk still requires confirmation |

```bash
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`:

```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

| Variable              | Description                             | Default   |
| --------------------- | --------------------------------------- | --------- |
| `AGENCY_LLM_PROVIDER` | LLM provider (`litellm` or `anthropic`) | `litellm` |
| `AGENCY_LLM_MODEL`    | Model identifier                        | Required  |
| `AGENCY_LLM_API_KEY`  | API key                                 | Required  |
| `AGENCY_LLM_BASE_URL` | Custom gateway URL                      | Optional  |

### Workspace Structure

When running, Agency creates the following directories:

| Directory                      | Purpose                       |
| ------------------------------ | ----------------------------- |
| `.env`                         | LLM API configuration         |
| `.memory/`                     | Persistent memory storage     |
| `.tasks/`                      | Task state and event logs     |
| `.runtime-tasks/`              | Background task status        |
| `.claude/scheduled_tasks.json` | Scheduled task configuration  |
| `.team/`                       | Team member data and messages |
| `.worktrees/`                  | Git worktree environments     |
| `.hooks.json`                  | Custom hook configurations    |
| `.transcripts/`                | Conversation logs             |

## 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

| Command            | Description                |
| ------------------ | -------------------------- |
| `/tools`           | List all available tools   |
| `/mcp`             | Show MCP server status     |
| `/plan`            | Display current plan/tasks |
| `/exit` or `/quit` | End session                |

## Hooks System

Extend Agency's behavior with custom hooks:

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

## Development

### Local Setup

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

### Code Quality

```bash
# Format code
black src/

# Lint
ruff check src/

# Type check
mypy src/

# Run tests
pytest tests/
```

### Publish New Version

```bash
# 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](LICENSE) for details.

## Disclaimer

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

