Nelson Muntz

Plan-based iterative development loops for OpenCode. Create structured plans, execute tasks automatically, and commit progress as you go.

Why "Nelson Muntz"? Named after the Simpsons character. Inspired by the Ralph Wiggum technique. Ha-ha!

What is Nelson?

Nelson is a development plugin that combines structured planning with automated execution. Create a plan with tasks, then let Nelson work through them one by one, committing progress after each task.

The plugin listens for OpenCode's session.idle event to continue work automatically, creating a feedback loop where the AI iteratively builds on its own work.

Core Workflow

# Create a plan through conversation:
nm-plan name="my-api"

# Work through tasks automatically:
nm-start

# Loop works through tasks one by one
# Stops when: all tasks marked [x] OR maxIterations reached

Installation

Note: This plugin has been primarily tested with Anthropic models (Claude) and works best with them.

From npm (recommended for end users)

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@whomwah/opencode-nelson-muntz"]
}

OpenCode will automatically install it on startup.

From source (for development)

# Clone the repository
git clone https://github.com/whomwah/opencode-nelson-muntz.git
cd opencode-nelson-muntz

# Install dependencies
just install

# Link to OpenCode for local development
just link-local    # Global: ~/.config/opencode/plugin/
just link-project  # Project: .opencode/plugin/

Usage

Nelson's tools are designed to complement OpenCode's built-in Plan and Code modes:

• OpenCode Plan mode - For thinking, designing, and conversation without making changes
• OpenCode Build mode - For executing tasks and writing code

Nelson's nm-plan and nm-start tools align with this workflow:

OpenCode Mode	Nelson Tool	What Happens
Plan mode	nm-plan	Design and refine your plan in conversation
Build mode	nm-start	Execute tasks, write code, commit changes

Plan Mode

Use OpenCode's Plan mode with nm-plan to create and refine your plan before any code is written. This is an iterative conversation where you shape the plan until you're happy with it.

1. Start planning - Ask the AI to create a plan:

   You: "Create a plan for building a REST API for todos"
   

   The AI calls nm-plan and generates a draft plan, showing it to you in the conversation. No file is written yet.

2. Iterate on the plan - Refine it through conversation:

   You: "Add a task for authentication"
   You: "Split the database task into schema design and migrations"
   You: "Remove the Docker task, I'll handle that manually"
   You: "Reorder so database setup comes before the API endpoints"
   

   The AI updates the plan and shows you each revision.

   Task ordering matters! Tasks are executed top-to-bottom, so ensure foundational work (setup, data models, infrastructure) comes before features that depend on it. Get the order right during planning - it's easier than reordering later.

3. Confirm and save - When you're satisfied, confirm it:

   You: "Looks good, save it"
   

   The AI calls nm-plan with action='save' to write the plan file to .opencode/plans/rest-api.md.

Build Mode

Once your plan is saved, switch to OpenCode's Build mode and use nm-start to execute tasks. The AI reads the plan file and works through each task.

1. Start the loop - Execute all pending tasks automatically:

   You: "Use nm-start rest-api"
   

   Nelson works through each task, marking them complete and creating git commits.

2. Or run tasks one at a time - For more control:

   You: "Use nm-tasks"          # List tasks and their status
   You: "Use nm-task 2"         # Execute task #2 only
   

Available Tools

When the plugin is installed you can ask opencode for all "nm-* tasks" and it will list them.

Tool	Description
nm-plan	Create or view a PLAN.md file
nm-plans	List all available plan files
nm-start	Start loop from PLAN.md (auto-commits per task)
nm-tasks	List all tasks from the plan
nm-task	Execute a single task (auto-completes, no commit)
nm-complete	Manually mark a task complete (rarely needed)

Tool Parameters

nm-start

Parameter	Type	Required	Description
name	string	No	Plan name (e.g., 'rest-api' or 'My API') - resolves to .opencode/plans/{slug}.md
file	string	No	Explicit plan file path (default: .opencode/plans/PLAN.md)
maxIterations	number	No	Safety limit on iterations (default: 0 = unlimited). Rarely needed.

You can specify the plan by name or file path. If both are provided, name takes precedence.

nm-plan

Parameter	Type	Required	Description
action	string	No	'create', 'view', or 'save' (default: create)
name	string	No	Plan name - used to generate filename (e.g., 'My API' → my-api.md)
description	string	No	Project description (also used for filename if no name)
file	string	No	Explicit file path (overrides auto-generated name)
content	string	No	Plan content to save (required when action='save')

Filename generation priority:

1. Explicit file parameter if provided
2. Slugified name parameter
3. Slugified description parameter
4. Falls back to "plan.md"

All plans are stored in .opencode/plans/ by default.

nm-task

Parameter	Type	Required	Description
task	string	Yes	Task number (1, 2, 3...) or name
name	string	No	Plan name (e.g., 'rest-api' or 'My API') - resolves to .opencode/plans/{slug}.md
file	string	No	Explicit plan file path (default: .opencode/plans/PLAN.md)

nm-tasks

Parameter	Type	Required	Description
name	string	No	Plan name (e.g., 'rest-api' or 'My API') - resolves to .opencode/plans/{slug}.md
file	string	No	Explicit plan file path (default: .opencode/plans/PLAN.md)

nm-complete

Parameter	Type	Required	Description
task	string	Yes	Task number (1, 2, 3...) or name
name	string	No	Plan name (e.g., 'rest-api' or 'My API') - resolves to .opencode/plans/{slug}.md
file	string	No	Explicit plan file path (default: .opencode/plans/PLAN.md)

Development

Prerequisites

• Bun v1.0 or later
• OpenCode installed

Setup

# Clone the repository
git clone https://github.com/whomwah/opencode-nelson-muntz.git
cd opencode-nelson-muntz

# Install dependencies
just install

# Type check
just typecheck

# Build for distribution
just build

Tasks

This project uses just as a command runner. Run just with no arguments to see all available tasks.

Local Files and Folders

Nelson creates files in your project's .opencode/ directory:

.opencode/
├── plans/                      # Your plan files (persistent)
│   ├── my-api.md
│   └── another-project.md
└── nelson-state.local.json     # Loop state (temporary)

File Details

File/Folder	Purpose	Lifecycle
.opencode/plans/	Stores PLAN.md files with your tasks	Persistent - you create and manage these
.opencode/nelson-state.local.json	Tracks active loop state (iteration count, current task, session ID)	Temporary - created when loop starts, deleted when loop completes or is cancelled

Git Recommendations

Add to your .gitignore:

# Nelson Muntz plugin state (temporary, local only)
.opencode/nelson-state.local.json

Your plan files in .opencode/plans/ can be committed if you want to share them with your team, or gitignored if they're personal.

How It Works

1. Loop Activation: When you call nm-start, the plugin reads PLAN.md and creates a state file at .opencode/nelson-state.local.json

2. Task Execution: The plugin generates a prompt for the first pending task and sends it to the AI

3. Session Monitoring: The plugin listens for the session.idle event which fires when the AI finishes its response

4. Task Completion: When idle, the plugin marks the current task as [x] in PLAN.md and creates a git commit

5. Loop Continuation: The plugin finds the next pending task and sends a new prompt. If no pending tasks remain, the loop ends.

When to Use Nelson

Good for:

• Multi-step projects with distinct phases
• Greenfield development where you want git commits per task
• Projects where you want to review progress task-by-task

Not good for:

• One-shot operations that don't benefit from iteration
• Tasks with unclear success criteria
• Production debugging (use targeted debugging instead)

Learn More

• OpenCode Plugins: https://opencode.ai/docs/plugins/

License

MIT