codeur

CLI agent for OpenAI-compatible APIs (Ollama, vLLM, DeepSeek, OpenAI).

Single-binary C tool with an interactive REPL, streaming markdown, tree-sitter syntax highlighting, tool use, sub-agents, MCP, and persistent memory.

AI-powered coding assistant and autonomous agent with advanced features including security testing tools (API fuzzing, endpoint scanning, auth scanning, schema validation), CVE scanning for dependencies, multi-agent coordination, and web UI.

Quick start

./configure
make -C src
cp config.ini.sample ~/.config/codeur/config.ini
# Edit url, api_key, model in config.ini
./src/codeur

Requirements

Optional: universal-ctags for faster codebase indexing.

Features

• Agent tools — read/write/edit files, shell, git, grep, find, web search, URL fetch, HTTP requests, background tasks, codebase search
• Codebase awareness — symbol indexing (ctags + regex fallback for 10 languages), hierarchical project context
• Streaming — live markdown rendering, tree-sitter syntax highlighting for 13 languages
• Sub-agents — typed agents (explore, plan, general) in sync or background mode
• Parallel execution — read-only tool calls via pthreads
• Approval system — per-tool ask/deny patterns, multi-turn approval, dangerous command blocking
• MCP — Model Context Protocol server support via JSON-RPC stdio
• Providers — multiple API endpoints with runtime switching and per-provider usage tracking
• Sessions — per-directory session save/resume, named sessions
• Skills — customizable agent behaviors with auto-activation
• Memory — persistent project and global memory
• Tasks — dependency-tracked task management with task_update tool
• Sub-agents — typed agents (explore, plan, general) in sync or background mode via sub_agent tool
• Context summarization — summarize conversations to free up context space via summarize_context tool
• Codebase macros — summarize files, list symbols, and get function signatures for small models via summarize_file, list_symbols, and get_function_signature tools
• Security testing — fuzz_api, scan_endpoints, auth_scanner, schema_validator
• CVE scanning — scan dependencies (requirements.txt, package.json, go.mod) and check specific packages for known vulnerabilities
• Multi-agent coordination — file locking, task delegation, and background task management
• Learning & Skills — auto-detect corrections and create reusable skills from user feedback
• Web UI — web-based interface for interacting with codeur
• XDG compliant — respects XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME

Environment variables

Commands

See src/codeur -h for options. Type /help in interactive mode.

Man pages are available after install: man 1 codeur and man 5 codeur-config.

Flags: --chat, --continue/-c, --verbose/-v, --print/-p, --auto, --session/-s, --debug (writes debug log to $XDG_STATE_HOME/codeur/sessions/), --fast-index, --no-index, --auto=N, -P <provider>, -m <model>, --json (structured JSON output for CI/CD), --json-input (read JSON task from stdin), --ci (CI/CD mode: JSON + auto-approve), --web (start web UI server), --secret (shared secret for web API access).

Interactive commands include:

• Session management: /save, /resume, /sessions, /session new, /session switch, /session delete, /session rename, /fork, /clear
• Model & API: /model, /modelsave, /provider, /config, /context, /usage, /caps
• Agent control: /agent, /chat, /auto, /plan, /refine, /architect, /do, /think, /ask, /tasks, /learn, /coord, /bg
• Context management: /compact, /compact-history, /uncompact
• Files & tools: /undo, /diff, /changed, /add-dir, /init, /index, /review, /pr, /tools, /cve
• History: /history, /search, /export, /copy
• Memory: /memory, /memory project, /memory global, /memory add, /memory add-global, /memory clear, /memory clear-global, /memory clear-all
• Session variables: /set, /get, /unset, /vars
• System: /status, /overview, /doctor, /bug, /mcp, /reload, /verbose, /shortcuts, /help, /exit, /quit, /web
• Skills: /skill, /skill list, /skill info, /skill activate, /skill <name>

The /architect command enables dual-model architect mode, where a powerful planner model creates a detailed implementation plan, then a fast coder model implements it. Requires architect_planner and architect_coder to be configured in the [architect] section of config.ini.

