Planning & Execution

For complex tasks, Gee-Code breaks work into structured plans — either simple todo lists for linear tasks, or beads (dependency graphs) for parallel, multi-agent execution.

Simple Planning (Todos)

For straightforward multi-step work, the AI uses a visible todo list:

> Refactor the login system to use OAuth

Creating todo list:
- [ ] Research OAuth providers
- [x] Update user model for OAuth tokens
- [ ] Implement OAuth callback endpoint
- [ ] Update login UI
- [ ] Write tests

The AI tracks progress in real time. You can see what’s in progress and what’s done.

Advanced Planning (Beads)

For complex tasks that benefit from parallelism and multi-agent execution, Gee-Code creates a bead plan — a directed acyclic graph (DAG) of tasks:

/plan Add user authentication

This generates a plan like:

gc-a1b2: Design auth schema      [architect]
gc-a1b3: Implement login API      [code]       depends: gc-a1b2
gc-a1b4: Write auth tests         [test]       depends: gc-a1b3
gc-a1b5: Update documentation     [docs]       depends: gc-a1b4

Bead Lifecycle

PROPOSED  -->  APPROVED  -->  IN_PROGRESS  -->  DONE
                                    |              |
                                    +-- BLOCKED    +-- FAILED

Status	Description
PROPOSED	AI proposed, awaiting your approval
APPROVED	You approved, ready for execution
IN_PROGRESS	Currently being executed by an agent
BLOCKED	Waiting on dependencies to complete
DONE	Completed successfully
FAILED	Execution failed

Approve and Execute

/beads                    # View the task graph
/beads approve            # Approve proposed beads
/run                      # Execute (parallel by default)
/run --fg                 # Execute in foreground (blocking)

Parallel Execution

Beads without dependency conflicts run in parallel. The executor:

1. Finds all ready beads (approved + dependencies met)
2. Groups them into parallel waves
3. Executes each wave concurrently
4. Moves to the next wave when the current completes

Wave 1: gc-a1b2 (Design) ──────┐
                                ├──> Wave 2: gc-a1b4 (Tests) ──> Wave 3: gc-a1b5 (Docs)
Wave 1: gc-a1b3 (Implement) ───┘

Design and Implement run in parallel (Wave 1). Tests wait for both. Docs waits for Tests.

Agent Assignment

Each bead can be assigned to a specific agent archetype:

• architect — design and planning
• code — implementation
• test — testing
• review — code review
• explore — research and investigation

If no agent is specified, the current session agent handles it.

Hierarchical Beads

Complex beads can be broken into subtasks:

gc-a1b2: "Build auth system" (parent)
├── gc-a1b2.1: "Design database schema"
├── gc-a1b2.2: "Implement API endpoints"
└── gc-a1b2.3: "Add middleware"

Child beads inherit context from their parent and results roll up.

Todos vs Beads

Feature	Todos	Beads
Scope	3-7 steps for current task	Full project decomposition
Dependencies	Linear (sequential)	DAG (parallel + dependencies)
Agents	Current agent only	Multiple agent types
Approval	None required	User must approve
Execution	Manual progress tracking	Automated parallel execution

For simple tasks, todos are sufficient. For complex multi-step work that benefits from parallelism and agent specialization, use beads.

Plan Persistence

Plans are saved in two locations:

1. Continuity ledger — in-session reference that survives compaction
2. .gee/plans/ — durable snapshots that survive session restarts

You can resume an in-progress plan even after closing and reopening Gee-Code.

Commands

Command	Description
/plan <task>	Generate a plan (todos or beads)
/beads	View current task graph
/beads approve	Approve proposed beads
/run	Execute approved beads (parallel)
/run --fg	Execute in foreground
/parallel	Execute multiple beads in parallel
/cancel	Cancel running execution
/todo	View the todo list

Next Steps

• Flights & Swarms — parallel agent orchestration
• Agents & Delegation — agent types and delegation
• RLM — recursive execution for complex computation