code-agent

Features

Quick Start

Prerequisites

• Go 1.25+
• An API key for a model that supports function calling

Install

go install ./cmd/codeagent

配置（可选）：首次启动会自动生成 ~/.codeagent/settings.json 模板；要迁移旧的 config.yaml，运行 codeagent migrate。也可从 config.example.yaml 参考字段。

Configure

export DEEPSEEK_API_KEY="..."

Run

# TUI workspace (default)
codeagent

# REPL with a specific model
codeagent --model deepseek repl

# One-shot task
codeagent run "explain this project"

The TUI is the default surface: a brand header shows version, model and workspace; typing / opens a filtered command menu; Shift+Enter inserts a newline in the composer; and drag-to-copy works in both the transcript and the input field.

Sessions persist per-project to .codeagent/sessions.db. List them with codeagent sessions, resume with codeagent resume <id>, or switch inside the REPL with /resume.

Usage

Interactive REPL

codeagent repl
> explain how RunTurn works
> /models
  deepseek
* deepseek-pro
  glm
  qwen
> /use glm
switched to glm (glm-5.1)
> /resume
  [1] 20260616-101500-a1b2c3d4  model=glm-5.1  msgs=42
Select a number to resume:

Goal mode (headless, CI-compatible)

codeagent --auto goal "fix the failing test in internal/agent/loop_test.go"
# exit code 0 = achieved, others distinct by outcome (blocked, errored, budget)

Serve mode

在用户级 ~/.codeagent/settings.json 的 server 段配置一次固定的本地开发 Token （或设置 CODEAGENT_SERVER_ACCESS_TOKEN 环境变量，优先）：

{
  "server": {
    "authentication": "bearer",
    "access_token": "<openssl rand -base64 32 的输出>"
  }
}

codeagent serve 127.0.0.1:8797
# authenticated HTTP + Agent Wire WebSocket protocol for client integrations

生产环境可以设置 CODEAGENT_SERVER_ACCESS_TOKEN 覆盖 YAML Token。

See Runtime Server deployment and security before exposing a Local or Remote Server.

Subagent trace

codeagent tasks                  # list delegations
codeagent task-trace <id>        # replay what the subagent did

Cross-workspace collaboration

The plan_workflow tool executes deterministic workflow templates across independent agent sessions. A manifest describes each worker; the runtime validates it, fans it out, and converges the results.

// v1: parallel dispatch + fan-in
plan_workflow(template: "cross_workspace_collaboration_v1",
  agents: [
    {role: "frontend", session_id: "<sid>", workspace_path: "/repo/frontend",
     message: "Build the frontend shell.", correlation_id: "todo/frontend/1"}
  ])

// v2: implement → independent review with VERDICT
plan_workflow(template: "cross_workspace_collaboration_v2",
  agents: [
    {role: "backend", session_id: "<sid>", reviewer_session_id: "<rev>",
     message: "Implement the API.", acceptance: "tests pass, no regressions",
     correlation_id: "todo/backend/1"}
  ])

Workers are resolved create_session child sessions owned by this runtime (guaranteed online, with a lease claimed synchronously at creation). A supervisor can drive the whole lifecycle from one conversation — see the cross-workspace-orchestrator skill.

Architecture

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px'}}}%%
graph TD
    A[CLI / TUI<br/>cmd/codeagent] --> B[Agent Loop<br/>internal/agent]
    B --> C[Session<br/>internal/session]
    B --> D[Model Provider<br/>internal/model]
    B --> E[Tool Registry<br/>internal/tools]
    B --> F[Skills<br/>internal/skills]
    B --> G[Reflection<br/>internal/reflection]
    B --> H[Observation<br/>internal/observation]
    E --> I[Sandbox Policy<br/>internal/sandbox]
    E --> J[MCP Adapter<br/>internal/mcp]
    E --> K[Task / Subagent<br/>internal/tools/task]
    C --> L[(SQLite<br/>sessions.db)]
    B --> M[Cross-Session Control Plane<br/>internal/controlplane]
    E --> N[Session Tools<br/>list / read / send / wait]
    M --> N
    M --> O[Workflow Engine<br/>internal/runtime + flux]
    N --> O
    O --> P[plan_workflow templates<br/>v1 / v2 Generator-Critic]

    classDef client fill:#3B82F6,stroke:#2563EB,color:#fff,stroke-width:2px
    classDef loop fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
    classDef service fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
    classDef data fill:#8B5CF6,stroke:#7C3AED,color:#fff,stroke-width:2px
    classDef ext fill:#F59E0B,stroke:#D97706,color:#fff,stroke-width:2px

    class A client
    class B loop
    class C,D,E,F,G,H,I service
    class J,K,N,O,P ext
    class L data
    class M service

