Goal
Make qmax-code work as a standalone terminal agent without requiring the qmax CLI binary. Any QualityMax account holder can install and use it directly.
Current Problem
- Users must install both
qmax CLI and qmax-code
- Auth depends on
~/.qamax/config.json (created by qmax login)
- All tools shell out to
qmax binary (exec.Command("qmax", "crawl", "start"))
- If qmax CLI isn't installed, qmax-code is useless
Target
- Single binary install:
curl -sL https://get.qualitymax.io/code | sh
- Browser-based auth:
qmax-code login opens browser, OAuth flow
- Direct API calls: HTTP client calls QualityMax REST API (no shelling out)
- qmax CLI becomes optional
What to Build
1. Browser-based Login
qmax-code login opens browser to app.qualitymax.io/auth/cli-login
- CLI polls
/api/auth/cli-poll?code=XXX until user approves
- Stores token in
~/.qmax-code/auth.json
- Alternative:
qmax-code login --api-key qm-...
2. Direct API Client (api_client.go)
- HTTP client calling QualityMax REST API
- Methods: ListProjects, StartCrawl, GetCrawlStatus, ListScripts, RunTest, etc.
- Uses stored token for Authorization header
3. Tools Refactor (tools.go)
- Replace
exec.Command("qmax", ...) with apiClient.Method()
- Same tool names, same parameters, different implementation
- Fallback to qmax CLI if available (backward compat)
4. Backend Endpoints (qamax-rag-app)
POST /api/auth/cli-login — generate auth code
GET /api/auth/cli-poll — poll for auth result
POST /api/auth/cli-authorize — authorize code for current user
5. First-Run Experience
Welcome to qmax-code!
To get started, run:
qmax-code login
Or set your API key:
export QUALITYMAX_API_KEY=qm-...
Files to Change
| File |
Change |
| auth.go (NEW) |
Browser login, token storage |
| api_client.go (NEW) |
Direct HTTP client |
| tools.go |
API calls instead of exec |
| context.go |
Load auth from ~/.qmax-code/auth.json |
| main.go |
Add login command, first-run UX |
| README.md |
Updated setup instructions |
Implementation Order
- auth.go + backend endpoints
- api_client.go
- tools.go refactor
- README + install script
- Build + release binaries
Goal
Make qmax-code work as a standalone terminal agent without requiring the qmax CLI binary. Any QualityMax account holder can install and use it directly.
Current Problem
qmaxCLI andqmax-code~/.qamax/config.json(created byqmax login)qmaxbinary (exec.Command("qmax", "crawl", "start"))Target
curl -sL https://get.qualitymax.io/code | shqmax-code loginopens browser, OAuth flowWhat to Build
1. Browser-based Login
qmax-code loginopens browser toapp.qualitymax.io/auth/cli-login/api/auth/cli-poll?code=XXXuntil user approves~/.qmax-code/auth.jsonqmax-code login --api-key qm-...2. Direct API Client (
api_client.go)3. Tools Refactor (
tools.go)exec.Command("qmax", ...)withapiClient.Method()4. Backend Endpoints (qamax-rag-app)
POST /api/auth/cli-login— generate auth codeGET /api/auth/cli-poll— poll for auth resultPOST /api/auth/cli-authorize— authorize code for current user5. First-Run Experience
Files to Change
Implementation Order