QodeX — the coding agent that stays on your side of the glass

Most agent CLIs are a rented brain with a terminal skin. QodeX is the opposite: a local-first agentic coding CLI that treats your machine as the source of truth. Qwen3-Coder on Ollama / LM Studio by default. Claude / GPT / Gemini / DeepSeek only if you invite them. Your repo does not become someone else's training set.

It does not just chat about code. It reads, edits, tests, and — if you ask — ships. And when you are not at the desk, it does not get the keys to the whole Mac: shell can run in a Docker sandbox, and --profile cloud is one switch between "think local" and "think in the cloud, execute in a box."

Looking for an LLM agent, a CLI agent, or an autonomous terminal agent that can go fully offline? That's QodeX.

curl -fsSL https://raw.githubusercontent.com/QodeXcli/QodeX/main/install.sh | bash
qodex setup && qodex

Version 2.7.0 · 100+ tools · self-improving · phone-driveable · English & Persian · Apache-2.0

---

Highlights

• Local-first & private — runs entirely on your models (Qwen-Coder via Ollama / LM Studio); your code never leaves the machine. Claude / GPT / Gemini / DeepSeek are opt-in cloud fallbacks.
• --profile studio / --profile cloud — named overlays, not a second product. Local Qwen on the Mac Studio in one file; a cloud model + Docker-isolated shell in another. -p is still --print.
• Shell in a box, not on bare metal — runtime.backend: docker bind-mounts the project and drops host $HOME, docker.sock, privileged mode, and host networking. File edits stay in the repo (a coding agent that cannot touch files is a chatbot). The Mac outside /workspace stays out of reach.
• Guardrails around the model, not just prompts — a syntax gate, completion gate, and per-language auto-verification run around the agent loop, so even a weak local model can't ship broken or unverified code.
• It gets sharper the more you use it — a real self-improvement loop captures the winning approach from objectively-successful tasks as quarantined skills, an independent judge model promotes them, UCB1 A/B-tests champion vs. challenger versions, episodic memory recalls how you solved similar tasks before, and it learns from recurring failures. Your agent next week is measurably better than today's — and it never overwrites a skill you wrote.
• Always reachable — drive it from your phone — run QodeX as a Telegram / Discord / Slack service and command the same agent from chat: stream tasks, approve diffs as inline buttons, and get Living Artifacts back as cards with an AI vision review (looks-good / needs-work / broken) and Approve / Edit / Reject.
• Remembers across sessions — a layered, local memory (curated QODEX.md rules · scoped project/user facts · per-project worklog · episodic task-recall · resumable sessions) with a human-readable Markdown mirror you can edit and git-commit, and a budget-aware Light Memory Mode for small context windows. The agent builds real context about you and this codebase instead of starting every session cold.
• Live, shareable artifacts + a project dashboard — build a page / React app / dashboard that hot-reloads on every edit and auto-opens in your browser; share it over your LAN or a private, token-protected https tunnel. qodex dashboard renders a live snapshot of providers, sessions, token/cost, memory, and skills.
• Design integrations — drive Figma (3 ways) and Canva straight from the terminal over MCP.
• 100+ built-in tools — Tree-sitter code-graph, real Playwright browser automation, dev-servers, web search, vision, Docker / DB / WordPress, and any MCP server.
• Persian-first — prompts, skill matching, and generated artifact copy follow your chat language, not a fixed default.
• Token-efficient — sub-agent delegation, result-aging, compaction, and tool-gating keep the working context small on long sessions.

---

Always-on, and it compounds

An "autonomous 24/7 agent" is easy to say and hard to mean — most of the time it's a chatbot wrapped in a cron job. QodeX's always-on story is three systems that actually exist, that you can read in this repo, and that each have tests:

• Reachable any time — the transport-agnostic bot gateway runs as a persistent service, so the agent is one message away from your phone. One turn per chat at a time (no interleaving), permission prompts as inline buttons, deny-by-default auth. (Telegram / Discord / Slack)
• Improves between sessions, on its own — capture → independent-judge promotion → UCB1 version A/B → episodic recall → failure-lesson injection. The loop is gated on objective success signals, not the model's self-grade, and a new code-graph "fit" signal grounds the judge in your codebase. (Self-learning skills)
• Runs while you sleep — verifiably — a built-in cron scheduler (launchd / crontab) runs tasks unattended and delivers the result to your phone. The headline recipe, Autonomous Verified PR, works on a sandbox branch, verifies, and opens a PR only if it passed — per-task budget caps, a circuit breaker, the git sandbox, and the guardrail gates all run too, so a 3am run can't quietly ship broken code or melt your token budget. (Scheduled & autonomous)

We're not going to claim a model thinks for you around the clock. We built the parts that make unattended, repeated, real work trustworthy — and we'd rather show the code than the slogan.

