Coder Agent

An open-source, enterprise-grade CLI agent coding tool
A Claude Code alternative with multi-provider support, Agent Teams, and a powerful hook system

Coder Agent is an open-source CLI coding agent that brings enterprise-grade Agent Team orchestration, multi-provider LLM support, and deep extensibility through its hook system. It runs in your terminal, reads and writes code, executes shell commands, and orchestrates multiple AI agents to solve complex engineering tasks — all with fine-grained permission control and comprehensive context management.

Quick Start

# Prerequisites: Node.js >= 18.0.0 (>= 22.0.0 recommended)

# Clone the repo
git clone https://github.com/AgenticMatrix/CoderAgent.git
cd CoderAgent

# One-click install (builds, links `coder` command globally, sets up config)
./install.sh

# Set your model  and API key (DeepSeek by default)
coder --model 

# Start coding
coder

Note: The installer defaults to DeepSeek as the LLM provider. To use Anthropic or OpenAI, set the corresponding API key and edit ~/.coder/settings.json.

Key Features

🧠 Intelligent Agent Loop

ReAct pattern powered by TypeScript AsyncGenerator. Supports real-time streaming, interrupt & resume, user confirmation pauses, and checkpoint recovery. Prevents infinite loops with max-turns, budget cap, token threshold, and duplicate-operation detection.

👥 Agent Teams

Coordinator/Worker pattern with async SubagentBus communication. Spawn sub-agents for exploration, building, code review, and planning. Workers communicate via shared context and task notifications. Supports TeamCreate/TeamDelete for on-demand team topology.

# Coordinator mode with 4 workers
coder --coordinator --workers 4 "Fix all TypeScript errors across the codebase"

# Worker mode (joins an existing team)
coder --worker --team my-team-id

🔌 Multi-Provider

Unified Provider interface supporting Anthropic (native extended thinking), OpenAI (GPT-4o, o4-mini), and DeepSeek (R1 reasoning). Auto Router automatically selects the optimal model based on task complexity. Hot-swap providers without changing agent logic.

🛠️ Built-in Tools

File system (Read, Write, Edit, Glob), search (Grep), shell (Bash), version control (Git), task management (TodoWrite), browser (WebFetch, WebSearch), agent orchestration (AgentSpawn, AgentMessage, AgentStop), system (Skill, Cron, Worktree), and LSP integration. MCP protocol support for community tool extensions.

🔐 3-Tier Permission Model

Plan (read-only, auto-approved) → Ask (prompt user for mutations) → Auto (trusted workspace, full authorization). SAFE / MUTATION / DESTRUCTIVE risk levels. PermissionRequest hooks allow third-party approval plugins. Configurable sandbox modes (Docker, local) for shell execution isolation.

🪝 Lifecycle Hooks

SessionStart, UserPromptSubmit, PreMessage, PostMessage, PreToolUse, PostToolUse, Stop, PreCompact — and 19 more event types (27 total). Blockable hooks (PreMessage, PreToolUse) can veto actions. Non-blockable hooks (PostMessage, Notification) fire-and-forget for observability. Shell and JS function handlers.

📦 Context Management

Snip compaction (drop oldest messages, keep last 30) and Summarize (LLM-based compression). Microcompact — zero-LLM cleanup on >60min idle sessions. BudgetStore — disk offload for large tool outputs (>50KB single, >200KB aggregate). Dynamic system prompt refresh per turn.

🧩 Session Fork & Rewind

Full session lifecycle: create, resume, fork from turn N to explore alternatives, rewind to a previous turn, continue the last session. Auto file-change checkpoints after every Write/Edit. Git stash checkpoints before destructive operations.

# Resume most recent session
coder --continue

# Resume specific session
coder --resume sess_abc123

# Fork a session from turn 5
coder --fork-session sess_abc123 --fork-turn 5

🎨 Terminal UI (TUI)

React Ink-based terminal renderer with command palette, model picker, multi-panel views, and full mouse support. Includes a rich set of slash commands accessible via / prefix.

TUI Keyboard Shortcuts

Slash Commands

Type / during an interactive session to access built-in commands:

Skill System

Coder Agent features a self-evolving skill system powered by SKILL.md files. Skills are discovered, loaded, and improved automatically through a three-phase lifecycle:

1. Create — The agent detects repeated task patterns across sessions and auto-proposes new skills. Users can also manually install skills from the community hub via /skills install.

2. Use — Skills are loaded at session start via Progressive Disclosure: only skill names and descriptions appear in the system prompt. When a task matches a skill's intent, the full SKILL.md body is injected into context on-demand, keeping token usage low.

3. Improve — After each skill execution, the agent evaluates the outcome. If improvements are detected (shorter execution, fewer turns, fewer errors), the skill is auto-updated. This creates a virtuous cycle where skills compound in quality over time.

Skills are stored in ~/.coder/skills/ and can be managed via:

/skills list        # List installed skills
/skills browse      # Browse community skills
/skills install     # Install a skill by name or URL
/skills inspect     # Inspect a skill's full definition
/skills search      # Search community skills by keyword

Configure skill auto-creation and auto-improvement in ~/.coder/settings.json:

skills:
  autoCreate: true           # Auto-propose new skills from repeated tasks
  autoImprove: true          # Auto-improve skills after execution
  minRepeatForSkill: 2       # Times a task must repeat before skill creation

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        TUI Layer (@coder/tui)                │
│            React Ink Terminal Renderer + Gateway            │
│                    query-bridge.ts ↔ GatewayEvent            │
└─────────────────────────────────────────────────────────────┘
                                ▲
                                │  AsyncGenerator<QueryMessage>
                                ▼
