╱|、
                                   (˚ˎ 。7
                                    |、˜〵
                                    じしˍ,)ノ

             ██████╗ ███╗   ███╗ █████╗ ██╗  ██╗
            ██╔═══██╗████╗ ████║██╔══██╗╚██╗██╔╝
            ██║   ██║██╔████╔██║███████║ ╚███╔╝
            ██║▄▄ ██║██║╚██╔╝██║██╔══██║ ██╔██╗
            ╚██████╔╝██║ ╚═╝ ██║██║  ██║██╔╝ ██╗
             ╚══▀▀═╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝
                             c o d e

qmax-code

Documentation · CLI quickstart · Latest release

An open-source coding environment built for developers first: your repository, your terminal, your choice of models and agents. One Go binary, no account required. Evolving into a standalone IDE with optional, first-class QualityMax connectivity through MCP. Named after Max, the real cat who inspired it all.

qmax-code runs against the repository in front of you. It reads, edits, and searches code, runs allowlisted commands and tests, and keeps QA in the same loop as coding: write the change, generate the tests, run them, review the diff, ship. Bring your own inference (Anthropic, Cerebras, or Ollama) or host the coding agent you already use (Claude Code, Codex, Antigravity, or OpenCode) and switch between them with /orch.

QualityMax is an opt-in extension, not a prerequisite. Connect it when you want hosted browser test runs, crawls, project and test-case management, or repository review. Its tools reach whichever agent you run through the embedded MCP server, and /disconnect takes them away again.

The terminal UI uses Bubble Tea for interactive pickers and input, Lip Gloss for styling, and Glamour for Markdown output.

qmax-code brings local coding and QA workflows into one agent environment. It sits alongside free-qa-skills (read-only audits inside a coding agent), qmax-mcp (scan a page, generate a repro, run it locally), 9lives (heal broken selectors), and qmax-local-agent (let the cloud reach a private network). Only hosted QualityMax needs an account.

qmax-code is now Apache 2.0. Starting with v1.38.0, use, modify, fork, and redistribute the CLI under the Apache License 2.0, including for commercial use. No waiting period or non-compete restriction. Read the announcement →

Built for developers

• Local by default. qmax-code --local needs no login, no project, and makes no QualityMax request. Your code leaves the machine only through the inference backend you chose; pick Ollama when it should not leave at all.
• Your keys, your agents. Use an Anthropic or Cerebras key, a local Ollama endpoint, or a Claude Code or Codex install you have already signed in to. Keys live in the OS keychain or in environment variables, never in a QualityMax proxy.
• One binary. curl | bash installs a single Go executable for macOS, Linux, and Windows on Intel and ARM. No Node, Python, or version manager.
• Nothing hidden. Exposure Receipts write a signed local manifest of every LLM and cloud-API egress. Telemetry is off unless you set two environment variables. Local commands run under an allowlist with your user permissions.
• QA inside the dev loop. A catalog of QA skills (diff risk, secrets, dependencies, accessibility, Core Web Vitals, flaky selectors, release gates, and more) installs into Claude Code, Codex, and OpenCode with /skills install, so review happens before the PR, not after.
• QualityMax when you want it. Connected mode adds hosted Playwright execution, crawls, test generation from managed test cases, repository review, script healing, and CI setup through MCP. Disconnect and everything above keeps working.

Where it is going

The direction is a standalone IDE where local development, coding agents, and QA share one environment, with QualityMax as an optional, first-class MCP integration. The terminal application is the foundation and what ships today: file editing, commands, tests, selectable backends, QA skills, and the connected tools listed below. Planned IDE features are future work; everything documented in this README describes the current release.

Go makes the binary install once. Cerebras makes tokens fast (today: GPT-OSS 120B, GLM 4.7, Gemma 4 at ~1000–2000+ tok/s; Qwen 3.8 coming soon). Claude Code and Codex are the careful path for hard design. Switch in /orch; do not run two CLIs and two configs.

Job	Pick
Edit, search, run commands and tests in a local repo	qmax-code --local with any backend
Fast loops, bulk generation, cheap iteration	/orch → Cerebras
Hard design, tricky refactors	/orch → Claude Code or Codex
GLM on a coding plan	/providers → Z.AI, then OpenCode in /orch
Air-gapped / local weights	Ollama
Hosted browser tests, crawls, coverage, QualityMax projects	qmax-code connected

