AgentCPP

AgentCPP is a modern C++ coding-agent harness. It is a CLI-first agent that can stream model output, execute coding tools under a permission model, persist sessions, and expose named C++ module APIs for future clients.

The implementation follows the design in docs/SDD.md and docs/specs/.

Status

The project has moved from design into an MVP implementation. Current implemented modules:

• AgentCPP.Types: provider-neutral messages, content blocks, tool specs, deterministic JSON.
• AgentCPP.AI: OpenAI Responses request mapping, OpenAI Codex backend request mapping, Codex CLI auth-file parsing, SSE parsing, injectable streaming HTTP transport, and concrete cpp-httplib transport.
• AgentCPP.Core: stateful agent loop, lifecycle events, tool execution loop, permission hook, max-turn guard.
• AgentCPP.Tools: built-in read, ls, find, grep, bash, write, and edit.
• AgentCPP.Resources: AGENTS.md/CLAUDE.md context loading and SKILL.md discovery.
• AgentCPP.Session: JSONL session header, message restore, and event persistence.
• AgentCPP.Config: CLI/environment config resolution.
• AgentCPP.Coding: product assembly, permission policy, system prompt construction, and skill expansion.
• AgentCPP.CLI: parser and one-shot runtime executable.

Still deferred:

• Interactive CLI loop.
• Resume command runtime.
• Interactive permission prompts.
• Long-term memory database.
• Context compaction.
• Plugin system.
• TUI.
• Anthropic/Gemini providers.
• First-party OAuth login and token refresh.

Requirements

Linux is the primary target.

Required toolchain:

• CMake 3.30 or newer
• Ninja
• Clang 19 or newer, or another compiler with working C++ named module support
• Catch2 v3
• OpenSSL development headers
• Python 3 for the fake OpenAI E2E fixture

CMake fetches:

• nlohmann/json
• cpp-httplib
• Catch2 v3 if the system package is unavailable

Build And Test

cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang++
cmake --build build --parallel 1
ctest --test-dir build --output-on-failure

The test suite is deterministic and does not require a real OpenAI key. A fake Responses API fixture is available at tests/fixtures/e2e/fake_openai_responses_server.py.

Single-job builds are recommended for now because current Clang named-module support can be unstable when several module interface units are rebuilt concurrently.

CLI Usage

Build output:

build/src/cli/agentcpp

One-shot prompt:

./build/src/cli/agentcpp \
  -p "Use the write tool to create /tmp/hello.cpp with a hello-world C++ program." \
  --permission-mode trusted \
  --model gpt-4.1-mini

JSON event mode:

./build/src/cli/agentcpp --json -p "Say hello"

OpenAI Codex/ChatGPT subscription auth reuse:

./build/src/cli/agentcpp \
  --provider openai-codex \
  --auth codex-cli \
  --model gpt-5.1 \
  --permission-mode trusted \
  -p "Use the write tool to create /tmp/hello.cpp with a hello-world C++ program."

This mode reads an existing Codex CLI file auth cache from ${CODEX_HOME:-$HOME/.codex}/auth.json. It does not refresh or write Codex credentials; if the token is expired, run codex login or codex first.

Supported permission modes:

• ask: deny tool calls for now; interactive prompting is deferred.
• auto-read: allow read-only tools and strict allowlisted shell commands.
• trusted: allow all registered tools.

Configuration

The CLI resolves configuration through AgentCPP.Config.

Environment variables:

• OPENAI_API_KEY
• AGENTCPP_PROVIDER (openai or openai-codex)
• AGENTCPP_AUTH or AGENTCPP_OPENAI_CODEX_AUTH (api-key or codex-cli)
• AGENTCPP_MODEL or OPENAI_MODEL
• AGENTCPP_OPENAI_BASE_URL or OPENAI_BASE_URL
• AGENTCPP_OPENAI_CODEX_BASE_URL
• AGENTCPP_CODEX_HOME or CODEX_HOME
• AGENTCPP_PERMISSION_MODE
• AGENTCPP_SESSION_DIR
• AGENTCPP_SKILL_PATHS
• AGENTCPP_CONFIG_DIR

The runtime also reads a repo-local .env file through the environment abstraction. .env and .env.* are ignored by git; do not commit secrets.

Deterministic CLI E2E Without OpenAI

Start the fake Responses server:

python3 tests/fixtures/e2e/fake_openai_responses_server.py 8765

Run the CLI against it:

OPENAI_API_KEY=test \
AGENTCPP_OPENAI_BASE_URL=http://127.0.0.1:8765/v1 \
./build/src/cli/agentcpp \
  -p "Write the simple C++ hello program." \
  --permission-mode trusted \
  --model fake-model

The fixture drives a real CLI run through HTTP transport, provider parsing, the core agent loop, and the write tool.

Project Layout

src/
  ai/
  cli/
  coding/
  config/
  core/
  resources/
  session/
  tools/
  types/
tests/
docs/

Development Principles

• Use TDD for new behavior.
• Keep module dependencies acyclic and aligned with the specs.
• Use dependency injection for network, process execution, environment, time, IDs, and filesystem-heavy behavior.
• Do not let provider-specific JSON escape AgentCPP.AI.
• Do not let tools prompt users directly.
• Do not let CLI execute tools or call providers directly except through AgentCPP.Coding.
• Never print, snapshot, or serialize API keys or sensitive headers.