QodeX — the local-first LLM agent & coding CLI agent

QodeX is an open-source LLM agent for your terminal — a local-first, agentic coding CLI. It runs on local models (Qwen3-Coder via Ollama / LM Studio) by default, with Claude / GPT / Gemini / DeepSeek as optional cloud fallbacks. A privacy-first AI coding agent built so a model on your machine does real, multi-step engineering work — fully offline if you want.

If you're looking for an LLM agent, a CLI agent, an AI coding agent, or an autonomous terminal agent that doesn't ship your code to someone else's cloud — that's QodeX.

Version 2.5.0 · 100+ built-in 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.
• 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.
• 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 — bash, 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 so you watch it change live; share="network" opens it to your LAN and share="tunnel" gives a private https link your team can open (token‑protected) — a live PR walkthrough or project dashboard.
• Design integrations (Figma + Canva) — qodex mcp add figma (3 ways: your logged‑in desktop Dev Mode, a personal token, or hosted OAuth) and qodex mcp add canva (OAuth login) let the model turn a Figma frame into code or build a Canva design — driven from the terminal over MCP.
• Matches your code style automatically — QodeX infers the project's conventions (indentation, quotes, semicolons, naming) from its own source + .editorconfig and writes new code to match, without you having to configure or remember anything. Off via context.styleProfile: false.
• Self‑learning skills — after a task that objectively succeeded (verified + honest, ≥ a few tool calls), QodeX can capture the winning approach as a candidate skill in quarantine. An independent judge model (a different model from the one that did the work) reviews it before it’s promoted, and a human‑authored skill is never overwritten. Drive it with qodex skill candidates | curate | promote. Off by default (learning.enabled).
• Trade‑off & business analysis — ask it to analyze or plan (not code) and it produces decision‑grade output: options × weighted criteria → a scored comparison and one clear recommendation, business‑plan structure, no invented numbers.
• Persian‑first — skill auto‑loading and tool selection understand Persian prompts (تحلیل، دیتابیس، آرتیفکت…), not just English keywords.
• Verify its own work — auto_fix runs your test command in a fix→test loop with an iteration cap and same-failure-twice detection; the auto‑verify gate runs the right checker per language in a polyglot repo (TS and Python both get checked).
• Git — status, diff, log, branch, commit, create-pr, release-notes.
• Skills — install from a curated registry or any GitHub repo (single / multi / catalog), security-scanned on the way in; search_skills to find them.
• Sub-agents & orchestration — task delegates to a separate model/window; orchestrate runs a DAG of sub-agents; gather fans out reads in parallel.
• MCP — connect any MCP-compatible server; its tools join the same registry as built-ins.
• Live control dashboard — qodex dashboard (alias dash) opens a local, token-protected control panel (127.0.0.1 only) that doesn't just show your QodeX — providers, sessions, token/cost, memory, skills — it drives it: toggle prompt caching / efficient mode / memory mode / sub-agents / learning, enable·disable·remove scheduled tasks, forget a memory fact, and apply MoE offloading — changes hit your real config and stores. Every capability is one entry in an action registry, so the panel grows to cover all of QodeX. --static writes the old read-only HTML snapshot.
• Add a provider by just asking — tell QodeX "add Groq with my key" and the add_provider tool wires the gateway into ~/.qodex/config.yaml (key stays in ~/.qodex/.env, never the config); or run qodex provider add for a guided setup. Unknown providers are refused unless you give a base URL + key-env, so nothing is silently misconfigured.
• Domain tools — Docker, databases, WordPress (php -l linting), media (ffmpeg), frontend/print, OpenAPI digest, and more.

Self-learning skills

QodeX can learn reusable playbooks from your successful tasks — without the usual failure mode of an agent rubber-stamping its own work and overwriting your hand-tuned skills. The whole loop is off by default and gated on objective signal