Optim-Plans: Human-in-the-Loop Planning for AI Coding Agents

An agent that starts coding the moment it understands a request skips the one step a human teammate would never skip: writing the plan down and getting it checked before touching anything. Optim-Plans is a small, free plugin for Claude Code and Codex built around that gap. It is human-in-the-loop planning for AI coding agents in a literal sense: the agent asks scoping questions, drafts a Markdown plan, waits for a person to review or push back on it, and only then is handed permission to implement.

What it actually does

Optim-Plans is a plugin, not a standalone app. Installed into Claude Code or Codex, it adds five skills that kick in before implementation starts:

• create-a-small-plan, for changes that need one to three clarifying questions
• create-a-plan, for medium efforts needing five to ten questions
• create-a-big-plan, for open-ended or high-risk work
• diagnose-before-plan, for bugs and failures
• reference-before-plan, for changes that need external research first

Invoking one, for example $create-a-plan Turn this idea into a reviewed plan, starts a fixed sequence: the agent inspects the repo in read-only mode, asks planning questions one at a time, confirms scope with the user, then writes the actual plan file. Nothing gets touched until that scope confirmation happens.

What "versioned" and "reviewed" mean mechanically

This is the part worth being precise about, since it is easy to read "versioned document" as something more automated than it is. Plans live in the repo itself, under a folder like docs/optim-plans/2026-08-13-topic/. The first draft is written as PLAN_v1.md, with stable IDs for each item and a mandatory ## Verifier Checklist section. Supporting files in the same folder track the reasoning: PROBLEM_ANALYSIS.md, DECISIONS.md, and, if research was involved, REF_ANALYSIS.md.

The review step is a refinement pass, not a separate approval role. The user can send the plan through a "Reviewer" or "Criticizer" mode, which reads the draft and writes its critique to a file like PLAN_v1_reviewer_comments.md. That feedback drives PLAN_v2.md, and the cycle can repeat. Once the plan is stable, the agent asks a native handoff question with three explicit options: execute now with normal tools, stop after planning, or something else. Notably, the plugin's own rules block its auto-complete mode from answering this question on the user's behalf. Approving implementation, waiving a missing reference requirement, or authorizing anything destructive has to come from an actual person, not a default choice.

The part the source material overstates a little

The scan note that flagged this tool described it as something your agent "actually follows step by step instead of losing context every new session." That is mostly true but needs a caveat. The plan file is a durable Markdown document sitting in the repo, so any future session, in Claude Code, Codex, or just opened in a text editor, can read it and pick up where the last one left off. That part is real and is the actual value of writing plans to disk instead of leaving them in a chat transcript that disappears.

What is not documented, at least as of the current release (v0.3.0), is any automatic mechanism that makes a brand-new agent session discover and reload an existing plan on its own. There is no slash command or hook in the README that re-injects an approved plan into a fresh context window. The persistence is structural (the file exists, versioned, in the repo) rather than active (the agent doesn't hunt for it and resume automatically). In practice this means a person still needs to point the next session at the right PLAN_vN.md file, which is a smaller win than full session-to-session continuity but still a meaningful one over agents that plan silently and lose the reasoning the moment the context window rolls over.

The maintainers are also candid that this version is intentionally scaled back. The README states plainly that 0.3.0 removed the separate controller execution engine, along with any manifest, checkpoint lifecycle, or verification role from earlier iterations. Git hooks enforce some guardrails around the review flow, but the docs are explicit that hooks are "defense in depth," not a sandbox.

Installing it

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

The controller code is standard-library Python 3.11+, with no external dependencies to wire up, and it expects to run inside a Git repository since its own run history is stored under .git/optim-plans/.

Who it's for

Solo operators and small teams running Claude Code or Codex on real codebases, where an agent jumping straight into a "big" refactor without checking scope first has caused pain before, are the obvious fit. It is also useful for anyone who wants a paper trail: a record of what was decided and why, sitting in the repo next to the code it describes, instead of buried in a chat log.

It will feel like overhead for quick, low-risk edits, which is presumably why the plugin ships a "small plan" tier instead of forcing every change through the same heavy process. And given the project is under a month old (first commit July 23, 2026, MIT licensed, standard-library Python), it is worth treating as an early, actively developed tool rather than a settled standard. As of today the repo sits at 541 stars and 1 fork, still climbing since its scan snapshot a few days ago.

Repo: github.com/Optim-Agent/optim-plans