diff --git a/AGENTS.md b/AGENTS.md index 77dcead..4453b08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index bf3a118..12e9b34 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/README.md b/README.md index 031cc56..ca72a89 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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 @@ -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 diff --git a/doc.go b/doc.go index e5be114..ee75ab5 100644 --- a/doc.go +++ b/doc.go @@ -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: //