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. An opt-in read denylist hides secrets (.env, *.pem, ~/.ssh, …) from the model and from shell/MCP subprocesses. 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.
• One tree per task (git worktrees) — a session can run in its own linked git worktree on its own branch, created from the desktop sidebar or with cluxmate worktree …, so parallel sessions stop fighting over the same files. Inside a tree the composer stops offering branch switches (the tree is its branch) and the project's branch list hides what other trees hold; deleting the session can take the tree with it. See Session worktrees.
• Subagent delegation — delegate independent tasks to restricted subagents (general-purpose, read-only explore, and an evidence-gated reviewer that fixes nothing), or define your own in Markdown. Recursion is capped at depth 4, parallelism is bounded (4 at once, 2 of them writers), and every child gets a turn budget, a machine-readable status header, and its own replayable session log.
• Code intelligence (LSP) — a read-only lsp tool exposes 10 navigation operations (go-to-definition, find-references, hover, call hierarchy, diagnostics, …) across seven language-server specs (Python, TypeScript, JavaScript, Go, Java, Rust, C/C++). Nothing is bundled: servers come from your PATH, and after every edit the language server's error-level diagnostics ride back in the write tool's result. See Code intelligence (LSP).
• 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), opt-in retrieval memory, and Model Context Protocol servers (stdio / HTTP) plug into the same context pipeline.
• Remote MCP with OAuth — HTTP MCP servers can authenticate with OAuth 2.0 (discovery → dynamic client registration → PKCE on a loopback callback), driven from the desktop MCP panel or cluxmate mcp auth / logout / status. Tokens live in ~/.cluxmate/mcp-auth.json, are always denied to the model's read path, and — deliberately — no tool exists that can trigger authorization. See Remote MCP servers & OAuth.
• 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.
• Honest completion — an agent's own summary is a claim, not evidence: every reply is reconciled against the tool calls that actually ran, and an unsupported claim is bounced back once. A subagent that reports success while its own audit says otherwise is downgraded to partial. See Trust, but verify.
• Rich toolset, safely capped — bash, file read/write/edit/delete, grep, list_dir, lsp, web_fetch, web_search, ask_user_question, todo_write, subagents, skills, memory updates and more; every tool's output is bounded — an oversized result keeps a head/tail preview and spills the rest to disk instead of flooding the context.

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              │
│  LSP ── 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