get-shit-done-codex (Codex CLI/Desktop)

A meta-prompting, context engineering and spec-driven development system for OpenAI Codex, including both CLI and Desktop.

Fork of get-shit-done by TÂCHES, adapted for Codex CLI by undeemed.

Caution

Codex is now supported upstream. This fork remains focused on Codex-specific UX, compatibility, and experimental features for personal use.

What This Does

GSD solves context rot — the quality degradation that happens as AI fills its context window. It structures your project through specs and plans so each task runs in a fresh context with exactly what it needs. No accumulated garbage, no forgotten requirements.

graph TB
  subgraph codex["GSD-Codex"]
    direction TB
    A["AGENTS.md<br/><i>behavior contract</i>"] --> O["Thin Orchestrator<br/><i>30-40% context</i>"]
    C[".codex/config.toml<br/><i>agent roles + flags</i>"] --> O
    O -->|"spawn"| S1["gsd-planner<br/><i>fresh 200k context</i>"]
    O -->|"spawn"| S2["gsd-executor<br/><i>fresh 200k context</i>"]
    O -->|"spawn"| S3["gsd-verifier<br/><i>fresh 200k context</i>"]
    S1 -.->|"agents/gsd-planner.md<br/>loaded at spawn"| D1["700+ line<br/>role definition"]
    S2 -.->|"agents/gsd-executor.md"| D2["700+ line<br/>role definition"]
    S3 -.->|"agents/gsd-verifier.md"| D3["700+ line<br/>role definition"]
  end

  style codex fill:#1a1a2e,stroke:#00d4ff,color:#e0e0e0
  style A fill:#0d2137,stroke:#00d4ff,color:#e0e0e0
  style C fill:#0d2137,stroke:#00d4ff,color:#e0e0e0
  style O fill:#162447,stroke:#00d4ff,color:#e0e0e0
  style S1 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style S2 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style S3 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style D1 fill:#0d2137,stroke:#444,color:#999
  style D2 fill:#0d2137,stroke:#444,color:#999
  style D3 fill:#0d2137,stroke:#444,color:#999

Loading

What Changed In This Fork

• AGENTS-first for Codex: AGENTS.md is the primary behavior contract. Agent.md > Skills.md
• Native skills: all commands use $gsd-* skill notation — no prompt aliases needed.
• Full config distribution: installer ships .codex/config.toml (multi-agent, feature flags, MCP servers) and 11 rich agents/*.md sub-agent definitions — everything needed for multi-agent orchestration out of the box.
• Sub-agent linking: each agent role in config.toml uses developer_instructions to load its full role definition from agents/gsd-*.md at runtime — no manual wiring needed.
• Overwrite protection: config.toml is never overwritten on reinstall. AGENTS.md prompts for confirmation on global installs.
• Installer integrity checks: --verify audits AGENTS.md, config.toml, agent definitions, command surfaces, and version metadata. --repair restores missing artifacts.
• One-click trust: Codex prompts to trust the project on first run so the config takes effect.

Installation

npx @undeemed/get-shit-done-codex@latest

You can install globally (~/.codex/) or locally (./).

Recommended

npx @undeemed/get-shit-done-codex --global

npx @undeemed/get-shit-done-codex --global   # Install to ~/.codex/
npx @undeemed/get-shit-done-codex --local    # Install to current directory
npx @undeemed/get-shit-done-codex --path .   # Install to a specific directory
npx @undeemed/get-shit-done-codex --global --migrate             # Clean up legacy prompts/
npx @undeemed/get-shit-done-codex --verify --global              # Check install integrity
npx @undeemed/get-shit-done-codex --verify --repair --global     # Auto-repair

After installation, run codex (CLI) or codex app (Desktop), then run $gsd-help.

What Gets Installed

The installer distributes everything GSD needs:

• AGENTS.md — behavior contract and command reference for Codex
• .codex/config.toml — multi-agent mode, feature flags, agent role registry, MCP servers
• agents/gsd-*.md — rich agent definitions (700+ lines each) for sub-agent orchestration
• skills/gsd-*/SKILL.md — native Codex skill commands
• get-shit-done/ — workflow files, templates, and references

On first run, Codex may prompt you to trust the project so the config takes effect (one-time, one-click).

Note

.codex/config.toml is non-destructive — the installer skips it if you already have one, so your customizations are preserved on updates.

Installed File Structure

~/.codex/
├── AGENTS.md
├── .codex/config.toml
├── agents/gsd-*.md
├── skills/gsd-*/SKILL.md
└── get-shit-done/

For local installs, replace ~/.codex/ with ./.

Verify And Repair

• --verify: checks AGENTS.md, config.toml, agent definitions, command surfaces, workflow assets, and version metadata.
• --verify --repair: reinstalls missing/broken artifacts and verifies again.
• Migration is detect-then-confirm, not automatic:
  • Interactive install asks before removing legacy surface files
  • Non-interactive install skips cleanup unless --migrate is passed
  • --skip-migrate keeps legacy files explicitly

AGENTS-First Reliability

This fork is intentionally AGENTS.md-first for Codex reliability:

• AGENTS.md is the source of truth for behavior and workflow constraints
• $gsd-* skills are lightweight command wrappers around the same workflow docs

Staying Updated

# Check for updates from inside Codex
$gsd-update

# Update from terminal
npx @undeemed/get-shit-done-codex@latest --global

The installer writes a get-shit-done/VERSION file so $gsd-update can detect installed vs latest and show changelog before updating.

npm Trusted Publisher (OIDC)

