OptiQ Code
OptiQ Code is a terminal coding agent that drives whatever model optiq serve is serving, on your Mac, fully offline. It is built to stay reliable on small local models. It always returns a working patch when one exists, and it recovers from failed edits and stalled turns rather than dead-ending. Every session is recorded so you can resume or export it.
This guide continues in six more pages: Approval & permissions, Sessions & traces, Headless & CI, the Tools reference, Robustness, and Cloud & remote models.
Install & launch
textual and openai ship with the wheel, so there is nothing extra to install. OptiQ Code talks to optiq serve over the OpenAI Chat Completions API and discovers the served model automatically.
$ pip install mlx-optiq # serve a model once, freeing its RAM after 5 min idle $ optiq serve --model mlx-community/Qwen3.6-27B-OptiQ-4bit --idle-timeout 300 # launch in a repo (or: optiq code PATH) $ cd my-project && optiq code
If no server is running, OptiQ Code tells you how to start one. Point it at a server on another port or host with OPTIQ_BASE_URL, or pass --model to have it spawn one for you.
How the loop works
Each turn, the agent calls the model, runs whatever tools the model asks for, and feeds the results back. It grounds a change by reading the relevant files, makes an edit, runs your tests, and reads the pass/fail count, so both it and the stall detector track real progress rather than text. It keeps going until the model gives a final answer (a plain reply with no tool call ends the turn, like a chat), or the goal is done, or a limit is hit. The working git diff is the source of truth for what changed, salvaged on every exit path (scoped to the files the agent touched). The mechanics of that resilience are covered in Robustness.
Commands & keys
The interactive UI is deliberately familiar. Type a task and press Enter; the model works and answers, and the turn ends when it does. Slash commands and keys cover the rest. Type / or @ to open an autocomplete menu (slash commands, or repo files for an @-mention), and Tab completes it.
| Slash command | Effect |
|---|---|
| /help | List the commands |
| /init | Analyze the repo and write an AGENTS.md guide (reads any existing AGENTS.md/CLAUDE.md first) |
| /model | Show the model, endpoint, and context window |
| /resume | Pick a past conversation in this repo (↑/↓ picker); /resume N loads directly |
| /copy | Copy the agent's last reply to the clipboard |
| /compact | Compact the context now (drop old tool output) |
| /clear | Clear the screen and start a fresh context |
| /quit | Exit (aliases /exit, /q) |
| Key | Effect |
|---|---|
| Enter | Send. Shift-Enter / Ctrl-J insert a newline; a paste keeps its newlines |
| ↑ / ↓ | Walk input history (moves between lines first in a multiline prompt) |
| Esc | Interrupt the running turn; Esc Esc opens a picker to rewind to an earlier turn |
| Tab | Cycle mode: standard ↔ plan (read-only). The status bar shows which one is live |
| Ctrl-V | Attach an image from the clipboard. Dragging a file onto the prompt attaches it too |
| /mcp | List connected MCP servers and the tools they expose |
| Shift-Tab | Cycle approval: approve each edit ↔ auto-approve all |
| Ctrl-C | Copy a selection if any, else clear the line, else press twice to exit |
Scrolling & selection. Like other full-screen TUI agents, OptiQ Code captures the mouse, so a two-finger trackpad swipe (or the wheel) scrolls the transcript; PageUp/PageDown and Ctrl-Home/Ctrl-End work too. To select text, hold your terminal's bypass key while dragging (Fn on macOS Terminal.app, Option on iTerm2), or use /copy. Prefer no-modifier drag-selection? Set "mouse": false in the config; you lose trackpad scroll but the scroll keys still work.
Images
If the model you are serving reads images, OptiQ Code can send it one. There are two ways in, and they match what a terminal can actually deliver.
Drag a file onto the prompt. Your terminal responds to a dropped file by typing its full path, and OptiQ Code takes it from there: the path leaves the text, the picture is attached, and the status bar shows a count. Type your question alongside it and press Enter.
Press Ctrl-V to paste one. A screenshot on your clipboard cannot arrive through a normal paste, because a terminal only carries text, so OptiQ Code reads the clipboard itself. Cmd-V still pastes text as usual.
# headless, one or more images $ optiq code -p "Why does this layout break?" --image ~/shot.png $ optiq code -p "Which renders correctly?" --image a.png --image b.png
Only absolute paths attach on their own. A drop always produces one, while a sentence like "fix the logo in assets/logo.png" is talking about a file rather than attaching it, and quietly uploading it would be the wrong read.
The image goes on the message you send it with, not on every message after. It stays in the model's context from that point, and re-sending it each turn would spend a local context window on something the model already has. PNG, JPEG, GIF, WebP and BMP, up to 10 MB each.
optiq serve.Configuration
| Flag / env | Effect |
|---|---|
| optiq code [PATH] | Launch the interactive TUI in a repo (default: current dir) |
| --model | Serve and drive this model if no server is already running |
| -p / --print | Headless run toward a goal, then exit (see Headless) |
| -c / --continue | Resume the most recent session in this repo |
| -r / --resume <id> | Resume a specific session by id |
| OPTIQ_BASE_URL | Point at a server on another port or host, or a cloud endpoint |
| OPTIQ_API_KEY | Bearer token for the server (default sk-optiq-local) |
These, plus per-model settings (context window, approval mode, max tokens, mouse capture), can live in a config file instead of flags: ~/.optiq/code/config.json for every repo, or <repo>/.optiq/code.json for one. Precedence is flag > env > repo config > user config > default; optiq code config prints the resolved values and where each came from.
Prefer a cloud or third-party model over a local one? Point OptiQ Code at any OpenAI-compatible endpoint with your own key; see Cloud & remote models.
Choosing a model
optiq serve is serving. For best results, use the OptiQ quant with the highest Capability Score your Mac can run; in general Qwen3.8-27B-OptiQ-4bit is the best pick. Serve a no-think variant when the model supports it, so the model answers directly.Track record
An initial version of OptiQ Code, driving a 4B local model, resolved 36% of a SWE-bench-Lite subset, state of the art at that size, with a valid patch on every task, versus 40% empty for a comparable-budget baseline. A stronger local quant raises the resolve rate. The reliability features work the same regardless of model size. See the product overview.