godmode-cli
godmode-cli builds the godmode executable, a Rust-native task graph and development session
manager. It parses commands with Clap, resolves the active repository, delegates domain work to
godmode-core, and renders human-readable, JSON, or command-specific SARIF output.
The CLI is the workspace's user-facing process boundary. Domain state transitions, persistence,
policy evaluation, release logic, and external-tool adapters belong in godmode-core; command
modules under src/commands/ own argument-to-API mapping and output behavior.
Contents
- Build And Install
- Repository Resolution And Global Output
- Quick Start
- Command Reference
- Configuration And State
- Development And Testing
Build And Install
From the workspace root:
cargo build -p godmode-cli
cargo run -p godmode-cli -- --help
Build and install the release binary with the workspace task:
cargo xtask install
godmode --version
cargo xtask install copies target/release/godmode (or the configured Cargo target directory)
to $HOME/.cargo/bin/godmode.
Generate Nushell completions:
godmode completions > godmode.nu
Completion generation is handled before normal Clap parsing and writes the script to standard output.
Repository Resolution And Global Output
Commands start at the current directory, walk upward to the nearest .git, and otherwise use the
current directory. A pinned_root in .ctx/godmode/session.json overrides that detected root;
manage it with godmode pin and godmode unpin.
Global options may appear with any command:
| Option | Behavior |
|---|---|
--json |
Request machine-readable JSON from command handlers that support structured output |
--sarif |
Request SARIF v2.1.0 from verification and review commands |
-h, --help |
Print command help |
-V, --version |
Print the workspace package version |
Errors use miette diagnostics. Template errors retain their typed source labels and help text;
other errors are converted to reports with their context chain. task next and empty dispatch
results use exit code 2 to distinguish a successful empty result from an error (exit code 1).
Quick Start
Create and execute a small dependency chain:
godmode init
godmode task add "Write a failing test" --id t1 --crate-name godmode-core
godmode task add "Implement the behavior" --id t2 --depends-on t1 \
--crate-name godmode-core --run "cargo nextest run -p godmode-core"
godmode task next
godmode task start t1
godmode task done t1 --notes "Contract captured"
godmode task start t2
godmode task run t2 --auto-done
godmode status
The task graph is persisted at .ctx/godmode/tasks.yaml. godmode init creates the expected
global/project state directories and ensures .ctx/ is ignored.
Ingest a plan generated by the writing-plans workflow:
godmode plan ingest docs/plans/2026-05-02-godmode-verify-wave-worktree-ci.md
godmode dispatch --max 5
godmode visualize-graph --format dot --out .ctx/godmode/tasks.dot
Plan headings use ### Task N: Title; optional **Crate**, **Run**, and **Depends-on**
annotations become task fields. Re-ingesting the same source is idempotent, while colliding plans
receive deterministic namespaced IDs.
Command Reference
Run godmode <command> --help for complete argument and flag details.
Sessions And Tasks
| Command | Purpose |
|---|---|
handon [--compact] |
Show session-start triage, running work, runnable work, and blocks |
handoff |
Warn about running tasks and emit session/handoff summaries |
status [--compact] |
Show graph counts and next runnable work |
context |
Emit repository, task, commit, critical-path, and Coursers context |
session prune --older-than N [--dry-run] |
Remove or preview old session JSONL files |
pin [PATH], unpin |
Set or clear the repository root used by the session |
Task operations:
| Command | Purpose |
|---|---|
task list [--priority LEVEL] [--filter TEXT] |
List and filter tasks |
task next [--priority LEVEL] |
List pending tasks whose dependencies are done |
task add TITLE [options] |
Add a task and its execution metadata |
task start ID |
Validate dependencies and mark a pending task running |
task done ID [--commit SHA] [--notes TEXT] |
Complete a running task |
task block ID REASON |
Block a task and retain the reason in notes |
task unblock ID, task unblock-all |
Reset one or all blocked tasks to pending |
task run ID [--auto-done] |
Execute the task's run field through the Rx adapter |
task remove ID |
Remove a task and references to it |
task clear --done|--all |
Remove completed tasks or the whole graph |
task pull [--project NAME] |
Import pending Doob work |
task pull --github [--repo OWNER/REPO] [--label LABEL] |
Import GitHub issues |
task push [--project NAME], task push-done |
Publish local tasks or sync completions to Doob |
task apply NAME [--var KEY=VALUE] |
Resolve and apply a local/global task template |
task list-templates |
List discovered task templates |
Priorities are high, normal, and low. Repeat --tag to attach multiple tags. Omit
--depends-on for a root task; values are comma-delimited when supplied.
Planning, Dispatch, And Parallel Work
| Command | Purpose |
|---|---|
plan ingest PATH |
Parse and atomically persist plan tasks |
dispatch [--max N] |
Emit independent active chains for parallel agents |
dispatch --critical-path |
Emit the longest active dependency chain |
agent dispatch PATH [--max N] |
Ingest a plan and emit its dispatch payload |
wave init --wave N --agents a,b |
Create persisted parallel-agent slot state |
wave status |
Show slot branches, statuses, and commits |
wave done AGENT [--commits a,b] |
Mark a slot complete |
wave block AGENT |
Mark a slot blocked |
wave check |
Fail while any slot remains pending |
worktree add BRANCH [--issue N] |
Create a linked worktree |
worktree remove BRANCH |
Remove a worktree after merge validation |
visualize-graph [--format dot|svg] [--out PATH] |
Render the task graph |
Agents, Skills, Hooks, And Policies
| Family | Actions |
|---|---|
agent |
list, index, dispatch, generate, migrate |
skill |
list, install PATH, uninstall NAME |
hook |
list, log [--tail N], test SCRIPT, migrate, run NAME |
policy |
resolve AGENT [--level], check AGENT TOOL, list, audit [--date] |
review |
self, skills, agents |
Agent generation reads structured definitions from agents/cfg/*.cfg.yaml and prompt text from
agents/prompts/. The skill registry persists globally at
$HOME/.config/godmode/registry.json. Governance policies compose repository policy files and can
return allow, deny, or review decisions; policy audit events are stored under .ctx/godmode/.
Pipelines And Workflows
| Command | Purpose |
|---|---|
pipeline list, pipeline show NAME |
Discover YAML skill pipelines and inspect steps |
pipeline start NAME [--from SKILL] |
Activate a pipeline at a valid entry point |
pipeline next, pipeline skip |
Advance the current step as done or skipped |
pipeline status, pipeline stop |
Inspect or clear active pipeline state |
pipeline run NAME [--from SKILL] [--fail-fast] |
Execute task-backed steps headlessly |
workflow list [--agent NAME] |
List workflow DAGs from agent definitions |
workflow run AGENT WORKFLOW |
Execute runnable command steps in dependency order |
workflow status NAME |
Inspect persisted workflow state |
Pipeline definitions live in pipelines/*.yaml; active state is stored in
.ctx/godmode/pipeline.yaml. Workflow state is stored as
.ctx/godmode/workflow-<name>.json and includes a definition hash for safe resumption.
Quality, Evaluation, And Releases
| Family | Actions |
|---|---|
verify [--crate-name NAME] |
Run quality gates and inspect recent commit history |
eval |
run, compare, promote, and status bounded skill evaluations |
release |
current, bump [--version], tag, push, changelog, validate |
ci triage [--run-id ID] |
Fetch and classify a failed GitHub Actions run |
doctor |
Check required tools, 1Password authentication, and worktrees |
eval run consumes a skill's evals/evals.json plus a deterministic results fixture and enforces
repeat, case-count, and dollar-cost bounds. Stored runs and promoted baselines live under
.ctx/godmode/evaluations/<skill>/.
Repository And Reporting Utilities
| Family | Actions |
|---|---|
issue |
list, close, and preview/apply sync-todos |
graph build |
Construct a graph interactively or from YAML with --var substitutions |
memory-banking |
inject, remind, init, status |
insight |
add, list [--date], render [--date] |
init |
Initialize global config and local state |
scaffold CRATE DIMENSION |
Generate a test module stub |
test-check PATH |
Check whether a Rust source file has associated tests |
Valid scaffold dimensions are unit, property, fuzz, conformance, integration, and
regression.
Configuration And State
Configuration precedence is repository .godmode.toml, global
$HOME/.config/godmode/config.toml, then defaults. The TOML model contains an optional project
name, integration toggles (doob, hj, crux, rx, crs), and handoff settings.
Frequently used state paths:
| Path | Content |
|---|---|
.ctx/godmode/tasks.yaml |
Task graph and plan-import mappings |
.ctx/godmode/session.json |
Session metadata and optional pinned root |
.ctx/godmode/sessions/ |
Task trace and session summary JSONL files |
.ctx/godmode/pipeline.yaml |
Active pipeline state |
.ctx/godmode/wave-status.json |
Parallel wave slots |
.ctx/godmode/reports/ |
Generated report artifacts |
Development And Testing
From the workspace root:
cargo check -p godmode-cli
cargo clippy -p godmode-cli --all-targets -- -D warnings
cargo nextest run -p godmode-cli
cargo run -p godmode-cli -- --help
cargo run -p godmode-cli -- task --help
Command integration tests under crates/godmode-cli/tests/ cover plan ingestion, Doob publishing,
pipeline entry points, task metadata and priority filtering, and graph visualization. For the full
workspace contract, including plugin structure and serialization behavior, run:
cargo xtask ci
When adding a command, update the Clap enum and the corresponding module in src/commands/, route
it through commands::dispatch, support structured output where applicable, and add parser or
process-level coverage. Keep business rules in godmode-core rather than command handlers.