This repo includes a GitHub Actions publish workflow at:

• .github/workflows/publish.yml

When setting up npm Trusted Publisher for this package, use:

• Publisher: GitHub Actions
• Organization or user: undeemed
• Repository: get-shit-done-codex
• Workflow filename: publish.yml
• Environment name: leave blank (unless you later bind this workflow to a specific GitHub Environment)

Quick Start

# 1. Initialize project (questions → research → requirements → roadmap)
$gsd-new-project

# 2. Plan the first phase
$gsd-plan-phase 1

# 3. Execute the phase
$gsd-execute-phase 1

# 4. Verify it works
$gsd-verify-work 1

How It Works

1. Initialize Project

$gsd-new-project

One command takes you from idea to ready-for-planning:

• Deep questioning to understand what you're building
• Optional domain research (spawns 4 parallel researcher agents)
• Requirements definition with v1/v2/out-of-scope scoping
• Roadmap creation with phase breakdown

Creates: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, .planning/research/

2. Plan Phase

$gsd-plan-phase 1

The system researches how to implement the phase, creates 2-3 atomic task plans, and verifies them against requirements.

Creates: {phase}-RESEARCH.md, {phase}-{N}-PLAN.md

3. Execute Phase

$gsd-execute-phase 1

Runs all plans in parallel waves. Each plan executes in a fresh 200k context window. Every task gets its own atomic commit.

Creates: {phase}-{N}-SUMMARY.md, {phase}-VERIFICATION.md

4. Verify Work

$gsd-verify-work 1

Manual user acceptance testing. The system walks you through testable deliverables and creates fix plans if issues are found.

Commands

Command	Description
$gsd-new-project	Initialize project: questions → research → requirements → roadmap
$gsd-plan-phase [N]	Research + plan + verify for a phase
$gsd-execute-phase <N>	Execute all plans in parallel waves
$gsd-verify-work [N]	Manual user acceptance testing
$gsd-help	Show all commands

Why It Works

Context Engineering

GSD maintains structured context files that stay within quality limits:

• PROJECT.md — Project vision, always loaded
• REQUIREMENTS.md — Scoped v1/v2 requirements with phase traceability
• ROADMAP.md — Where you're going, what's done
• STATE.md — Decisions, blockers, position — memory across sessions
• PLAN.md — Atomic task with XML structure, verification steps
• SUMMARY.md — What happened, committed to history

Multi-Agent Orchestration

Every stage uses a thin orchestrator that spawns specialized agents:

• Research — 4 parallel researchers investigate stack, features, architecture, pitfalls
• Planning — Planner creates plans, checker verifies, loops until pass
• Execution — Executors implement in parallel, each with fresh 200k context
• Verification — Verifier checks codebase against goals, debuggers diagnose failures

The orchestrator stays at 30-40% context. The work happens in fresh subagent contexts.

Sub-Agent Roles

GSD ships 11 specialized agent definitions in agents/gsd-*.md, each wired into config.toml via developer_instructions:

Agent	Role
gsd-planner	Draft atomic PLAN.md files with tasks and success criteria
gsd-executor	Execute plans with atomic commits and verification
gsd-verifier	Goal-backward verification that outcomes are delivered
gsd-debugger	Hypothesis testing, root cause isolation, fix proposals
gsd-phase-researcher	Research implementation patterns for planners
gsd-project-researcher	Ecosystem research for roadmap creation
gsd-research-synthesizer	Synthesize parallel research into actionable inputs
gsd-plan-checker	Stress-test plan quality and requirement coverage
gsd-codebase-mapper	Map stack, architecture, and conventions
gsd-roadmapper	Turn requirements into phased roadmaps
gsd-integration-checker	Verify cross-phase wiring and e2e behavior

Each agent gets its full role definition (700+ lines) loaded at spawn time — no context wasted on the orchestrator.

Atomic Git Commits

Each task gets its own commit immediately after completion:

feat(01-01): implement user authentication
feat(01-01): add password hashing
docs(01-01): complete auth-setup plan

Git bisect finds exact failing task. Each task independently revertable.

Troubleshooting

Commands not found?

• Restart Codex to reload installed command surfaces
• Check ~/.codex/skills/gsd-*/SKILL.md (global) or ./skills/gsd-*/SKILL.md (local)

Multi-agent / sub-agents not working?

• Check .codex/config.toml exists in your install directory
• Ensure the project is trusted in Codex (it prompts on first run)
• Run --verify to check all artifacts are present

Update to latest:

npx @undeemed/get-shit-done-codex@latest

Can users be notified when an update is available?

• Yes. The installer prints an update notice if a newer npm version exists.
• In-Codex update checks are available via $gsd-update.
• For release notifications outside the CLI, enable GitHub release watching on this repo.

More Documentation

For deeper guides, detailed workflows, and comprehensive documentation, see the original get-shit-done README.

The original repository contains:

• Detailed workflow explanations
• Advanced usage patterns
• Complete command reference
• Best practices and examples
• Architecture and design principles

Note: The original README is written for Codex Code. When following it, remember that this fork uses:

• Codex-native skills ($gsd-*)
• OpenAI Codex CLI & Desktop

Keywords

get-shit-done gsd openai codex codex-cli codex-desktop codex-app openai-codex ai ai-coding ai-agents meta-prompting context-engineering context-rot spec-driven-development prompt-engineering multi-agent subagent ai-workflow developer-tools dev-tools productivity code-generation

Credits

Original project by TÂCHES. This fork adapts it for Codex CLI.

License

MIT