Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 25 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,33 @@ Instructions for coding agents working on qmax-code.

## What this is

qmax-code is evolving into a **standalone IDE with optional, first-class
QualityMax connectivity through MCP**. The current Go terminal agent is the
foundation: it works on local repositories without a QualityMax account and
can connect to QualityMax for hosted QA workflows. Through `/orch` it can
launch Claude Code, Codex, Antigravity, or OpenCode while keeping qmax tools
and terminal UX — or run the built-in loop on Anthropic, Cerebras, or Ollama.
qmax-code is a **developer-first coding environment**: a Go terminal agent
that works on the repository in front of the user, with no account, no
project, and no QualityMax request in standalone mode. It is evolving into a
**standalone IDE with optional, first-class QualityMax connectivity through
MCP**. Through `/orch` it hosts Claude Code, Codex, Antigravity, or OpenCode
while keeping qmax tools and terminal UX, or runs the built-in loop on
Anthropic, Cerebras, or Ollama.

This repository is **Go 1.27.3+**, not TypeScript. The thing users install is one
compiled binary.

## Positioning

The product direction is an independent development environment for coding,
testing, review, and agent workflows. QualityMax is an optional integration
with first-class MCP support, rather than a prerequisite for using the IDE.
QA remains a core strength: crawl, generate/run tests, review, heal, and receipts.
Claude Code, Codex, Antigravity, and OpenCode are selectable coding backends.
Lead with the developer. The product is the environment a developer works
in: their repo, their terminal, their choice of model and agent, their keys
in their keychain. QualityMax is an optional integration with first-class
MCP support, never a prerequisite. QA remains a core strength, framed as part
of the developer's own loop (write, test, review, ship) rather than as a
separate service.

Be exact about the standalone boundary. `--local` exposes five agent tools
(`update_plan`, `read_file`, `write_file`, `edit_file`, `run_command`), the
`/orch` backends, and `/skills`. Test generation from managed test cases,
hosted test runs, crawls, repository review, project and test-case
management, PR creation, CI setup, and script healing require a QualityMax
connection. Say so when describing a feature; do not imply a connected tool
works offline.

Distinguish the IDE direction from capabilities shipped today. The current
release is a terminal application; describe planned IDE features as future work.
Expand All @@ -34,9 +44,10 @@ release is a terminal application; describe planned IDE features as future work.
- **OpenCode** = opt-in providers (Z.AI GLM, Groq, OpenRouter) via
`/providers`.

When writing product-direction copy, say “a standalone IDE with optional,
first-class QualityMax connectivity through MCP.” Describe current terminal
capabilities accurately and attribute inference speed to the backend.
When writing product-direction copy, say "a developer-first coding
environment, evolving into a standalone IDE with optional, first-class
QualityMax connectivity through MCP." Describe current terminal capabilities
accurately and attribute inference speed to the backend.

## Why Go

Expand Down
30 changes: 17 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
# CLAUDE.md

qmax-code is evolving into a **standalone IDE with optional, first-class
QualityMax connectivity through MCP**. Its current foundation is a **Go**
terminal agent (Go 1.27.3+). It ships as one compiled binary:
`curl | bash` installs a file, not a Node or Python runtime.
Claude Code, Codex, Antigravity, and OpenCode are separate subprocesses that `/orch` can
host; they are not this repository's runtime.

**Positioning:** an independent environment for coding, testing, review, and
agent workflows. QualityMax is optional, with first-class MCP connectivity;
using qmax-code does not require a QualityMax account. QA (tests, crawls,
review, receipts) remains a core strength. Describe the standalone IDE as the
product direction and the terminal app as what ships today; describe planned
IDE features as future work.
qmax-code is a **developer-first coding environment** evolving into a
**standalone IDE with optional, first-class QualityMax connectivity through
MCP**. Its current foundation is a **Go** terminal agent (Go 1.27.3+). It
ships as one compiled binary: `curl | bash` installs a file, not a Node or
Python runtime. Claude Code, Codex, Antigravity, and OpenCode are separate
subprocesses that `/orch` can host; they are not this repository's runtime.

**Positioning:** lead with the developer: their repo, their terminal, their
choice of model and agent, their keys in their keychain. Standalone mode
(`--local`) needs no QualityMax account and exposes five agent tools (plan,
read, write, edit, run command) plus `/orch` backends and `/skills`. Hosted
test runs, test generation from managed cases, crawls, repository review,
project management, PR creation, CI setup, and healing require a QualityMax
connection; say so rather than implying they work offline. QA is a core
strength, framed as part of the developer's own write-test-review-ship loop.
Describe the standalone IDE as the product direction and the terminal app as
what ships today; describe planned IDE features as future work.
qmax-code switches inference in `/orch`. **Cerebras** is the fast path
(~1000–2000+ tok/s: GPT-OSS 120B, GLM 4.7, Gemma 4; **Qwen 3.8 coming soon**).
Do not add Qwen to the picker until Cerebras publishes the live model ID.
Expand Down
117 changes: 66 additions & 51 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,22 +26,19 @@

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/qualitymax)

