Geordi

Geordi is the builder workflow for goal-driven coding work. It combines build-pipeline discipline - context first, implementation second, independent verification, retries, and receipts - with an installable CLI that can run bounded missions through Codex, Droid, Cursor Agent, or Claude Code.

The machinery is intentionally plain: define a goal, add missions, run one runtime at a time, verify with real commands, and leave logs behind. Less mysticism. More receipts.

What Geordi does

• Defines a goal: the operator outcome.
• Breaks work into missions: bounded implementation units with acceptance checks.
• Loads project context before building.
• Prepends the shared global AGENTS.md context before every mission prompt.
• Runs missions through Codex, Droid, Cursor, or Claude Code.
• Keeps state in .geordi/state/ so runs can be resumed or audited.
• Separates implementation from verification.
• Captures receipts: prompts, command logs, verification logs, and git status before/after.

Install

From the source repo:

git clone https://github.com/OWNER/REPO.git /tmp/geordi-source
bash /tmp/geordi-source/geordi/install.sh

Or one line, pinned to the public release. Set GEORDI_TARBALL_URL to the matching source archive so streamed installs can locate the bundle:

GEORDI_TARBALL_URL=https://codeload.github.com/OWNER/REPO/tar.gz/refs/tags/v1.2.0 \
  bash <(curl -fsSL https://raw.githubusercontent.com/OWNER/REPO/v1.2.0/geordi/install.sh)

The installer copies the bundle into ~/.geordi, creates ~/.local/bin/geordi, and prints a verification command.

Quick start

cd /path/to/repo
geordi init --goal "Ship dark mode settings" --mode codex
geordi mission add "Add settings toggle" --accept "npm test"
geordi run --mode codex
geordi status

Pick any of the four supported runtimes. Use --model MODEL_ID where the runtime supports it (Codex, Droid, Cursor, Claude).

Global AGENTS context

Geordi requires a global AGENTS.md file by default. This keeps mission runs aligned with the operator's shared agent rules before project-specific context is applied.

Default path:

~/.agents/AGENTS.md

Override when needed:

GEORDI_AGENTS_FILE=/path/to/AGENTS.md geordi run --mode codex

To intentionally run without a global file:

GEORDI_REQUIRE_AGENTS=0 geordi run --mode codex

geordi doctor checks the global file unless GEORDI_REQUIRE_AGENTS=0 is set.

Project-local defaults can live in .geordi.env:

GEORDI_CODEX_ARGS="exec --full-auto"
GEORDI_DROID_AUTO="medium"
GEORDI_CURSOR_ARGS="-p --trust --output-format text"
GEORDI_CLAUDE_ARGS="-p --dangerously-skip-permissions --output-format text"

Mission contract

Each mission should include:

• Title - what to change.
• Acceptance command - what proves it worked.
• Scope note - what not to touch, if relevant.

Example:

geordi mission add \
  "Add CSV export to reports page" \
  --accept "npm run test:unit -- reports" \
  --scope "Only reports UI and export helper files. Do not modify auth."

Good missions are small enough to verify in one command. If a mission needs five unrelated acceptance commands, split it.

Runtime modes

Geordi dispatches missions to one of four supported runtimes. Pick the one that fits the task and the model you want to use.

Codex mode

Uses codex exec from the current git repository, with optional --model.

Good for:

• feature builds
• refactors
• tests and type fixes
• PR review follow-up

Default command shape:

codex exec --full-auto "<mission prompt>"

With --model:

codex exec --full-auto --model "$MODEL" "<mission prompt>"

Override with:

GEORDI_CODEX_ARGS="exec --full-auto" geordi run --mode codex --model "gpt-5"

cd /path/to/repo
geordi init --goal "Ship dark mode settings" --mode codex
geordi mission add "Add settings toggle" --accept "npm test"
geordi run --mode codex --model "gpt-5"

Droid mode

Uses droid exec with optional --model and --auto settings.

Good for:

• BYOK model routing
• custom OpenAI-compatible endpoints
• Droid mission-style coding passes
• UI/code tasks where Droid is already configured

Default command shape:

droid exec --auto medium --cwd "$PWD" -m "$MODEL" "<mission prompt>"

Override with:

GEORDI_DROID_AUTO=low geordi run --mode droid --model "custom:Your-Model-0"

cd /path/to/repo
geordi init --goal "Fix checkout form validation" --mode droid
geordi mission add "Repair validation and errors" --accept "npm test"
geordi run --mode droid --model "custom:Your-Model-0"

Cursor mode

Uses the cursor-agent CLI in headless print mode.

Good for:

• Cursor editor users who want the same agent in a terminal
• repos where Cursor's model routing is already configured
• UI/code tasks where Cursor's editor-aware context is useful

Default command shape:

cursor-agent -p --trust --output-format text --model "$MODEL" "<mission prompt>"

-p runs Cursor in headless print mode. --trust auto-accepts the workspace trust dialog so the run is non-interactive. --output-format text produces a clean text receipt for the log file.

Override with:

GEORDI_CURSOR_ARGS="-p --trust --output-format stream-json" geordi run --mode cursor --model "gpt-5"

cd /path/to/repo
geordi init --goal "Refactor settings panel into shared component" --mode cursor
geordi mission add "Extract SettingsPanel and add unit tests" --accept "npm test -- settings"
geordi run --mode cursor --model "gpt-5"

Claude Code mode

Uses the claude CLI in non-interactive print mode.

Good for:

• Claude-Code-native repos with a CLAUDE.md or .claude/ config
• missions that benefit from Claude's instruction-following and tool use
• sandboxes where you need a self-contained, non-interactive agent

Default command shape:

claude -p --dangerously-skip-permissions --output-format text --model "$MODEL" "<mission prompt>"

-p runs Claude in non-interactive print mode. --dangerously-skip-permissions is intended for sandboxed/headless runs where the agent should not be blocked on permission prompts. --output-format text produces a clean text receipt for the log file.

Override with:

GEORDI_CLAUDE_ARGS="-p --permission-mode bypassPermissions --output-format text" geordi run --mode claude --model "sonnet"

cd /path/to/repo
geordi init --goal "Add OAuth refresh-token rotation" --mode claude
geordi mission add "Implement refresh-token rotation and tests" --accept "npm test -- auth"
geordi run --mode claude --model "sonnet"

Choosing a mode

If a runtime is missing, install it and re-run geordi doctor. The CLI does not bundle any of these agents. Cursor can also fail in unattended shells when its OS credential store is locked or no login exists; run a one-time interactive Cursor Agent login, then retry.

Context-first build loop

The core build-pipeline rule remains: load context before implementation.

Before running a non-trivial mission, collect:

1. AGENTS.md, CLAUDE.md, or other repo agent instructions.
2. Relevant PRD/story/task text.
3. Existing test/build commands.
4. Recent git status and nearby code conventions.
5. Explicit scope exclusions.

The bundled helper scripts can support this pattern:

~/.geordi/scripts/load-context.sh /path/to/repo
~/.geordi/scripts/update-context.sh /path/to/repo "Added CSV export with unit tests; npm test passes."

If those scripts do not match a repo, do the same manually and put the important context directly into the mission title/scope.

State layout

Inside the target repo:

.geordi/
  goal.md
  missions.jsonl
  state/
    run-YYYYmmdd-HHMMSS/
      mission-001.prompt.md
      mission-001.log
      mission-001.verify.log
      git-before.txt
      git-after.txt
      summary.md

Operator rules

1. Do not run open-ended prompts when a mission can be bounded.
2. Do not count agent completion as success; run the acceptance command.
3. Do not hide failures. Preserve the log and make the next mission smaller.
4. Do not put secrets in missions, prompts, or logs.
5. Read repo instructions before changing code.
6. Commit only after verification passes and scope is reviewed.
7. If verification fails, retry with the exact failure log and a smaller repair mission.

When to use Geordi

Use Geordi when the work is larger than a single prompt but smaller than a full project-management system:

• Build a feature across a few files.
• Convert a PRD into a sequence of agent missions.
• Run the same mission through Codex, Droid, Cursor, or Claude Code and compare results.
• Keep receipts for agent work without building a control plane.
• Continue the former build-pipeline workflow under the shorter geordi name.

Do not use Geordi for:

• one-line edits where a normal direct change is cleaner
• destructive repo rewrites without explicit operator approval
• secrets, credentials, payment flows, or private data entry
• unbounded "go improve the whole codebase" prompts

Verification

geordi doctor

Checks:

• bundle installed
• target directory is a git repo
• requested runtime exists (codex, droid, cursor-agent, or claude; --mode cursor checks cursor-agent)
• mission file is parseable
• acceptance command is available for each mission

To check a specific runtime:

geordi doctor --mode codex
geordi doctor --mode cursor
geordi doctor --mode claude

Common pitfalls

1. Running the agent before reading repo instructions. Always load context first.
2. Over-wide missions. Split broad PRD stories into smaller missions with one acceptance command each.
3. Treating agent success as real success. The acceptance command is the proof.
4. Committing generated dirt. Review git status --short before committing.
5. Leaking private environment details. Keep model IDs, internal hosts, private paths, and secrets out of public missions and docs.
6. Forgetting to install the runtime. cursor-agent is a separate package from the Cursor editor; install it from the Cursor docs before using --mode cursor.
7. Locked Cursor credentials. If cursor-agent exists but fails before the prompt runs, unlock the OS credential store or refresh Cursor Agent login interactively.
8. Windows shell mismatch. Use WSL or Git Bash for the installer and tarball extraction; PowerShell needs an equivalent manual download/copy flow.

Verification checklist

• geordi --version prints the expected version.
• geordi doctor passes inside a git repo.
• geordi init creates .geordi/goal.md and .geordi/missions.jsonl.
• geordi mission add appends valid JSONL.
• geordi run writes prompt/log/verification receipts.
• Acceptance command output is preserved in .geordi/state/*/*.verify.log.
• The chosen runtime (codex, droid, cursor-agent, or claude) is on PATH before geordi run.