┌─────────────────────────────────────────────────────────────┐
│                     Agent Loop (core/query.ts)               │
│  while(true): LLM Stream → Tool Execute → Observe → Repeat  │
│  Exit: maxTurns | budget | abort | stopReason ≠ tool_use    │
└──┬──────────┬──────────┬──────────┬──────────┬──────────────┘
   │          │          │          │          │
   ▼          ▼          ▼          ▼          ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│Provider│ │Hooks │ │Tools │ │Context│ │Subagent  │
│Adapter│ │System│ │Reg.  │ │Mgmt  │ │Bus       │
└──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └────┬─────┘
   │        │        │        │           │
   ▼        ▼        ▼        ▼           ▼
 Anthropic  Shell  File/Sys  Compactor  Worker
 OpenAI   JS Func  Shell/Git BudgetStore  Agents
 DeepSeek         MCP/Ext.  Snip/Summ.

Packages

Comparison

Coder Agent stands out in enterprise scenarios with its Agent Teams, multi-provider flexibility, deep hook system, and fine-grained permission control. If you need a single-agent coding tool, Claude Code is excellent. If you need AI agent orchestration with extensibility, Coder Agent is the right choice.

Configuration

Coder Agent uses ~/.coder/settings.json for persistent config. Settings are auto-populated at runtime — no manual environment variable exports needed.

Priority order:

1. CLI flags (--model provider/model-name)
2. ~/.coder/settings.json → default_model + model_list[] + env.*

Quick setup:

# Interactive model selection (provider → model → auth token)
coder --model

# Direct model set
coder --model deepseek/deepseek-v4-pro

Environment variables are auto-populated from settings.json at runtime. No need to manually export CODER_AUTH_TOKEN, CODER_MODEL, or CODER_BASE_URL.

Model Switching

Switch models interactively:

coder --model          # Interactive selection from model_list

~/.coder/settings.json

{
  "theme": "dark",
  "default_model": "deepseek/deepseek-v4-pro",
  "model_list": [
    {
      "model": ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-chat", "deepseek-reasoner"],
      "base_url": "https://api.deepseek.com/anthropic",
      "auth_token_env": "YOUR_DEEPSEEK_API_KEY",
      "provider": "deepseek",
      "price": {
        "input": 0.14,
        "output": 0.28,
        "currency": "USD",
        "unit": "1M tokens"
      }
    },
    {
      "model": ["claude-sonnet-2025", "opus-4.8"],
      "base_url": "https://api.deepseek.com/anthropic",
      "auth_token_env": "YOUR_ANTHROPIC_API_KEY",
      "provider": "anthropic",
      "price": {
        "input": 3.0,
        "output": 15.0,
        "currency": "USD",
        "unit": "1M tokens"
      }
    },
    {
      "model": ["gpt-4-turbo", "gpt-4o", "gpt-3.5-turbo"],
      "base_url": "https://api.openai.com/v1",
      "auth_token_env": "YOUR_OPENAI_API_KEY",
      "provider": "openai",
      "price": {
        "input": 10.0,
        "output": 30.0,
        "currency": "USD",
        "unit": "1M tokens"
      }
    }
  ],
  "env": {
    "CODER_MODEL": "deepseek-v4-pro",
    "CODER_BASE_URL": "https://api.deepseek.com/anthropic",
    "CODER_AUTH_TOKEN": "YOUR_DEEPSEEK_API_KEY"
  }
}

Hook Configuration

Place hook definitions in ~/.coder/hooks/*.json:

{
  "event": "PreToolUse",
  "handler": {
    "type": "shell",
    "command": "/usr/local/bin/coder-guard",
    "timeout": 30000
  }
}

Supported events: SessionStart, UserPromptSubmit, PreMessage, PostMessage, PreToolUse, PostToolUse, PostToolBatch, Stop, StopFailure, PreCompact, PostCompact, PermissionRequest, PermissionDenied, Notification, SubagentStart, SubagentStop, and more.

Project Configuration (CODER.md)

Place a CODER.md file in your project root for project-specific instructions. Coder Agent automatically loads this as context at the start of every session:

# Project Overview

This is a Node.js microservice with PostgreSQL and Redis.

## Architecture
- `src/app/` — Application entry points
- `src/components/` — Shared components
- `src/lib/` — Utilities and business logic
- `db/` — Database schema and migrations

## Conventions
- Use TypeScript strict mode
- Tests use Vitest
- API routes follow RESTful conventions

Use /init in an interactive session to have Coder Agent auto-generate a CODER.md for your project.

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests (~500 tests across 41 test files)
pnpm test

# Type check
pnpm type-check

# Lint
pnpm lint

# CI pipeline (lint + type-check + tests + build)
pnpm ci

Package Descriptions

Requirements

• Node.js >= 18.0.0 (Node.js >= 22.0.0 recommended)
• pnpm >= 9.15.0
• TypeScript 5.7+
• macOS 12+ or Linux (for sandbox features)

Documentation

• Getting Started Guide — installation, basic usage, TUI shortcuts, session management
• Configuration Reference — full settings.json schema, env vars, permission modes, sandbox setup

License

MIT © Coder Agent Contributors

_{Built with TypeScript, React Ink, and ❤️ by the Coder Agent community}