---

What makes it different

Most agentic CLIs delegate to the model — they hand the model tools and trust it to use them well. That works with a frontier model and falls apart with a weaker local one (loops, half-finished edits, "done" when nothing was tested).

QodeX takes the opposite stance: protect the model. A layer of deterministic guardrails runs around the loop so even a smaller local model produces trustworthy output:

• Syntax gate — every edit is parsed before it's written; broken syntax is rejected, not saved.
• Completion gate — the model can't claim "tests pass" or "I fixed it" unless a test actually ran / an edit actually succeeded. Unsupported claims get bounced back for correction.
• Auto-verification — after the model thinks it's done, QodeX detects the project type and runs the real checker (tsc, eslint, ruff, pyright, go vet, cargo, php -l …) on touched files and force-feeds any errors back.
• Interactive edit approval — see a red/green diff and Accept / Edit / Continue / Reject before anything hits disk (or /auto on to skip).
• Git-backed sandbox — risky work runs on a hidden branch with checkpoints; auto-snapshot (git stash) before destructive commands, one command to roll back.
• Process sandbox (Docker) — a second, different isolation: the shell runs in a container so a remote-ish turn cannot rm your home directory. Pair it with --profile cloud. Not a Hub client — Hub is for approvals; this is where commands actually execute.
• Skill security scanner — skills installed from GitHub are scanned for prompt injection, secret exfiltration, destructive shell, and hidden-unicode payloads before they touch disk.

The result raises the floor (what a weak model is allowed to ship) without needing a bigger model.

Token efficiency

Long agent sessions burn tokens on a growing history, not the (cached) system prompt. QodeX keeps the working context small with four real levers:

• Delegation — heavy file-exploration runs in a read-only sub-agent (task) with a separate context window; only its summary returns, so dozens of reads never pile up in the main window.
• Result-aging — stale large tool outputs are stubbed after a few turns (re-read on demand).
• Compaction — history is structured-summarized as the window fills.
• Tool-gating — only relevant tool schemas are sent each turn (a greeting sees ~20 tools, a real task ~50, out of 100+).
• Opt-in context.efficient: true tightens all of the above for weak local models — a sliding token window that compresses large tool outputs the very next turn.

Hierarchical cache engineering

Standard agent caching pins only the static system block. QodeX goes further with a multi-tier rolling-breakpoint cache (Anthropic, on by default), so the part that actually grows — the conversation — is cached too:

• Immutable tier — core instructions + 70+ tool schemas, byte-identical across every turn of the session. A static/volatile boundary splits the system prompt so this core gets its own breakpoint and stays a cache hit the whole conversation — not just within one task.
• Ephemeral / rolling tier — per-turn injections (memory, retrieval, dir-tree) and the conversation history, pinned with a breakpoint that advances every turn.

In a deep agentic loop the re-sent prefix dominates each call, and it's now served at 0.1× instead of full price — up to ~90% off the input cost of every iteration after the first (the C × N blow-up, defused) — with no loss of granular state and no shrinking of the context window. Caching the growing history, not just the system block, is the lever; opt out with providers.anthropic.useCaching: false.

A live 12.4k/200k ████░░░░░░ 8% meter in the status bar shows how full the context window is.

What it can do

Give QodeX a task in natural language (English or Persian) and it drives a real agent loop:

• Read and edit code — read_file, write_file, edit_text, edit_symbol (AST-aware), multi_edit (single-file sequential), multi_file_edit (atomic across up to 50 files).
• Understand a codebase — ls, glob, grep, plus a Tree-sitter code-graph: project_overview, analyze_impact, find_callers, find_references, find_dead_code, safe_rename.
• Run commands — shell on the host, or inside Docker when runtime.backend: docker; plus code_run for sandboxed Python / Node / TS / PHP / Ruby (macOS sandbox-exec where available).
• Drive a real browser — Playwright-backed Chromium: navigate, click, fill, screenshot, evaluate JS, read console + page errors — to verify your own UI changes.
• Manage dev servers & jobs — dev_server_start npm run dev then browser_navigate http://localhost:5173; background_job_start for async work, all in one session.
• Search the web — DuckDuckGo by default (hardened with a lite fallback + retry), or Tavily / Brave / Firecrawl (returns full page markdown inline to save round-trips) when you set a key. Auto-fallback chain across whatever keys are present.
• Smart vision — vision_analyze automatically uses your own vision-capable model (Gemini, GPT‑4o, Claude, or a local Qwen‑VL) when your primary or sub‑agent can already see; it only spins up a dedicated vision model when neither can.
• Shareable live artifacts — build a web page / React / dashboard and serve it with artifact_live that hot‑reloads on every edit and auto‑opens in your browser