Quickstart
Run these commands in any Python project with git initialized.
After gradez install, Gradez offers a one-time interactive setup for provider, model, and API key (or skip and use flags). Run gradez configure anytime to update saved settings.
CLI reference
| Command | Description | Common flags |
|---|---|---|
gradez install | Install Gradez rules or skills into a coding host. | cursor, claude-code, --no-setup |
gradez configure | Set up or update LLM provider, model, and API key. | none |
gradez models | List recommended models for a provider. | --provider |
gradez doctor | Check whether your environment is ready. | cursor, claude-code |
gradez dashboard | Start the live dashboard on localhost. | --port, --no-browser |
gradez upgrade | Check PyPI for a newer Gradez release. | none |
gradez discover | Analyze the repo and capture a baseline score (Python or Node). | --provider, --model, --api-key |
gradez optimize | Run the parallel optimization loop. | --subagents, --budget, --stall |
gradez stats | Show analytics, token usage, cost estimate; export JSON or CSV. | --json, --csv, --run-id |
gradez traces | View experiment trace timeline. | --experiment, --json |
gradez report | Export a shareable HTML run report. | --output, --run-id |
gradez history | List recent optimization runs. | --limit |
Provider setup
Use CLI flags for a quick start, run gradez configure for interactive setup, or store defaults in ~/.gradez/config.toml.
Groq
Recommended free cloud provider. Fast inference and no local setup.
OpenRouter
Try Gradez with free-tier models using one API key. Best for testing discover.
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.
- 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.
Host plugins
Gradez works directly from the CLI, but it can also install guidance into coding hosts.
| Host | Install command | What it adds |
|---|---|---|
| Cursor | gradez install cursor | Project rules in .cursor/rules/. |
| Claude Code | gradez install claude-code | Discover and optimize skill files. |