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 signals, not the model's self-grade.

How it works:

1. Capture — when a task finishes in the git sandbox and objectively succeeds (it compiled / type-checked, the completion-claim gate passed, and it took at least a few tool calls and changed a file), QodeX distills the winning approach into a SKILL.md and assigns it a confidence score (0–100) from those objective signals.
2. Quarantine — the new skill is written to ~/.qodex/skills-candidates/ (a dir QodeX never auto-loads), stamped provenance: machine, status: candidate. It can't affect the model until promoted.
3. Independent review — qodex skill curate runs an independent judge model (a different model from the one that did the work — a self-grade is refused) against a fixed rubric (reusable / correct / specific / non-redundant). The judge is grounded in your codebase: a Tree-sitter code-graph "fit" signal checks how many of the symbols a candidate references actually exist here, so a skill that name-drops APIs your project doesn't have scores lower (and the capture notice shows it: "confidence 82/100 · codebase-fit 90%"). Near-duplicate candidates are merged into one. It never overwrites a human-authored skill, and snapshots the skills dir (tar.gz) before any change so you can roll back.
4. Auto-evaluation — qodex skill eval <name> (or learning.autoEval to run it right after capture) replays the skill's original task in a throwaway git worktree and runs the real verifier (tsc/ruff/…) on the code it produces, recording pass / fail / inconclusive into the skill. It tests whether the skill actually works, not just whether a judge likes it. Content-hash cached.
5. Learning from failures — with learning.failureLessons.enabled, QodeX records tool failures and, once a mistake recurs across tasks, injects a deterministic "learned caution" into the prompt (e.g. "verify a symbol exists before edit_symbol") so it stops repeating it. One-offs never teach; see qodex skill lessons.
6. Episodic memory — with learning.episodicMemory.enabled, QodeX records a lean episode after each successful task and, at the start of a new one, recalls similar past tasks on this project and injects a one-line reminder of what worked — so it reuses its own approach instead of rediscovering it. Retrieval is smart, not noisy: an unrelated task recalls nothing, and the top-K are selected for relevance and diversity (MMR — so a recurring task doesn't inject K copies of itself), grounded against the current tree (episodes pointing at files that no longer exist are demoted, like the skill-judge's codebase-fit), with a recency tie-break toward your more recent solution.

QodeX also auto-matches your code style (indentation, quotes, semicolons, naming — inferred from the project + .editorconfig) so generated code blends in without you having to spell it out. Off via context.styleProfile: false.

# ~/.qodex/config.yaml — opt in
learning:
  enabled: true                     # capture candidates after successful tasks
  minToolCalls: 5                   # how substantial a task must be to capture
  judgeModel: llama-3.3-70b-versatile   # the INDEPENDENT judge (must differ from defaults.model)
  autoPromoteMinConfidence: 50      # hold lower-confidence captures for human review
  autoEval: false                   # run `skill eval` automatically after each capture
  failureLessons:
    enabled: true                   # learn from RECURRING tool failures
  episodicMemory:
    enabled: true                   # recall similar past tasks and reuse what worked
    topK: 2                         # how many past episodes to inject
    diversity: 0.3                  # 0–1: keep the top-K distinct, not K clones of one task

A worked example. With learning.enabled + an independent judgeModel, a typical loop:

> add cursor pagination to the /orders endpoint        # you give a task
… QodeX edits, type-checks, tests, and the sandbox merges (objective success) …
🎓 Captured candidate skill "add-cursor-pagination" (confidence 82/100)
🧪 Auto-eval of "add-cursor-pagination": pass            # (if learning.autoEval)

$ qodex skill candidates        # review the quarantined capture
$ qodex skill curate            # an INDEPENDENT judge promotes/merges the good ones
$ qodex skill stats             # captured 3 · promoted 2 · promotion rate 67%

# next week, a similar task:
> add pagination to the /users endpoint
# → QodeX recalls the past episode + loads the promoted skill automatically.