What qmax-code can do

The table shows what works in standalone mode and what connecting to QualityMax adds. Standalone exposes exactly five agent tools (plan, read, write, edit, run command) plus whichever backend /orch selects; every other tool is refused until you connect.

Capability	Standalone (--local)	Connected to QualityMax
Read, create, edit, and search files in your repository	Yes	Yes
Run allowlisted commands and your own test suites	Yes	Yes
Host Claude Code, Codex, Antigravity, or OpenCode through /orch	Yes	Yes, with qmax tools served over MCP
Install QA skills into those agents with /skills install	Yes	Yes
Exposure Receipts for every outbound request	Yes	Yes
Generate Playwright, pytest, Go, and Rust tests from managed test cases	No (the model writes tests directly with the file tools)	Yes
Run browser tests in QualityMax, Go and Rust tests on the native runner	No	Yes
Crawl an app, generate scenarios, analyze screenshots and page elements	No	Yes, optionally with the live terminal browser feed
Review a repository for quality, coverage, security, and testing risk	No	Yes, honoring saved review preferences
Manage projects and test cases, enhance cases, find coverage gaps, import requirements	No	Yes
Create test PRs and a GitHub Actions test workflow	No	Yes
Heal broken scripts and roll back script versions	No	Yes

Some advanced surfaces (k6, QTML, framework export/trigger operations, and background-job health) remain experimental and are only exposed when QMAX_EXPERIMENTAL=1.

Latest changes

See the latest release for the current version and release notes. The maintained source and release history are the authoritative place for changes between versions.

Install

curl -sL https://qualitymax.io/static/install-qmax-code.txt | bash

To build from source instead:

go install github.com/Quality-Max/qmax-code@latest

Or from a checkout:

git clone https://github.com/Quality-Max/qmax-code.git
cd qmax-code
go build -o qmax-code .
./qmax-code --version

Go 1.27.3 or newer is required for source builds.

Why Go

qmax-code is a compiled Go program, not a Node or Python app. That is why it installs like a Unix tool.

• One file. curl | bash drops a single binary. There is no Node, npm, Python, or version manager to keep in sync.
• Every OS from one source tree. A release is six binaries — macOS, Linux, and Windows, Intel and ARM — from the same code.
• Starts immediately. A terminal agent you open all day cannot wait on an interpreter.
• Concurrent without extra machinery. The agent turn, live browser feed, signals, and MCP server run as goroutines in one process.

Go does not make the model smarter, and qmax-code is not faster than Claude at thinking. Token speed is the inference backend (Cerebras today; Qwen 3.8 on Cerebras soon). Claude Code, Codex, and OpenCode remain separate tools that qmax-code can host through /orch. Go makes qmax-code itself install once and run like curl, git, or rg.

Quick start

Standalone local-only

Run qmax-code without a QualityMax account:

# Use an already authenticated coding-agent CLI:
qmax-code --local --backend codex
qmax-code --local --backend cc

# Or use the built-in agent with your selected inference provider:
qmax-code --local

The built-in path still needs an inference backend: an Anthropic or Cerebras key, or a configured Ollama endpoint. --local means no QualityMax login, project, or cloud request; it does not mean that a third-party model provider is offline. Use Ollama on a local endpoint when you also want inference to stay on your machine.

To make standalone mode the default:

qmax-code config set local_only true
qmax-code

# Return to QualityMax-connected startup:
qmax-code config set local_only false

Standalone qmax tools are deliberately limited to read_file, edit_file, write_file, run_command, and the built-in agent's update_plan. QualityMax projects, hosted tests, crawls, imports, cloud sessions, live feeds, and the cloud-backed run_local_test workflow are unavailable. CLI backends may also have their own native coding tools, governed by their permission settings.

QualityMax-connected

Log in for cloud-backed tools:

qmax-code login

The browser flow is the default. You can instead use an API key from QualityMax Settings:

qmax-code login --api-key qm-YOUR-API-KEY

Then start qmax-code and choose an inference backend:

qmax-code

# Inside the REPL:
> /orch