Docker

The main image (Alpine 3.21, multi-stage build) runs codeur in --web mode behind a hitch TLS proxy. The browser talks HTTPS to hitch on port 8443, which forwards plain HTTP to codeur on 127.0.0.1:8080 inside the container.

Build

docker build -t codeur -f Dockerfile .

Run

# Mount the project you want codeur to work in, and your config directory:
docker run --rm -p 8443:8443 \
 -v "$PWD":/work \
 -v "$HOME/.config/codeur":/root/.config/codeur \
 codeur
# Point the browser at https://127.0.0.1:8443
# The web auth secret is printed on stdout (or set CODEUR_WEB_SECRET).

The optional positional argument overrides the working directory:

docker run --rm -p 8443:8443 -v "$PWD":/work codeur /work/myproject

Environment variables

TLS

If no certificate is supplied, a self-signed one is generated automatically (valid for localhost / 127.0.0.1, 365 days). To use your own:

# Single combined PEM:
docker run --rm -p 8443:8443 -v "$PWD":/work \
 -v "$HOME/.config/codeur":/root/.config/codeur \
 -v /path/to/fullchain.pem:/tls.pem:ro \
 -e CODEUR_TLS_PEM=/tls.pem \
 codeur
# Or separate cert and key:
docker run --rm -p 8443:8443 -v "$PWD":/work \
 -v "$HOME/.config/codeur":/root/.config/codeur \
 -v /path/to/cert.pem:/cert.pem:ro \
 -v /path/to/key.pem:/key.pem:ro \
 -e CODEUR_TLS_CERT=/cert.pem -e CODEUR_TLS_KEY=/key.pem \
 codeur

Provider config & API keys

Mount your codeur config directory so the container can read config.ini (provider URLs, API keys, model settings):

-v "$HOME/.config/codeur":/root/.config/codeur
# or set XDG_CONFIG_HOME:
-e XDG_CONFIG_HOME=/config -v "$HOME/.config/codeur":/config

Debian 12 export variant

Dockerfile.deb12 produces a standalone static binary for Debian 12 (no container runtime):

docker build -t codeur-deb12 -f Dockerfile.deb12 .
docker cp $(docker create codeur-deb12):/codeur-debian-12 .
./codeur-debian-12

Web UI

Start codeur with the web UI server:

./src/codeur --web [port]

Access the web interface at http://127.0.0.1:8080 (or the specified port).

The web UI provides a single-page application with:

• Session management and switching
• File browser and upload functionality
• MCP server status and tools
• Skills panel
• Model and provider selection
• Real-time chat interface with streaming responses
• Status bar showing model, cost, and token usage

Tests

make check # build codeur, build tests, run kyua
# or manually:
make -C src
make -C test
cd test && kyua test

Cross-compilation

Cross-compile for macOS and Linux using Zig's native build system — no Apple SDK or separate toolchain needed. The libcurl stub is built automatically as part of the build graph (no separate step):

zig build macos-arm64 # -> zig-out/cross/codeur-macos-arm64
zig build linux-musl-x64 # -> zig-out/cross/codeur-linux-musl-x64
zig build # alias for macos-arm64

Requirements: zig (0.16 or newer).

The cross-build uses vendored curl headers (deps/curl/include/) and a libcurl stub (deps/curl/stub.c) compiled into a shared library whose soname is libcurl.so.4 / libcurl.4.dylib. Only the executable is shipped; at runtime the target system's real libcurl is loaded. No Xcode or macOS SDK required.

src/*.c are auto-discovered by the build script, so the cross source list never drifts from the native build.

Note: the linux-glibc-x64 target needs glibc ≥ 2.38 (which provides strlcpy/strlcat/strtonum); older glibc requires libbsd-overlay at build time. The linux-musl-x64 target is the recommended Linux build.

License

BSD 2-clause. See individual files in deps/ for vendored dependency licenses.