qodex skill candidates          # list quarantined captures (with confidence)
qodex skill curate              # independent judge merges + promotes the good ones
qodex skill eval <name>         # replay the skill in a clean worktree + real verify → pass/fail
qodex skill promote <name>      # promote one yourself (you are the independent reviewer)
qodex skill reject <name>       # discard a candidate
qodex skill stats               # learning metrics: captured / promoted / merged, promotion rate, avg confidence
qodex skill lessons             # cautions learned from your recurring failures
qodex skill snapshots           # rollback points;  qodex skill restore <archive>  to roll back

Every successful task can also be exported as a ShareGPT JSONL corpus (flywheel.datasetExport: true → ~/.qodex/dataset/) — a ready-to-use dataset for a future zero-cost local fine-tune. Strictly local; nothing is uploaded.

Skill versioning & A/B testing (UCB1)

A skill keeps its whole history in one flat directory — manifest.json + SKILL.v1.md, SKILL.v2.md, … — no symlinks, identical on every OS. When a new candidate is captured for an existing skill it becomes a challenger to the stable champion, and QodeX routes traffic between them with the UCB1 adaptive bandit instead of a fixed split: it explores the challenger enough to get signal, then favours whichever has the higher score — and a challenger that turns out worse has its traffic driven to zero automatically.

The score is a composite reward, not just win-rate: success dominates, but token- and time-efficiency (normalized relative to the champion) break ties — so between two equally-correct versions, the cheaper, faster one wins.

learning:
  versioning:
    strategy: ucb1                 # or 'champion-only' to freeze a sensitive skill (UCB off)
    ucbExplorationFactor: 1.41     # √2 — higher explores challengers more
    minChallengerTrials: 5         # force a challenger ≥5 runs before judging it
    rewardWeights: { success: 0.7, token: 0.15, time: 0.15 }

$ qodex skill versions git-commit-expert
Skill "git-commit-expert"  ·  strategy: ucb1  ·  routed this turn → v2

  v1  [human]   ★ champion
      success: 88% over 40  ·  tokens: 60000  ·  1900ms/run  ·  confidence: 75
      UCB: reward 0.838 + bonus 0.214 = 1.052
  v2  [machine] ⚡ challenger
      success: 92% over 12  ·  tokens: 41000  ·  1300ms/run  ·  confidence: 60
      UCB: reward 0.921 + bonus 0.391 = 1.312     ← higher → gets this turn

$ qodex skill rollback git-commit-expert v1     # snap the champion back to v1 anytime

Memory & continuity

Most CLI agents are amnesiac — every session starts from a blank slate and you re-explain the same things. QodeX remembers, across five layers that each answer a different question, so a model on your machine accumulates real context about you and your codebase over time:

The split is deliberate: your curated rules (QODEX.md, git-tracked) stay separate from the agent's auto-learned scratchpad (the DB) — no machine write ever touches your authoritative file, and there are no merge conflicts. Facts are scoped — a project fact (a build command, a gotcha) is auto-injected only when you start in that directory; a user fact ("prefers Persian comments", "always run tests before saying done") follows you into every project. Recall is smart, not heavy: episodic memory injects only relevant, de-duplicated past tasks above a threshold (an unrelated task recalls nothing) — a one-line reminder, never a full transcript.

A Markdown mirror you can read, edit, and git-commit. /memory export writes the agent's learned facts to a human-readable MEMORY.md (project) and ~/.qodex/memory.md (user). Edit them by hand — fix a wrong fact, add three — and /memory import folds your changes back into the DB (additive). The DB stays the source of truth; the Markdown is the window into it.

Light Memory Mode for small context windows. On a roomy model, every fact is injected (memory.mode: full). On a tight local model, set memory.mode: lightweight (or auto) — QodeX injects your !important-tagged facts plus as many recent ones as fit a token budget, and leaves the rest to load on demand. Your memory doesn't shrink; only what's pushed into each prompt does.

Searchable memory (FTS5). As facts pile up, dumping the newest N isn't enough — recall query="deploy key" does a relevance-ranked full-text search (SQLite FTS5) over your facts and pulls out the specific one, so the agent finds an old gotcha instead of rediscovering it. This is the on-demand half of Light Memory Mode: lightweight mode keeps prompts small, and search retrieves anything it left out. The index stays in sync automatically and falls back to a substring scan if a build lacks FTS5.

