Skip to content

AgenticMatrix/CoderAgent

BranchesTags

Repository files navigation

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

License: MIT TypeScript Node.js >= 18.0.0 Tests

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

Key Action
Enter Send message
Ctrl+C Interrupt agent / exit
Ctrl+L Clear screen
Ctrl+R Toggle reasoning display
↑ / ↓ Navigate history
/ Open slash command palette

Slash Commands

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

Command Description
/help List all commands and hotkeys
/clear Start a new session
/resume Resume a prior session
/model Change or show the current model
/sessions Switch between live TUI sessions
/compress Compress the conversation transcript
/branch Fork/branch the current session
/usage Show session usage stats (tokens, cost)
/agents Open the spawn-tree dashboard
/skills Browse, inspect, and install skills
/tools Enable or disable tools
/rollback List, diff, or restore checkpoints
/status Show live session info
/quit Exit Coder Agent
/init Bootstrap a project context file

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

Package Description
@coder/cli Terminal entry point, TUI gateway, engine wiring, slash commands
@coder/core Agent Loop, QueryEngine, Hooks, Context, Checkpoint, Session, Cron
@coder/shared Types, utilities, protocol definitions, config loader
@coder/provider Anthropic, OpenAI, DeepSeek adapters + Auto Router
@coder/tools Tool system: registry, orchestrator, permission engine
@coder/skills SKILL.md discovery, Progressive Disclosure, self-evolution
@coder/mcp MCP Client & Server (JSON-RPC 2.0 over stdio)
@coder/tui React Ink terminal renderer with Yoga Layout, ANSI processing
teams/ Team topology definitions and role configurations

Comparison

Feature Coder Agent Claude Code Hermes-Agent
License MIT Proprietary MIT
Multi-Provider ✅ Anthropic + OpenAI + DeepSeek + Auto ❌ Anthropic only ✅ Multi-provider
Agent Teams ✅ Coordinator/Worker + SubagentBus ❌ Single agent ❌ Single agent
Hook System ✅ 27 events, Shell + JS ⚠️ Limited hooks ❌ No hooks
Permission Model ✅ 3-tier (Plan/Ask/Auto) + Risk ⚠️ Ask/Auto only ⚠️ Basic
Context Compaction ✅ Snip + Summarize + Microcompact ✅ Summarize + Archive ❌ Limited
BudgetStore Disk Offload ✅ Per-result + Aggregate ❌ No ❌ No
Session Fork/Rewind ✅ Fork from any turn ❌ No ❌ No
Thinking Support ✅ DeepSeek R1 + Claude Extended ✅ Claude Extended ❌ Limited
MCP Protocol ✅ Full Client + Server ✅ Client only ⚠️ Partial
Skill System ✅ Self-evolving Skills ✅ Skills ❌ No
Sandbox ✅ Docker + Local modes ⚠️ Basic ❌ No
Cron Scheduler ✅ Durable tasks ✅ Scheduled tasks ❌ No
Worktree ✅ Git worktree isolation ✅ Git worktree ❌ No
FTS5 Memory ✅ Semantic search ✅ Memory system ❌ No

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

Package Description
packages/shared Shared types, utilities, protocol definitions, config loader
packages/tui Terminal rendering framework (React Ink + Yoga Layout)
packages/tools Tool system: registry, orchestrator, permission engine
packages/provider LLM provider adapters (Anthropic, OpenAI, DeepSeek) + Auto Router
packages/skills Skill system: SKILL.md discovery, creation, improvement
packages/mcp MCP Client & Server (JSON-RPC 2.0 over stdio)
packages/core Core runtime: Agent Loop, QueryEngine, Hooks, Context, Session, Cron
packages/cli CLI entry point, TUI gateway, slash commands, engine factory
packages/teams Team topology definitions and coordinator/worker strategies

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

License

MIT © Coder Agent Contributors

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

About

A pure open-source coding agent developed solely by DeepSeek.

Topics

react agent skill deepseek agentic-workflow claude-code codeagent

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

6 stars

Watchers

2 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages