cagent

English | 简体中文

cagent is a minimal Linux-first code agent written in modern C++ for learning how tools like Claude Code and OpenCode are structured.

Learning path: English | 简体中文

Current Features

• CLI commands: chat, run, tools list, config init
• OpenAI-compatible Chat Completions client with native tool calling
• Configurable model backends with openai_compatible and local_openai_compatible
• Configurable built-in tool registration through enabled_tools and disabled_tools
• Todo-based planning for multi-step tasks, including chat-side todo display and reminder injection
• Workspace-safe tools for listing files, describing paths, reading targeted file ranges, searching text, and inspecting Git status or diffs
• Built-in editing tools for full writes, exact text replacement, and inclusive line-range replacement with diff previews
• Recoverable session checkpoints with --session and --resume-latest support for both chat and run
• Lightweight history compaction so resumed sessions do not rely only on full message stacking
• Streaming assistant output with step-by-step CLI progress updates during longer runs
• Near-budget step reminders so long runs are nudged to finish before exhausting max_steps
• Clearer approval prompts with action kind, diff previews, and explicit approval or denial feedback
• Approval gate for file writes and shell commands
• Session logs and resumable state stored under .cagent/sessions
• Lightweight runtime telemetry in session events, including per-step and per-tool durations
• Prompt guidance tuned to reduce verbosity on simple questions and small edit tasks
• Unit and integration tests

Dependencies

• C++20 compiler
• CMake 3.22+
• libcurl
• nlohmann/json headers
• CLI11 headers
• doctest headers

On Ubuntu:

sudo apt-get install -y build-essential cmake libcurl4-openssl-dev nlohmann-json3-dev libcli11-dev doctest-dev

Build

cmake -S . -B build
cmake --build build -j4
ctest --test-dir build --output-on-failure

Quick start

Generate a local config template:

./build/cagent config init --workspace .

Set your API key:

export OPENAI_API_KEY=...

You can also put a raw key into .cagent/config.json using the api_key field. api_key_env should normally be the name of an environment variable such as OPENAI_API_KEY.

DashScope / Qwen example:

{
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model_backend": "openai_compatible",
  "model_name": "qwen3.6-plus",
  "api_key_env": "DASHSCOPE_API_KEY"
}

Run a one-shot task:

./build/cagent run "Find the main entrypoint and summarize it"

Start an interactive session:

./build/cagent chat

List the tools currently enabled for this workspace:

./build/cagent tools list --workspace .

Resume the most recent recoverable session:

./build/cagent chat --resume-latest

Notes

• The default config lives at .cagent/config.json.
• The default workspace root is the current directory.
• model_backend can be openai_compatible or local_openai_compatible.
• local_openai_compatible defaults to http://127.0.0.1:11434/v1 so local OpenAI-style servers can be used without changing the runtime architecture.
• enabled_tools and disabled_tools let you keep the single-agent loop but tighten or narrow the tool surface.
• tools list shows the exact tool set registered for the current config.
• read_file can focus on line ranges, and describe_path helps the model scout files before reading them in full.
• git_status and git_diff provide read-only repository context without needing approval, and hide .cagent metadata noise by default.
• chat and run now show step progress, tool activity, and streamed assistant text when the model backend supports streaming.
• When a run gets close to the configured step budget, the loop injects a reminder to prefer a concise finish over extra tool churn.
• Simple read-only questions are now guided to skip todo and answer after one or two relevant tool calls.
• Small edit tasks are now guided to inspect named files directly, avoid unnecessary repository-wide scouting, and verify with Git after edits succeed.
• run_command is restricted to an allowlist and always requires approval unless --auto-approve is enabled.
• todo no-op updates now surface as plan unchanged in the CLI instead of looking like a fresh plan write.
• Streamed assistant setup text that is immediately followed by tool calls is now suppressed in the CLI, so runs show less “Now I’ll…” chatter.
• File edits only happen through built-in tools so the agent can preview diffs before writing.
• Each resumable session now lives under .cagent/sessions/<session-id>/ with both events.jsonl and state.json.
• events.jsonl now carries lightweight telemetry such as duration_ms, step_complete, and step_budget_warning.