> the build here is `npm run build:prod`, not `npm run build`
🧠 remembered (project)              # silently re-injected next time you start in this dir

/memory                              # show what's stored for this project
/memory export                       # write the human-readable MEMORY.md mirror
/memory import                       # pull hand-edited facts from the markdown back in
/memory forget <substring>          # drop matching facts
/project        ·  /project log <e>  # this project's worklog (view · append)
/sessions       ·  /resume <id>      # list past sessions · rehydrate one

# ~/.qodex/config.yaml — tune what gets pushed into each prompt (DB + mirror are unaffected)
memory:
  mode: auto              # full | lightweight | auto (lightweight on small context windows)
  injectMaxTokens: 2000   # budget for facts in lightweight mode (!important always included)

It all lives under ~/.qodex/ — nothing is uploaded, the same privacy line as your code.

Install

One line (macOS · Linux · WSL)

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

Checks for git + Node 20+ (installs Node via your package manager if it's missing or too old), clones QodeX to ~/.qodex-src, builds it, and puts qodex and qx on your PATH. Idempotent — re-run it to update. Knobs: QODEX_SRC_DIR, QODEX_BRANCH, QODEX_NO_LINK=1; preview without touching anything via QODEX_DRY_RUN=1.

Prefer to read before you pipe to bash? The script is install.sh in this repo — or follow the manual steps below.

Manual

Prerequisites: Node 20+ (Node 22 LTS recommended) and Git. dist/ is built locally (not committed), so the npm run build step is required on every platform. The build links two commands — qodex and the short alias qx.

macOS

# Node + Git via Homebrew (or use nvm). Check: node -v  →  v20+  
brew install node git

git clone https://github.com/QodeXcli/QodeX.git qodex && cd qodex
npm install
npm run build
npm link            # puts `qodex` and `qx` on your PATH

Linux

# Debian/Ubuntu — get Node 20+ from NodeSource if your distro ships an older one
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git
# (Fedora: sudo dnf install nodejs git    ·    Arch: sudo pacman -S nodejs npm git)

git clone https://github.com/QodeXcli/QodeX.git qodex && cd qodex
npm install
npm run build
sudo npm link       # or plain `npm link` if your npm prefix is user-writable

Windows

Open PowerShell and install Node + Git (via winget, or the installers from nodejs.org / git-scm.com):

winget install OpenJS.NodeJS.LTS Git.Git
# reopen PowerShell so PATH refreshes, then:
git clone https://github.com/QodeXcli/QodeX.git qodex; cd qodex
npm install
npm run build
npm link            # `qodex` and `qx` on PATH

Windows tip: if the native better-sqlite3 module fails to compile, install the C/C++ build tools (npm install --global windows-build-tools, run PowerShell as Administrator) — or use WSL2 and follow the Linux steps above (recommended for the smoothest experience).

Optional — browser automation (all platforms)

Playwright-backed Chromium for the browser_* tools (~200 MB, one-time):

npm install playwright
npx playwright install chromium

Then run qodex setup to detect your local models and write ~/.qodex/config.yaml.

Updating to a newer version

The easy way — one line (works no matter how you first installed):

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

The installer is idempotent: it pulls the latest main, rebuilds, and re-links qodex/qx. Re-running it replaces your old version in place — you don't need to uninstall anything first. At the end it checks that the qodex your shell runs is actually the fresh build, and if an older copy is still winning on your PATH it prints the exact one-line fix.

From inside QodeX (once you're on a build new enough to have it):

qodex update --check      # is a newer version available?
qodex update              # git pull → npm install → npm run build (then restart qodex)

If you cloned manually into a folder (e.g. ~/Downloads/qodex) and want that folder updated:

cd ~/Downloads/qodex          # your existing clone
git pull                       # get the latest code
npm install && npm run build   # rebuild (dist/ is not committed — this step is required)
npm link                       # make sure `qodex` points here

Coming from an old copy and just want a clean switch? Delete the old clone and use the one-liner — it installs to ~/.qodex-src and takes over the qodex command:

rm -rf ~/Downloads/qodex       # or wherever your old copy lives (safe: it's just source)
npm uninstall -g @qodex/cli 2>/dev/null; hash -r   # drop any stale global link
curl -fsSL https://raw.githubusercontent.com/QodeXcli/QodeX/main/install.sh | bash

Verify which build is active any time:

command -v qodex     # where the command resolves
qodex --version      # the version now running

After updating, restart QodeX (and any running session) so the new dist/ is loaded — the running process keeps the old build until it exits.

Quick start

# Setup wizard — detects local models, writes ~/.qodex/config.yaml
qodex setup

# Or just start it
qodex
> read package.json and summarize what this project does

Configuration

Lives in ~/.qodex/config.yaml. A minimal local-model setup pointed at LM Studio:

defaults:
  provider: openai
  model: qwen/qwen3-coder-next
  preferLocal: true

providers:
  ollama:
    baseUrl: http://localhost:11434
  openai:
    apiKeyEnv: OPENAI_API_KEY
    baseUrl: http://127.0.0.1:1234/v1   # point at LM Studio
    extraModels:
      - id: qwen/qwen3-coder-next
        contextWindow: 32768
        supportsToolCalls: true

roles:
  subagent:
    provider: ollama
    model: qwen3-coder      # smaller/faster model for delegated reads

context:
  efficient: false          # set true on weak local models to save tokens

subagents:
  mode: parallel            # off | sequential | parallel

Large (MoE) models on limited VRAM + local "turbo cache"

Big Mixture-of-Experts coders (Qwen3-Coder-MoE, DeepSeek-MoE) don't have to fit entirely in VRAM — keep some layers on the GPU and the rest on the CPU via Ollama's num_gpu, which QodeX forwards verbatim:

providers:
  ollama:
    keepAlive: 30m            # keep the model + its KV cache warm between turns — the local "turbo cache"
    options:
      num_gpu: 14             # layers on GPU; the rest run on CPU (lower = fits a bigger model)
      num_ctx: 32768          # KV-cache size; QodeX already defaults this to the model's window

Not sure what num_gpu to use? Let QodeX figure it out:

qodex offload                 # auto-detects VRAM (nvidia-smi / Apple unified memory) + the
                              # model's size & layer count from Ollama, and suggests a num_gpu
qodex offload --apply         # …and writes it to providers.ollama.options.num_gpu
qodex offload --vram 12       # override the VRAM budget if auto-detect is off

e.g. a 48 GB MoE on a 12 GB GPU → keep ~14/64 layers on the GPU, the rest on CPU. (The pure core is suggestGpuLayers in src/llm/offload.ts.)

Two things make local fast here: keep_alive keeps the model resident so there's no cold reload, and QodeX's byte-stable prompt prefix (hierarchical cache work above) means the engine's KV prefix cache hits instead of re-prefilling the whole context every turn — the local counterpart to Anthropic prompt caching.

Run the model on another box — qodex tunnel. Local-first answer to remote backends: SSH-forward to a workstation running Ollama/LM Studio and drive it from your laptop, code and execution staying local.

qodex tunnel --host workstation --user me --remote-port 11434 --local-port 11434
# → point providers.ollama.baseUrl at http://localhost:11434; the 70B/MoE model runs over there.

Cloud providers are opt-in. Web-search keys are read from the environment, never the config file:

export TAVILY_API_KEY=tvly-...
export BRAVE_SEARCH_API_KEY=...
export FIRECRAWL_API_KEY=fc-...          # set FIRECRAWL_SCRAPE_CONTENT=1 for inline markdown

Built-in tools

100+ tools across these areas — run /tools inside QodeX for the full list with descriptions:

Slash commands

/help              Overview
/network           Diagnose internet + Ollama + LM Studio connectivity
/tools [--all]     List registered tools by category
/plan  /normal     Plan mode (read-only)  /  back to normal
/auto on|off       Auto-approve permissions
/model <id>        Override model for this conversation
/subagents off|sequential|parallel
/snapshot list|take|restore        Manage auto-snapshots
/cost  /tokens     Token / cost usage
/index [--force]   Build/refresh the code graph
/mcp               List connected MCP servers
/memory [export|import|forget <s>|clear]   Learned facts — show · mirror to MEMORY.md · import edits · drop · wipe
/project [log <e>] This project's worklog — view, or append an entry
/sessions  /resume <id>  /clear  /exit

Plus any custom commands you drop in .qodex/commands/ as markdown.

End-to-end example

> add a logout button to the navbar in src/Header.tsx and verify it works

QodeX will: read Header.tsx → add the button (shown as an approvable diff) → dev_server_start npm run dev → browser_navigate localhost → click the button → check the console for errors → screenshot → vision_analyze to confirm it looks right → run the type-checker on the touched file → stop the server and report. One agent loop, with the guardrails above running throughout.

Telegram / Discord / Slack bot

Drive the same agent from chat — stream tasks to QodeX from your phone:

# 1. put the token(s) in ~/.qodex/.env (secrets never go in config)
echo 'TELEGRAM_BOT_TOKEN=123:abc' >> ~/.qodex/.env
#   Slack uses Socket Mode (no public URL needed) and TWO tokens:
#   echo 'SLACK_APP_TOKEN=xapp-...' >> ~/.qodex/.env
#   echo 'SLACK_BOT_TOKEN=xoxb-...' >> ~/.qodex/.env

# 2. enable the platform + allowlist your user id (deny-by-default) in config
#    bot:
#      telegram: { enabled: true, allowedUsers: ["<your-telegram-id>"] }
#      discord:  { enabled: true, allowedUsers: ["<your-discord-id>"] }   # needs: npm i discord.js
#      slack:    { enabled: true, allowedUsers: ["<your-slack-user-id>"] } # needs: npm i @slack/socket-mode @slack/web-api

# 3. run it from the project directory you want it to work in
qodex bot                 # all enabled platforms · --telegram / --discord / --slack to pick one

One transport-agnostic gateway does all the work; the platform adapters are thin — Telegram needs zero installs, Discord and Slack are optional lazy-loaded deps. Adding a platform is one adapter implementing the same Transport seam, so behaviour never drifts between them.

Talk to it — voice memos. Send a Telegram voice message and QodeX transcribes it and runs it as your turn (it echoes 🎙️ "…" so you can see what it heard). Local-first, like web-search and vision: point QODEX_TRANSCRIBE_CMD at any local STT (whisper.cpp, faster-whisper, a script — {file} is the audio path, STDOUT is the transcript) for a fully-offline path, or set OPENAI_API_KEY for the cloud fallback. Neither configured ⇒ a friendly "just type" note, never a crash. The bug-classes that wreck chat-agent UIs are each solved once: throttled, coalesced streaming with code-fence-aware spill across messages (no edit-flood / no sheared code blocks), one turn per chat at a time (later messages queue — no interleaving), permission prompts as inline buttons (tap or reply), and deny-by-default auth (a coding agent runs shell on your host, so an empty allowlist admits no one; "*" opts into public access deliberately).

Full agent control from your phone. Commands live in one declarative registry, so every command is also pushed to the client as a native / menu (tap-to-pick, with descriptions) — no memorizing:

Adding a command is one entry — Telegram, Discord, and Slack all gain the command, its menu item, and its /help line. Capabilities a given build doesn't support degrade to a friendly note, never a crash.

Living Artifacts in chat — with an AI vision review. Ask for a dashboard, a landing page, or a chart from your phone and QodeX doesn't dump code at you — it builds a versioned artifact, renders it, and (for web types) runs a vision self-review that actually looks at the result and verdicts it LOOKS_GOOD / NEEDS_WORK / BROKEN, listing concrete issues. You get back a compact card:

📊  Sales dashboard  ·  html · v3
🔎  vision review: NEEDS_WORK
    • legend overlaps the Q4 bars
    • contrast too low on the dark header
[ ✅ Approve ]   [ ✏️ Edit ]   [ ❌ Reject ]   [ 🔗 Open live ]

Tap Edit and reply with the change in plain language; tap Open live for the hot-reloading, token-protected https link. The agent iterates create → preview → review → fix until the vision check passes — the same loop the CLI runs, now driven from chat.

Scheduled & autonomous — the real "24/7"

Plenty of agents say "autonomous 24/7." QodeX has a plain, boring scheduler