For the direct Anthropic backend, set a session-only key before launch:

export ANTHROPIC_API_KEY=YOUR_KEY
qmax-code

You can also provide a prompt directly:

qmax-code "crawl staging.myapp.com and generate e2e tests"
qmax-code -p "run all tests for project 42"
qmax-code --backend codex -p "review this repository's test strategy"

Orchestration mode

/orch is qmax-code's unified backend, model, and effort picker. It is not a separate model and it does not create several agents. It selects which inference engine handles the conversation while keeping qmax-code as the host for terminal UX, QualityMax context, and tools.

For CLI backends, qmax-code launches the selected agent as a subprocess and serves qmax tools through its embedded MCP server. On first activation you choose one of two permission levels:

• Standard (recommended): auto-approves reads, searches, status/diff inspection, common test runners, and qmax tools. File edits and destructive shell commands remain gated.
• Unattended: grants the CLI agent full file and shell autonomy. Use only in a trusted repository.

Claude Code and Codex also offer an optional global MCP installation. Accepting it adds qmax to their user-level configuration so qmax QA tools are available when those CLIs are launched outside qmax-code. Declining keeps the integration scoped to qmax-code sessions. OpenCode uses a qmax-managed overlay config rather than modifying the user's main OpenCode configuration.

Read Orchestration mode for backend requirements, provider setup, permission behavior, installed files, switching, and troubleshooting.

qmax-code orchestration is separate from Conductor's parallel-workspace orchestration. Conductor can run multiple isolated qmax-code development workspaces; /orch chooses the inference backend inside one qmax-code session.

Backend guide

Backend	Select with	Authentication	Notes
Anthropic API	/api or /orch	ANTHROPIC_API_KEY or OS keychain	Built-in agent loop; tool set follows connected vs. standalone mode.
Claude Code	/cc or /orch	Local Claude Code login	CLI subprocess; qmax tools arrive through MCP. Uses Claude Code authentication and plan/provider billing; see subscription setup.
Codex	/codex or /orch	Local Codex login	CLI subprocess using the user's OpenAI access; qmax tools arrive through MCP.
Antigravity	/agy or /orch	Google OAuth (run agy once to sign in)	CLI subprocess using the same Google account as AI Studio. No Gemini API key. qmax tools arrive through MCP.
Cerebras	/gemma, /orch, or --backend cerebras	CEREBRAS_API_KEY or OS keychain	Built-in native function calling. Fast inference (~1000–2000+ tok/s): GPT-OSS 120B, GLM 4.7, Gemma 4 (vision + effort). Qwen 3.8 coming soon.
OpenCode	/opencode or /orch	Per-provider key in OS keychain	CLI subprocess for opt-in Z.AI, Groq, and OpenRouter providers.
Ollama	/ollama or /orch	Configured Ollama endpoint	Self-hosted inference; configure the URL and model first.

Haiku 5.5 is an explicit option in the Anthropic API and Claude Code pickers, or with /model claude-haiku-5-5. The haiku shorthand and automatic chat routing continue to use Haiku 4.5 until the upgrade is verified. Direct Haiku 5.5 requests disable thinking to reserve the response budget for text and tools. Cost estimates preserve each request's prompt-size tier and reported cache tokens; historical sessions without recorded costs remain estimates.

QualityMax authentication is independent of model-provider authentication. You can run any backend with --local and no QualityMax login. Without --local, qmax-code starts the QualityMax onboarding flow when no supported QualityMax connection is available. Cloud projects, crawls, hosted test runs, imports, and repository analysis always require connected mode.

QA skills

qmax-code ships the following agent skills:

• QA workflows: migration to Playwright, release quality gates, pre-change SAST, and failure triage.
• Static review: diff risk, secrets, dependencies, dead code, complexity, error handling, test quality, and flaky selectors.
• Browser/runtime audits: accessibility, broken links, cold-load waterfall, console errors, cookies/privacy, Core Web Vitals, form validation, i18n/RTL, mixed content, page weight, responsive screenshots, security headers, SEO, third-party bloat, and UI/UX.

Use these commands from the REPL:

/skills          Show every skill and its Claude Code/Codex/OpenCode status
/skills install  Refresh the catalog in all supported CLI backends