**Building an open-source standalone IDE with optional, first-class QualityMax connectivity through MCP.** Named after Max, the real cat who inspired it all.
**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 is evolving into an independent development environment for coding,
testing, review, and agent workflows. QualityMax is an optional integration,
with first-class connectivity through MCP as part of that direction.
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`.

Today, qmax-code ships as a Go terminal application that works on local
repositories without a QualityMax account. Connect to QualityMax to manage
projects and test cases, crawl sites, generate and run tests, review
repositories, heal scripts, and prepare CI. The current client calls the
QualityMax API directly and exposes tools to coding-agent backends through
its embedded MCP server; the separate `qmax` CLI is optional.

Use the built-in agent with Anthropic, Cerebras, or Ollama, or use
**orchestration mode** to run Claude Code, Codex, Antigravity, or OpenCode with the same qmax
QA tools through MCP.
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.

![qmax-code startup banner in standalone local-only mode](docs/img/terminal.png)

Expand All @@ -65,18 +62,37 @@ cloud reach a private network). Only hosted QualityMax needs an account.
> including for commercial use. No waiting period or non-compete restriction.
> [Read the announcement →](docs/releases/v1.38.0.md)

## Where it sits

The goal is a **standalone IDE** where local development, coding agents, and
QA workflows share one environment. QualityMax connectivity through MCP is
optional and first-class: it extends the environment with hosted QA services
without making a QualityMax account a requirement for local work.

The current terminal application is the foundation for that IDE. It already
supports local file editing, commands, tests, and selectable coding backends.
Connected workflows add crawls, hosted tests, repository review, and healing.
The standalone IDE is the product direction; the capabilities documented
below describe the terminal release available today.
## 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
Expand All @@ -85,40 +101,39 @@ in `/orch`; do not run two CLIs and two configs.

| Job | Pick |
| --- | --- |
| Tests, crawls, coverage, QualityMax projects | qmax-code connected (or `--local` for workspace-only) |
| 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 |

In the current terminal release, use `/orch` to select the backend for your
next task. Local coding works without QualityMax; enable connected mode when
you need its hosted QA workflows.
| Hosted browser tests, crawls, coverage, QualityMax projects | qmax-code connected |

## 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;
run browser tests in QualityMax, run Go/Rust tests on the native runner, or
execute supported tests locally.
- **Crawl and inspect applications:** discover pages, generate test scenarios,
analyze screenshots and page elements, and optionally watch test/crawl runs
through a live terminal browser feed.
- **Review and ship:** analyze repositories for quality, coverage, security, and
testing risk; honor saved review preferences; create test PRs; and generate a
GitHub Actions test workflow.
- **Work on local repositories:** read, create, and edit files; search code; run
allowlisted commands and tests. Standalone mode provides this lane without a
QualityMax login.
- **Extend coding agents:** install QA skills into Claude Code, Codex, and
OpenCode, including accessibility, performance, security, dependency,
usability, flaky-selector, and release-gate workflows.

Some advanced surfaces—k6, QTML, framework export/trigger operations, and
background-job health—remain experimental and are only exposed when
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
Expand Down
19 changes: 11 additions & 8 deletions doc.go
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
// Command qmax-code is the terminal foundation for a standalone IDE with
// optional, first-class QualityMax connectivity through MCP.
// Command qmax-code is a developer-first coding environment: a terminal
// agent that works on the local repository with no account required, and the
// foundation for a standalone IDE with optional, first-class QualityMax
// connectivity through MCP.
//
// It runs standalone against a local repository or connects to QualityMax,
// and can switch inference between the Anthropic API, Cerebras, Ollama, and
// hosted coding agents (Claude Code, Codex, Antigravity, OpenCode) through
// /orch. It supports local coding, QA work, and exposure receipts. Connected
// workflows add test generation and execution, app crawling, and repository
// review.
// In standalone mode (--local) it reads, writes, edits, and searches files
// and runs allowlisted commands and tests, using the Anthropic API, Cerebras,
// or Ollama for inference, or hosting Claude Code, Codex, Antigravity, or
// OpenCode through /orch. Every outbound request is recorded in a signed
// Exposure Receipt. Connecting to QualityMax adds hosted test generation and
// execution, app crawling, repository review, and project management over
// the same MCP server.
//
// Install a release binary:
//
Expand Down
Loading