The loop (internal/agent) is business-agnostic. It assembles context, calls the model with tool schemas from the Registry, gates each call through the policy layer, feeds results back. Skills, observation, reflection, and subagents plug into nil-safe interfaces — the loop never changes.

Configuration

Configuration lives in settings.json — layered user (~/.codeagent/settings.json) over project (<cwd>/.codeagent/settings.json + <cwd>/.codeagent/settings.local.json) — and in Claude-compatible .mcp.json files for MCP servers. Models, credentials (references only — values stay in env/keychain), agent/provider/web knobs, and permissions/verify/hooks all live here. codeagent migrate converts legacy config.yaml files. First start auto-generates a template.

Models

Credentials

credentials maps namespace → name → {source, env}. Values are references only — the secret itself stays in the environment or the host keychain (settings.json is committable):

Model configs reference a credential via models.<name>.credential: {namespace, name}.

Server (deployment)

server lives in the user-level ~/.codeagent/settings.json (never the project file). Configure once, any project inherits it:

{
  "server": {
    "authentication": "bearer",
    "access_token": "<token>",
    "display_name": "My Mac",
    "public_healthz": true
  }
}

access_token may be omitted and access_token_env: "CODEAGENT_SERVER_ACCESS_TOKEN" used instead — the env var wins when set.

Minimal example

{
  "default_model": "deepseek",
  "credentials": {
    "llm": { "deepseek": { "source": "env", "env": "DEEPSEEK_API_KEY" } }
  },
  "models": {
    "deepseek": {
      "provider": "openai",
      "base_url": "https://api.deepseek.com",
      "model": "deepseek-v4-flash",
      "credential": { "namespace": "llm", "name": "deepseek" }
    }
  }
}

Agent

Supported models

OpenAI-compatible providers: DeepSeek, Qwen (DashScope), GLM. Local models via Ollama native protocol or OpenAI-compatible endpoint (vLLM, llama.cpp, LM Studio).

Project Structure

cmd/codeagent/         CLI entry point (repl, tui, serve, goal, stats, trace)
internal/
├── agent/             Loop driver (thin) — turn execution, plan mode, hooks
├── session/           Context assembly, token accounting, compaction, SQLite store
├── model/             Provider abstraction (OpenAI, Ollama, DeepSeek) + resilient retry
├── tools/             Tool registry + implementations (filesystem, git, shell, search, web, task)
│   ├── sessions/      Cross-session tools (list/read/send/wait, create/fork) + typed schemas
│   └── task/          Subagent delegation
├── sandbox/           Command policy classification (allow / confirm / block)
├── skills/            Skill registry + load_skill tool + plugin marketplace
├── mcp/               MCP client — stdio/HTTP/SSE transport, tool wrapping
├── observation/       Tool result classification (ok, compile/test/lint failure, salient lines)
├── reflection/        Post-turn self-check (unverified mutations, paper-over detection)
├── hooks/             Pre/post-tool shell hooks (deterministic, config-driven)
├── controlplane/      Cross-session control plane — leases, ownership, spawn, target resolution
├── conversation/      Agent-wire protocol, runtime server, WebSocket transport
├── server/            HTTP mux, wire encoding, control messages, job streaming
├── runtime/           Runner, workspace, registry builder, subagent spawning, flux workflow bridge
├── goal/              Goal-mode engine (admit → execute → verify → evidence)
├── credential/        Credential chain resolver (env, static, cached)
├── managedworktree/   Isolated git worktree provisioning for sandboxed child sessions
├── jobs/              Background job tracking
└── ui/                Console renderer, diff formatting, terminal helpers
pkg/agentapi/          Public API types
skills/                Built-in skills (code-review, verify-change, git-commit, cross-workspace-orchestrator, etc.)
mobile/                iOS embedding support
docs/                  Design docs and protocol specifications

Tech Stack

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feat/amazing).
3. Commit your changes following Conventional Commits.
4. Push and open a Pull Request.

Built-in skills provide guidance for contributing code: verify-change for safe edits, code-review for structured review, and git-commit for commit conventions.

License

MIT