$ gimbal run --help
Available Commands:
implement Implement works through supplied outcomes until each is demonstrated.
pyramid-summary PyramidSummary writes and validates every derived compression of a largest document.
research-document ResearchDocument produces a research-backed document within a token budget.
research-eval ResearchEval measures research candidates and checks a frozen choice on holdout.
review Review asks one reviewer to inspect the repository read-only and record its findings.
sprint-plan SprintPlan prepares an indexed working set and a reference-backed implementation plan.
validate-product ValidateProduct runs user workloads, checks their screenshots, and triages findings.gimbal run WORKFLOW --help is the full invocation reference. Explore each workflow below with the same interactive viewer as the Gimbal console. Click steps to read their prompts, context shapes, and Go source; expand groups to follow loops and parallel work. Open the full view for more room. These views describe workflow source, not a running execution.
review
One reviewer inspects a repository read-only and returns a list of concrete correctness findings. The whole workflow is about ten lines, which makes it the one to read first.
gimbal run review --goal "Find correctness bugs in the retry logic"sprint-plan
Starts from a local intent file naming the stakeholder outcome, constraints, and useful references. Project and prior-art research feed an indexed working set; three independent planning lanes draft, critique, and synthesize a proposed plan. A successful run means the working set and plan.md exist. It does not implement or validate the outcome.
gimbal run sprint-plan --intent ./intent.md --sprint-dir ./ephemeral/sprints/nextvalidate-product
Runs up to three prepared user workloads concurrently, records their browser sessions, asks each tester for a structured UX debrief, checks the screenshots, and synthesizes actionable findings. It is practical user testing—not source review or an exhaustive feature checklist.
gimbal run validate-product --suite-file /abs/user-testing.yamlimplement
Works through an ordered list of outcomes. For each outcome, a planner chooses bounded assignments, a coding agent implements them under a scope coach, and an independent validator judges the outcome. It is designed to advance at 90–95% completion when only small gaps remain, but a recorded run accepted incomplete outcome work. It never commits, pushes, or merges.
gimbal run implement --outcomes-file ./outcomes.json --max-tasks-per-outcome 3Primitives used: promise loop, supervision, scoped context, Check.
research-document
Researches a subject into a local semantic index, writes a document within a token budget, and revises it until an independent editor finds only nitpicks. A planner returns five groups of topics, one per parallel researcher; each leaves local source files and an index that cites them.
gimbal run research-document --goal "Explain passkeys to security-conscious product managers" --research-dir ./passkeys-research --output ./passkeys.md --token-budget 4000research-eval
Runs bounded research-document trials against a fixed local-source suite, assesses document and index quality, then checks a frozen model choice on a held-out case. It reports quality, retrieval, repairs, and cost. The bundled fictional suite does not establish open-web quality or a general model success rate. This workflow requires a hosted project run with --work-dir equal to --project.
gimbal run research-eval --project /path/project --work-dir /path/project --output-dir /tmp/research-eval-1 --max-trials 3pyramid-summary
Compresses one validated document into a pyramid of summaries, halving the token budget at each level until the next would be under 100 tokens. Six authors write levels in parallel; one editor then reads every level together for fidelity and useful compression. Its author and editor roles can use different harnesses through the role flags shown in --help.
gimbal run pyramid-summary --goal "Explain passkeys to security-conscious product managers" --semantic-index ./passkeys-research/INDEX.md --largest-document ./passkeys.md --output-dir ./passkeys-pyramidFlags every workflow has
| Flag | Meaning |
|---|---|
--project | The repository admitted to the running Gimbal instance. Its .gimbal holds the run. |
--work-dir | The execution directory; defaults to the owning project. |
--instance-dir | Select a running instance when using a non-default state directory. |
--follow | Wait for the hosted run’s terminal success or failure; without it, the run continues after the client exits. |
--conversation | Associate the run with a project conversation. |
--ROLE | One per role the workflow names, as model or model:effort. Defaults come from one shared file. |
--port, --uds, and --no-web configure the instance when starting gimbal, not a gimbal run command.