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
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ jobs:
run: go build ./...

- name: Lint
uses: golangci/golangci-lint-action@v6
with:
version: latest
# Build with the project's Go toolchain; the v1 release binary was
# built with Go 1.24 and cannot analyze this module's Go 1.25 target.
run: go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8 run

- name: Vet
run: go vet ./...
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ standalone on a local repository or connected to QualityMax. Through `/orch`
it can launch Claude Code, Codex, or OpenCode while keeping qmax tools and
terminal UX — or run the built-in loop on Anthropic, Cerebras, or Ollama.

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

## Positioning
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CLAUDE.md

qmax-code is a **Go** terminal **QA** agent (Go 1.24+). It ships as one
qmax-code is a **Go** terminal **QA** agent (Go 1.25.13+). It ships as one
compiled binary: `curl | bash` installs a file, not a Node or Python runtime.
Claude Code, Codex, and OpenCode are separate subprocesses that `/orch` can
host; they are not this repository's runtime.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Thanks for your interest in improving `qmax-code`. This document covers everythi

| Requirement | Notes |
|---|---|
| **Go 1.24+** | See `go.mod` for the exact version. `go version` to check. |
| **Go 1.25.13+** | See `go.mod` for the exact version. `go version` to check. |
| **Inference backend** | The direct API path needs an Anthropic key. You can instead develop against a logged-in Claude Code/Codex CLI, an enabled OpenCode provider, Cerebras, or Ollama. |
| **QualityMax account** | Required only for connected cloud tools (test generation, crawl, repo review). Standalone `--local` development and most unit tests do not need one. |

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ go build -o qmax-code .
./qmax-code --version
```

Go 1.24 or newer is required for source builds.
Go 1.25.13 or newer is required for source builds.

## Why Go

Expand Down Expand Up @@ -334,7 +334,7 @@ troubleshooting.
| 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. Agent SDK usage may be separately metered by Anthropic. |
| 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](docs/ORCHESTRATION.md#claude-code-subscription-billing). |
| Codex | `/codex` or `/orch` | Local Codex login | CLI subprocess using the user's OpenAI access; 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. |
Expand Down
1 change: 1 addition & 0 deletions codexrunner/model.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ var (
ErrInvalidModel = errors.New("codex runner: invalid model")

supportedModels = [...]string{
"gpt-6-astra",
"gpt-5.6-sol",
DefaultModel,
"gpt-5.6-luna",
Expand Down
80 changes: 80 additions & 0 deletions docs/ORCHESTRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,86 @@ QualityMax authentication is separate from backend authentication. Use
`--local` to skip QualityMax authentication entirely. QualityMax cloud tools
require connected mode and `qmax-code login`.

## Go integration with Claude Code and Codex

qmax-code calls both native harnesses directly from Go. As of September 5,
2026, their official harness SDKs are available for Python and TypeScript;
neither provider documents an official Go harness SDK.

| Harness | Go integration used here | Continuation |
| --- | --- | --- |
| Claude Code | `os/exec` with `claude --print --output-format stream-json` | `--resume` with the native session ID |
| Codex | The Go `codexrunner` package with `codex exec --json` | `codex exec resume` with the native thread ID |

Anthropic explicitly recommends a CLI subprocess for other languages in its
[Agent SDK overview](https://code.claude.com/docs/en/agent-sdk). OpenAI documents
the JSONL stream and saved CLI authentication in its
[non-interactive guide](https://learn.chatgpt.com/docs/non-interactive-mode);
its [SDK guide](https://developers.openai.com/codex/sdk/) covers the Python and
TypeScript libraries. Codex's [app server](https://learn.chatgpt.com/docs/app-server)
also exposes a language-independent JSON-RPC interface for richer custom clients.

The providers' Go **API client** SDKs are separate from these coding harnesses.
Adding an API client would not provide the native agent loop or subscription
login. The current subprocess integration keeps qmax-code a single Go binary,
with Claude Code and Codex installed and updated separately. `go mod tidy` or
updating Go modules does not update those CLI executables.

## GPT 6 Astra and Claude Fable 5.1

Select **GPT 6 Astra** under Codex, or **Fable 5.1** under Claude Code or
Anthropic API in `/orch`. The exact IDs are `gpt-6-astra` and
`claude-fable-5-1`; `fable` is a shorthand for Fable 5.1. Existing defaults
and the explicit Fable 5 model remain available.

```bash
qmax-code --local --backend codex --model gpt-6-astra
qmax-code --local --backend cc --model fable
# Direct API billing:
qmax-code --local --backend api --model claude-fable-5-1
```

The `/orch` Codex selection is saved separately from Claude's preference and
survives `/clear`. **Codex default** (or `--backend codex --model auto`)
uses Codex's own model configuration. Approval and sandbox policy continue to
come from Codex configuration. Model access depends on the account used by
the native CLI. See the [Astra model reference](https://developers.openai.com/api/docs/models/gpt-6-astra)
and [Fable 5.1 reference](https://platform.claude.com/docs/en/models/fable-5-1/overview).

## Claude Code subscription billing

Yes: qmax-code can use the native Claude Code harness with a Claude subscription
login, without an Anthropic API key. The `cc` backend runs `claude --print`
and connects qmax tools through MCP. It inherits Claude Code authentication;
it does not require `qmax-code cc connect` or a QualityMax login in local mode.

For subscription authentication, remove the API-key override from the shell
that launches qmax-code, then open Claude Code and use `/login` to sign in with
your Claude account and `/status` to verify authentication:

```bash
unset ANTHROPIC_API_KEY
claude
# After signing in and exiting Claude Code:
qmax-code --local --backend cc --model fable
```

An inherited `ANTHROPIC_API_KEY` takes precedence over subscription login and
causes API billing. See [Anthropic's authentication guidance](https://support.claude.com/en/articles/12304248-manage-api-key-environment-variables-in-claude-code).

As of September 5, 2026, the separate third-party Agent SDK billing change
announced for June 15 remains paused. Anthropic's
[June 15 update](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan)
confirms that Agent SDK, `claude -p`, and third-party app usage still draw from
subscription limits. Conductor also documents continued subscription use in
its [billing update](https://www.conductor.build/blog/claude-subscription-update).

Fable 5.1 specifically requires Claude Code **2.1.255 or later**. Max and eligible
premium Team/legacy Enterprise seats include Fable usage up to 50% of the weekly
limit. Pro and standard seats use paid usage credits for Fable 5.1 from the first
request. A subscription login therefore does not guarantee included Fable usage;
check your tier and extra-usage settings in [Anthropic's Fable plan guide](https://support.claude.com/en/articles/15424964-claude-fable-models-on-your-plan).

## Standalone local-only orchestration

Every backend can be selected in standalone mode:
Expand Down
45 changes: 24 additions & 21 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,44 +1,47 @@
module github.com/qualitymax/qmax-code

go 1.24.0
go 1.25.13

require (
github.com/BourgeoisBear/rasterm v1.1.2
github.com/Quality-Max/qmax-receipt v0.1.0
github.com/charmbracelet/bubbletea v1.3.10
github.com/charmbracelet/glamour v0.8.0
github.com/charmbracelet/lipgloss v1.1.0
github.com/charmbracelet/x/ansi v0.10.1
github.com/charmbracelet/glamour v1.0.0
github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
github.com/charmbracelet/x/ansi v0.11.8
github.com/chzyer/readline v1.5.1
github.com/coder/websocket v1.8.14
github.com/getsentry/sentry-go v0.44.1
golang.org/x/sys v0.36.0
golang.org/x/term v0.22.0
github.com/coder/websocket v1.8.15
github.com/getsentry/sentry-go v0.49.0
golang.org/x/sys v0.47.0
golang.org/x/term v0.45.0
)

require (
github.com/alecthomas/chroma/v2 v2.14.0 // indirect
github.com/alecthomas/chroma/v2 v2.27.0 // indirect
github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
github.com/aymerick/douceur v0.2.0 // indirect
github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
github.com/charmbracelet/x/term v0.2.1 // indirect
github.com/dlclark/regexp2 v1.11.0 // indirect
github.com/charmbracelet/colorprofile v0.4.3 // indirect
github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
github.com/charmbracelet/x/exp/slice v0.0.0-20260902165432-6f6ad8b37b0a // indirect
github.com/charmbracelet/x/term v0.2.2 // indirect
github.com/clipperhouse/displaywidth v0.11.0 // indirect
github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
github.com/dlclark/regexp2/v2 v2.7.1 // indirect
github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
github.com/gorilla/css v1.0.1 // indirect
github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/lucasb-eyer/go-colorful v1.4.1 // indirect
github.com/mattn/go-isatty v0.0.24 // indirect
github.com/mattn/go-localereader v0.0.1 // indirect
github.com/mattn/go-runewidth v0.0.16 // indirect
github.com/mattn/go-runewidth v0.0.29 // indirect
github.com/microcosm-cc/bluemonday v1.0.27 // indirect
github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
github.com/muesli/cancelreader v0.2.2 // indirect
github.com/muesli/reflow v0.3.0 // indirect
github.com/muesli/termenv v0.16.0 // indirect
github.com/rivo/uniseg v0.4.7 // indirect
github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
github.com/yuin/goldmark v1.7.4 // indirect
github.com/yuin/goldmark-emoji v1.0.3 // indirect
golang.org/x/net v0.27.0 // indirect
golang.org/x/text v0.16.0 // indirect
github.com/xo/terminfo v1.0.0 // indirect
github.com/yuin/goldmark v1.8.6 // indirect
github.com/yuin/goldmark-emoji v1.0.6 // indirect
golang.org/x/net v0.58.0 // indirect
golang.org/x/text v0.41.0 // indirect
)
Loading
Loading