Nelson Muntz Plugin for OpenCode


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.

!Nelson Muntz OpenCode Plugin

$3

``


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

$3

Add the plugin to your opencode.json:

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

OpenCode will automatically install it on startup.

$3

`bash


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 |

$3

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.

$3

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
`

$3

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) |

$3

#### 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

$3

- Bun v1.0 or later
- OpenCode installed

$3

`bash


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
`

$3

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)
`

$3

| 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 |

$3

Add to your .gitignore:

`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

$3

- 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

$3

- 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