optim-plans
Human-in-the-loop planning plugin for Claude and Codex: turn ideas into reviewed Markdown plans, record decisions, enforce explicit execution gates, and provide tested controller primitives for safer agent workflows.
What is it?
What it is
optim-plans is an open‑source agentic coding framework that turns a vague request into a reviewed Markdown plan, records the decision history, and gates execution behind explicit human approval. It implements a two‑ring architecture: a planning‑refining ring that iteratively asks questions, refines plans, and produces reviewable artifacts, and an executing‑validating ring that runs code in a dedicated worktree, validates the results, and integrates changes only after a controller‑verified audit.
Why it exists
The tool was created to solve the two classic failures of agentic coding: building the wrong thing and executing unsafe changes. By making plans durable, reviewable, and tied to verification, it keeps humans in the loop, reduces context‑window drift, and provides defense‑in‑depth safety checks that guard against accidental or malicious code changes.
Who should use it
Developers and teams building or maintaining open-source projects that require structured, reviewable, and safe agentic coding workflows, especially those using Claude or Codex for code generation and execution.
Who should avoid it
Users who need a quick, single-shot code generation without planning or review, or those who cannot afford the overhead of planning, review, and execution gates, or who lack the technical capacity to run the CLI and manage Git worktrees.
How it works
A quick walkthrough in plain English
How optim-plans works
Step 1 of 3
You interact with it
Open optim-plans, send a request, or connect it to your stack.
Features
Advantages
- Reduces risk of wrong plans through iterative refinement
- Ensures safe execution via human approval and validation
- Maintains audit trails with Markdown and Git integration
- Supports reproducibility with replayable state
- Balances autonomy with controlled execution
- Adapts to repository context via inspections and research
- Prevents drift with bounded retries and recovery
- Enables collaboration through reviewable artifacts
- Scales from small changes to complex systems
- Integrates with existing developer workflows
Disadvantages
- Complex setup and configuration required
- Manual approval gates may slow workflow
- Dependency on specific tools (Codex/Claude)
- Learning curve for mastering the planning process
- Potential overhead for small, low-risk changes
- Recovery mechanisms add complexity
- Limited parallel execution support
- Requires careful handling of Git workflows
- May introduce latency in iterative refinement
- Auto-complete options could lead to unintended outcomes if misused
Installation
cloud
Not specified
docker
Not specified
native
For Claude Code: claude plugin validate --strict. claude plugin marketplace add./ --scope user claude plugin install optim-plans@optim-plans-dev --scope user For Codex: codex plugin marketplace add. codex plugin add optim-plans@optim-plans-dev For one-off development: claude --plugin-dir. '$optim-plans Turn this idea into a reviewed plan before implementation.'
compose
Not specified
FAQ
What is optim-plans and what problem does it solve?
optim-plans is a planning-refining and executing-validating ring for agentic coding. It turns vague intent into a reviewed Markdown plan, records decisions that shaped it, and keeps execution behind explicit approval to prevent building the wrong thing or unsafe execution.
How do I install optim-plans for local Claude Code development?
From the repository root, run: `claude plugin validate --strict .`, then `claude plugin marketplace add ./ --scope user`, and finally `claude plugin install optim-plans@optim-plans-dev --scope user`.
What are the two rings in optim-plans and how do they work?
The planning-refining ring turns vague intent into a reviewed plan through question-answering loops and refinement (reviewer or criticizer). The executing-validating ring starts from an immutable manifest-bound human approval, runs serial checkpointed work, and uses a read-only validator before controller verification, only proceeding when validation passes.
What are the different planning levels (mini-plan, small-plan, plan, big-plan, huge-plan) and when should I use each?
mini-plan (1 question): Tiny, low-risk repo edits. small-plan (1-3 questions): Small docs, policy, or workflow changes. plan (1-5 questions): Normal multi-decision project changes. big-plan (5-10 questions): Broad features with research needs or unclear architecture. huge-plan (10+ questions): New plugins, large systems, or open-ended efforts.
How does optim-plans ensure safety during execution?
Safety is ensured by immutable manifest-bound execution approval, controller-owned worktree and branch, serial item execution with checkpoint commits, read-only validation before controller verification, path allowlists and Git audits, automatic retry until success or blocked, and automatic fast-forward integration after full local proof.
Featured in Videos
YouTube tutorials and walkthroughs for optim-plans
Alternatives
Similar projects ranked by category, topics, and text overlap.
