CluxMate

An AI coding agent — one Python core, three front-ends.

English · 中文文档

What is CluxMate?

CluxMate is an AI coding agent that reads your codebase, plans changes, edits files, runs commands, and answers questions. A single Python core powers three interchangeable front-ends:

It speaks the OpenAI-compatible API, so it works with DeepSeek, Qwen, GLM, OpenAI, OpenRouter, Ollama, or any self-hosted endpoint using the same protocol — just point it at a base_url. No vendor lock-in.

Screenshots

Highlights

• One core, three front-ends — the headless CLI, the REPL, the Textual TUI, and the Electron desktop all drive the exact same agent loop. The desktop app is a shell around that core; the Python agent remains fully usable on its own.
• No vendor lock-in — speaks any OpenAI-compatible API: DeepSeek, Qwen, GLM, OpenAI, OpenRouter, or a self-hosted endpoint. Configure multiple models and switch on the fly; provider failures never crash a turn, because timeouts, API errors, and network failures are translated into graceful, user-visible messages.
• Event-sourced sessions, fully traceable — every session is an append-only event log; the model's message history is derived from it, never stored separately. Every turn of every agent — main and subagents — is bracketed by turn/start/turn/end, every step logs step/start, request/header, and tool results, so the exact prompt sent at any step can be reconstructed and replayed verbatim, and context compaction rewrites a summary region without erasing the underlying events. See Sessions you can replay below.
• Stable, cache-friendly context — the system prompt never changes with your session: memory, skills, and mode are injected as tagged synthetic messages, so request prefixes stay stable and prompt caches stay hot — with per-turn cache-hit and latency metrics surfaced in the UI.
• Risk-tiered permissions — every tool declares a risk level (safe / write / dangerous / critical); four modes (plan / default / acceptEdits / yolo) plus two persistent always-allow lists (write tier + dangerous tier — delete_file, and bash per category like bash:rm / bash:python / bash:run, never whole-tool) control approval. Running code (python script.py, node app.js, npm run, ./x.sh, …) is dangerous, not safe. plan mode is read-only by construction; dangerous commands prompt unless explicitly always-allowed, and critical commands (format/mkfs/dd, etc.) and sandbox escalation always prompt.
• A two-layer sandbox — file write/delete tools are guarded by an in-process WriteFence (canonicalize-then-contain), and model-generated bash commands run inside an OS-level sandbox (Windows Low-integrity token, Linux bubblewrap, macOS Seatbelt). Sandboxing is fail-closed and only yolo mode — the explicit opt-out — disarms it. See Security: sandbox.
• Network-access guard (SSRF) — web_fetch / web_search pass through an SSRF guard in every mode (including yolo): internal/private addresses (RFC1918, loopback, link-local, cloud metadata, …) are denied by default, every redirect hop is re-validated, and DNS resolution failures close the request. Allow/block rules are configurable (~/.cluxmate/ssrf.json), managed from desktop Settings → Sandbox → Network access. See Security: network access (SSRF guard).
• Network egress control (bash/MCP) — bash and MCP stdio subprocesses can have their outbound traffic locked down: shared (unrestricted), off (kernel-level deny — bwrap --unshare-net / Seatbelt deny network*), or proxy (allowlist-only via a local filtering proxy). Default shared; Windows off is fail-closed for now. See Security: network egress (bash/MCP).
• Checkpoints & rewind — a shadow-git repository per working directory snapshots your files before and after every turn, so you can undo any turn — session-scoped, so other sessions' edits surface as conflicts, never clobbered.
• Subagent delegation — delegate independent tasks to restricted subagents (general-purpose, read-only explore) with a depth cap of 4, each with its own replayable session log.
• Doom-loop guard — if the agent starts repeating identical tool calls, escalating advisories nudge it back on track; MAX_TURNS remains the hard backstop.
• Skills, memory & MCP — project-scoped skill packs, durable project memory (AGENTS.md), and Model Context Protocol servers (stdio / HTTP) plug into the same context pipeline.
• Lifecycle hooks — run your own shell commands at UserPromptSubmit / PreToolUse / PostToolUse / Stop / SessionStart / SessionEnd / SubagentStop / PreCompact / Notification, receiving context as stdin JSON and deciding to block or inject context via stdout JSON. Hooks are your own trusted config, never sandboxed; crashes/timeouts degrade to a no-op.
• Rich toolset, safely capped — bash, file read/write/edit/delete, grep, list_dir, web_fetch, web_search, ask_user_question, subagents, skills, memory updates and more; every tool's output is capped and truncated to keep context bounded.

Architecture at a glance

┌──────────────────────────────────────────────┐
│                 Front-ends                   │
│  CLI ─── REPL ─── Textual TUI ─── Desktop    │
└──────────────────────────────────────────────┘
                     │
         JSON-RPC over stdio (desktop)
                     │
┌──────────────────────────────────────────────┐
│             Python agent core                │
│  AgentLoop ── SessionLog (event-sourced)     │
│  Builder ── Permissions ── Checkpoints       │
│  WriteFence ── Bash/MCP sandbox              │
│  Skills ── Memory ── MCP ── Subagents        │
│  Hooks ── Grants                              │
└──────────────────────────────────────────────┘
                     │
         OpenAI-compatible API (httpx)
                     │
┌──────────────────────────────────────────────┐
│  DeepSeek · Qwen · GLM · OpenAI · any base   │
└──────────────────────────────────────────────┘

The session log is the source of truth: an append-only sequence of events from which the model's message history is derived. This keeps request prefixes stable (prompt-cache friendly), enables exact replay, and survives crashes.

Sessions you can replay

Everything the agent does is recorded in an append-only event log — one .jsonl file per session — and the provider message history is derived from those events, never stored separately. That single source of truth buys a lot:

• Every turn, every step — each turn is bracketed by turn/start / turn/end; inside it, every model request logs step/start + request/header (config, system prompt, tool schemas — only when they change), and every tool call logs its result. The exact prompt sent at any step can be reconstructed verbatim (session/context shows it turn by turn).
• Environment changes are logged too — memory updates, skill loads, and mode switches are recorded as tagged synthetic user/message events (source: memory / skill / mode), and a mode or tool-schema change appends a fresh request/header with reason change — so replay shows what the agent knew and could do at every point, not just what it said.
• Subagents included — a subagent is just another agent loop with its own child SessionLog, linked to its parent via subagent/spawn pointers. Replaying a session replays the whole delegation tree, parents and children, in order.
• Compaction without erasure — when a context grows too long, compaction rewrites one region of the log into a single summary message (one ReplaceOp). The underlying events stay in the append-only log and the prompt-cache-friendly prefix stays intact — nothing is silently lost.
• Crash-safe by construction — a torn tail is dropped on load, and an interrupted turn is durably closed with synthetic tool/result + turn/end {interrupted} events, so a reloaded history is always a valid transcript. Undo rewinds to a turn boundary via a single truncate.

Security: sandbox

Permissions decide what is allowed; two enforcement boundaries make denials stick:

① WriteFence (in-process) — guards the five file tools (write_file, search_replace, multi_edit, multi_write, delete_file). Every path is canonicalized (.. and symlinks resolved) then checked: deny-list first, containment second, before any I/O. Only the working directory, the platform temp dir, and your ~/.cluxmate/AGENTS.md are writable — and <project>/.cluxmate/ (permission config, MCP servers, skills) is always off-limits so a prompt-injected model can never edit its own permission settings.

② Bash + MCP sandbox (OS-level) — model-generated bash commands run under an OS sandbox instead of your full user, with a kernel-level backend on each platform:

• Windows: a Low-integrity token (NO_WRITE_UP) with the wor