Browser/runtime skills also require a Playwright MCP server in the consuming agent. qmax-code declares that dependency in the Codex skill metadata.

Useful commands

/orch                    Pick backend, model, and effort
/agy                     Switch to Antigravity (Google OAuth)
/providers               List opt-in OpenCode providers
/providers enable groq   Store a provider key and enable its models
/skills                   Show managed QA skills and install status
/live on                  Stream eligible test/crawl browser runs in the terminal
/feed                     Reopen the latest live browser feed
/sessions                 Pick a saved session to resume
/queue <prompt>           Add follow-up work; typing during a turn also queues it
/theme                    Preview and select a terminal theme
/cost                     Show token usage and estimated cost
/plan                     Show coding-plan usage window (5h limit + reset time)
/config                   Show session configuration
/help                     Show the full in-app command reference

See Command reference for subcommands, flags, REPL commands, configuration keys, and keyboard shortcuts.

Sessions and automation

Interactive sessions auto-save by default. For a one-shot command, use --save-session with any backend to make it available through --resume last:

qmax-code --save-session -p "review the current diff"
qmax-code --resume last
qmax-code --list-sessions

Switching models, effort levels, or providers preserves one shared conversation. Claude Code, Codex, Antigravity, and OpenCode reuse their native session when available; returning to a backend transfers the turns it missed. Built-in Anthropic, Cerebras, and Ollama receive the shared history, including exposed CLI tool activity. /save, /resume, and --resume retain this state across restarts. --resume last -p "continue the review" --save-session also works.

The retained transcript is separate from the model's compacted working context. Large conversations use a private, searchable JSONL file plus recent context; the destination agent can retrieve older details with its file tools. Provider context windows still apply. Hidden reasoning and provider-private state cannot be transferred, and image interpretation depends on the destination's support. Only content exposed to qmax-code can be retained; this cannot recover history that an older version already discarded.

To keep a ruled-out approach visible when you switch backends, record the decision and its evidence explicitly:

/handoff reject Increase the timeout | TestReconnect still fails at 60s; the connection is never reopened
/handoff
/handoff forget 1

/handoff lists the current rejected approaches and their user-supplied evidence. The checkpoint is part of every built-in provider prompt and is sent to a CLI backend whenever it has not seen the current version, remains visible when history is compacted, and survives /save and /resume. Write \| for a literal pipe inside the approach. After a backend switch that follows unrecorded work, qmax-code prints a one-line reminder to record anything that was ruled out, mentioning interrupted turns and failed tool calls it can see. /handoff forget <number> removes an outdated rejection; /clear resets it. Notes are redacted using the retained-transcript rules and capped at 12 KiB in total. Recording notes makes no additional model calls. qmax-code does not automatically classify failed commands as rejected approaches or independently verify the evidence. The destination is instructed to check the notes before acting and explain any justified retry; model compliance is not guaranteed. See handoff notes and the live evaluation procedure.

Saved conversations live in ~/.qmax-code/sessions/; those carrying a portable transcript are kept for 90 days, legacy sessions for 7. /clear resets the shared conversation and native resume state and starts a new session ID, so the conversation you cleared stays listed by /sessions and remains resumable. Save errors are reported. If a native session is rejected by its CLI, the failed turn remains in the transcript and the next request restores portable context into a fresh session.

Cloud session sync is opt-in:

/cloudsync
/set cloud_sync true
/set cloud_sync false

Cloud session sync is unavailable in standalone local-only mode. Local session save/resume and prompt queues continue to work.

Live browser feed and images

Turn on /live to request QualityMax Cloud Sandbox execution for eligible browser tests and AI crawls. qmax-code displays the stream in the terminal and keeps the latest feed available through /feed.

/live, /feed, and /browserfeed are connected-mode commands and are unavailable in standalone local-only mode.

Use /screenshot to capture a screen and /paste to attach clipboard text or an image. Image attachments are supported by the built-in multimodal path (including Gemma 4 on Cerebras).

For CLI backends, the Gemma 4 vision sidecar can send images to Cerebras and pass their text descriptions to the selected coding model. It requires a Cerebras key. The default auto mode enables this for OpenCode with Z.AI coding-plan models; always enables it for every CLI backend, and off disables it. Set the mode with /set vision_sidecar auto|always|off or qmax-code config set vision_sidecar off.

