diff --git a/README.md b/README.md index 4e54acb..cb00b3e 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,10 @@ # qmax-code +[![Latest release](https://img.shields.io/github/v/release/Quality-Max/qmax-code?label=release&color=217a45)](https://github.com/Quality-Max/qmax-code/releases/latest) [![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-2ea44f.svg)](LICENSE) [![Future License: Apache 2.0](https://img.shields.io/badge/future%20license-Apache%202.0-blue.svg)](LICENSE) -[![Made with Go](https://img.shields.io/badge/made%20with-Go-00ADD8.svg)](https://go.dev/) +[![Made with Go](https://img.shields.io/badge/made%20with-Go%201.24+-00ADD8.svg)](https://go.dev/) [![Announcement](https://img.shields.io/badge/announcement-2026--05--01-7c6cf0.svg)](https://qualitymax.io/blog/qmax-code-open-source) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/qualitymax) @@ -34,6 +35,16 @@ Use the built-in agent with Anthropic, Cerebras, or Ollama, or use **orchestration mode** to run Claude Code, Codex, or OpenCode with the same qmax QA tools through MCP. +![Five open QualityMax tools and where qmax-code sits among them](docs/img/family.svg) + +qmax-code is the terminal agent that drives a QA session. It sits alongside +[free-qa-skills](https://github.com/Quality-Max/free-qa-skills) (read-only +audits inside a coding agent), [qmax-mcp](https://github.com/Quality-Max/qmax-mcp) +(scan a page, generate a repro, run it locally), +[9lives](https://github.com/Quality-Max/9lives) (heal broken selectors), and +[qmax-local-agent](https://github.com/Quality-Max/qmax-local-agent) (let the +cloud reach a private network). Only hosted QualityMax needs an account. + > **License:** Source-available under the > [Functional Source License (FSL-1.1-ALv2)](LICENSE), created by > [Sentry](https://fsl.software). It is free for non-competing use, including @@ -42,6 +53,8 @@ QA tools through MCP. ## What qmax-code can do +![Plan, generate, execute, review, and ship, over a local repository lane](docs/img/lifecycle.svg) + - **Plan and manage QA work:** list and manage projects and test cases, enhance cases, find coverage gaps, and import requirements or repositories. - **Generate and execute tests:** create Playwright, pytest, Go, and Rust tests; @@ -64,11 +77,24 @@ Some advanced surfaces—k6, QTML, framework export/trigger operations, and background-job health—remain experimental and are only exposed when `QMAX_EXPERIMENTAL=1`. -## What is new in v1.21 +## What is new + +### v1.22 -- **Standalone local-only mode:** start with `--local` (or persist +- **Cloud-routed MCP tool calls (v1.22.1):** `serve --mcp` now routes + authenticated QualityMax tool calls through the cloud MCP endpoint instead of + calling the REST API directly. Calls made through the local MCP server were + previously invisible to the platform — they set no trace context, so they + produced no session history — and they returned UI-shaped REST payloads + carrying every script's full source. Browser login now mints an + MCP-compatible token, so the routing works immediately after sign-in. +- **Standalone local-only mode (v1.22.0):** start with `--local` (or persist `local_only=true`) to skip QualityMax onboarding and expose only workspace - file, command, and planning tools. + file, command, and planning tools. MCP children inherit the mode, and + execution-time checks reject direct calls to hidden QualityMax tools. + +### v1.21 + - **Exposure Receipts:** every session that makes an outbound LLM or QualityMax API request writes a signed local egress manifest that can be inspected and verified offline. @@ -188,20 +214,7 @@ 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. -```text -you - │ - ▼ -qmax-code REPL ── /orch chooses one backend - │ - ├─ built-in loop: Anthropic API / Cerebras / Ollama - │ - └─ CLI agent: Claude Code / Codex / OpenCode - │ - └─ embedded qmax MCP server - ├─ connected: QualityMax + local QA tools - └─ --local: workspace tools only -``` +![The /orch picker selects one backend; mode decides which tools exist](docs/img/orchestration.svg) 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 diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 5c01fac..0ea06d9 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,6 +1,6 @@ # Command reference -This reference describes the qmax-code v1.21 command-line and interactive +This reference describes the qmax-code v1.22 command-line and interactive surfaces. Run `qmax-code --help` for the flags compiled into your installed version and `/help` for its REPL commands. diff --git a/docs/img/family.svg b/docs/img/family.svg new file mode 100644 index 0000000..363a33e --- /dev/null +++ b/docs/img/family.svg @@ -0,0 +1,59 @@ + + Where qmax-code sits among the QualityMax tools + free-qa-skills audits, qmax-mcp proves one change, 9lives repairs broken tests, qmax-code orchestrates the session from a terminal, qmax-local-agent gives the cloud reach into a private network, and hosted QualityMax manages the QA program. Only the hosted service requires an account. + + + Five open tools, one QA program + + + AUDIT + free-qa-skills + 27 read-only QA skills, run + inside a coding agent + + + PROVE + qmax-mcp + scan a page, generate a repro, + run it locally. No account. + + + REPAIR + 9lives + heal broken selectors and + show a diff for approval + + + ORCHESTRATE — YOU ARE HERE + qmax-code + the terminal agent that drives + the session, connected or local + + + REACH + qmax-local-agent + lets the cloud run tests inside + a private network or CI runner + + + MANAGE — ACCOUNT REQUIRED + Hosted QualityMax + projects, suites, runs, + and observability + + Skills find issues · qmax-mcp proves a change · 9lives repairs the test · qmax-code runs the session · hosted QualityMax keeps the program + Everything except the amber card works without a QualityMax account. + diff --git a/docs/img/lifecycle.svg b/docs/img/lifecycle.svg new file mode 100644 index 0000000..e4e1fbe --- /dev/null +++ b/docs/img/lifecycle.svg @@ -0,0 +1,60 @@ + + What qmax-code covers across the QA lifecycle + Five connected stages — plan, generate, execute, review, ship — sitting on top of a local repository lane that also works without a QualityMax account. + + + + + + + + One agent across the QA lifecycle + + + PLAN + projects and test cases + coverage gaps + requirement imports + + + + GENERATE + Playwright · pytest + Go · Rust + from crawls or cases + + + + EXECUTE + cloud browser runs + native Go/Rust runner + or locally + + + + REVIEW + quality and coverage + security and risk + saved preferences + + + + SHIP + open test PRs + generate a GitHub + Actions workflow + + + Local repository lane — read, edit, search, run allowlisted commands and tests + This lane is what standalone --local mode keeps. The stages above need a QualityMax connection. + diff --git a/docs/img/orchestration.svg b/docs/img/orchestration.svg new file mode 100644 index 0000000..1207f06 --- /dev/null +++ b/docs/img/orchestration.svg @@ -0,0 +1,72 @@ + + qmax-code orchestration mode + The /orch picker selects one inference backend for a qmax-code turn: the built-in agent loop running Anthropic, Cerebras, or Ollama, or a CLI subprocess running Claude Code, Codex, or OpenCode, which receives qmax tools through an embedded MCP server. Connected or standalone mode decides which tools exist, independently of the backend. + + + + + + + + One picker. Six backends. The same qmax tools. + + + you + + + + + qmax-code REPL + terminal UX · tool policy · QualityMax context + + + + + /orch + backend · model · effort + + + + + + BUILT-IN AGENT LOOP + + Anthropic API + + Cerebras + + Ollama + qmax-code runs the tool loop itself + + + CLI SUBPROCESS + + Claude Code + + Codex + + OpenCode + qmax tools arrive through the embedded MCP server + + + + + + WHICH TOOLS EXIST IS SET BY MODE, NOT BY BACKEND + connected: QualityMax + local QA tools · --local: workspace tools only +