Quickstart
Run these commands in any Python project with git initialized.
pip install gradex
gradex install cursor
gradex discover "make the parser faster" --provider groq --api-key <key>
gradex optimize --provider groq --api-key <key>
gradex dashboard
CLI reference
| Command | Description | Common flags |
|---|---|---|
gradex install | Install GradeX rules or skills into a coding host. | cursor, claude-code |
gradex doctor | Check whether your environment is ready. | cursor, claude-code |
gradex dashboard | Start the live dashboard on localhost. | --port, --no-browser |
gradex upgrade | Check PyPI for a newer GradeX release. | none |
gradex discover | Analyze the repo and capture a baseline score. | --provider, --model, --api-key |
gradex optimize | Run the parallel optimization loop. | --subagents, --budget, --stall |
gradex stats | Show analytics for a run and export JSON or CSV. | --json, --csv, --run-id |
gradex history | List recent optimization runs. | --limit |
Provider setup
Use CLI flags for a quick start or store defaults in ~/.gradex/config.toml.
[llm]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key = "gsk_..."
# Other providers: anthropic, openai, ollama
Groq
Recommended free cloud provider. Fast inference and no local setup.
Ollama
Fully local. Run ollama serve and pull a model before starting.
Anthropic
Use Claude models when you need deeper code reasoning.
OpenAI
Use GPT models through the OpenAI-compatible path.
Dashboard
The dashboard gives you trust while the optimizer runs: latest run, experiments, pass rate, score chart, and trace logs.
gradex dashboard
# Open http://127.0.0.1:8080
- Experiment table shows status, score, delta from baseline, and gate result.
- Score chart plots only passed experiments.
- Analytics cards show pass rate, improvement, best score, and duration.
Analytics
Use stats and history to inspect run quality, export data, and prove that changes improved real metrics.
gradex stats
gradex stats --json run.json --csv run.csv
gradex history --limit 20
Host plugins
GradeX works directly from the CLI, but it can also install guidance into coding hosts.
| Host | Install command | What it adds |
|---|---|---|
| Cursor | gradex install cursor | Project rules in .cursor/rules/. |
| Claude Code | gradex install claude-code | Discover and optimize skill files. |