If the sidecar fails, screenshots and clipboard images use the built-in multimodal backend when configured; otherwise the turn stops without sending the image. Dragged image paths retain the text-only CLI fallback. Cancelling the sidecar skips the turn.

Exposure Receipts

When a session makes outbound requests, qmax-code writes a signed manifest under ~/.qmax-code/receipts/. The receipt records LLM and cloud-API egress without storing prompt bodies, file contents, model responses, shell output, or credential values.

qmax-code receipt list
qmax-code receipt show latest
qmax-code receipt verify latest

Offline verification proves that the receipt was produced by this agent's local signing key; it is provenance evidence, not proof that every possible network path was disclosed. Cross-check receipts against your own egress logs when that assurance matters.

Authentication and credential storage

• QualityMax browser/API-key credentials are stored in ~/.qmax-code/auth.json with 0600 permissions. /disconnect removes them.
• Anthropic and Cerebras keys saved through qmax-code are stored in the OS keychain. Environment variables remain available for session-only or CI use.
• OpenCode provider keys are opt-in per user and stored in the OS keychain. Disabling a provider hides it but keeps its key so it can be re-enabled.
• qmax-code codex connect starts a fresh Codex OAuth login and securely attaches it to the authenticated QualityMax user.
• qmax-code cc connect reads the active local Claude Code credentials and securely attaches them to the authenticated QualityMax user.
• Known credential patterns are redacted from API errors, command output, local test output, and optional telemetry.

Local safety

qmax-code is a trusted local terminal agent. Local file and command tools run with your user permissions in the current workspace; they are not a sandbox. CLI orchestration in unattended mode is broader still and can edit files, run arbitrary commands, and push commits.

Standalone mode prevents qmax-code from loading QualityMax credentials or exposing QualityMax tools. It does not sandbox the selected inference backend or suppress that backend's own network traffic.

Read SECURITY.md before using local execution or unattended orchestration in an unfamiliar repository.

Telemetry

qmax-code does not send telemetry off-machine by default. Crash and error reporting requires both:

export QMAX_CODE_TELEMETRY=1
export QMAX_CODE_TELEMETRY_DSN=YOUR_SENTRY_COMPATIBLE_DSN

When enabled, reporting is limited to structural metadata such as backend, status code, model identifier, input length, and image count. Prompt content, file contents, LLM responses, credentials, and shell output are not included. Unset either variable to disable reporting.

Architecture

Path	Purpose
main.go	Process entry, flags, subcommands, login, backend startup, and one-shot mode
internal/repl/repl.go	Interactive REPL, slash commands, backend switching, queue, and live feed
internal/agent/agent.go	Built-in streaming agent loop, tool use, routing, and history compression
internal/agent/tools.go	Tool schemas, safety gates, dispatch, local execution, and healing
internal/agent/{cc,codex,opencode}_agent.go	CLI orchestration backends
internal/agent/{cerebras,ollama}_agent.go	Built-in alternative inference backends
internal/api/	QualityMax client, auth, provider registry, models, and persistent config
internal/mcp/server.go	Embedded stdio MCP server for CLI backends
internal/setup/orch.go	MCP registration and QA-skill installation
internal/skills/	Backend-neutral QA-skill catalog and materialization
internal/session/	Local/cloud sessions and prompt queue
internal/tui/	Terminal rendering, input, themes, media, and model pickers
internal/httpx/ and receipt.go	Guarded outbound HTTP and Exposure Receipt integration

Development

go build -o qmax-code .
go test ./...
go vet ./...

See CONTRIBUTING.md for architecture, development workflow, testing, security-sensitive areas, and pull-request expectations.

Cat personality

Max is a curious explorer, playful bug hunter, and proud test presenter. Use --professional or /set professional true when you prefer a direct, personality-free response style.

  /\_/\
 ( o.o )   "knocks bugs off the table"
  > ^ <    "nine lives, zero regressions"
 /|   |\   "if it fits I sits, if it breaks I test it"
(_|   |_)  meow.

---

Building an open-source standalone IDE. Optional, first-class QualityMax connectivity through MCP. Licensed under Apache 2.0.