getting started

Install the command-line tool, write one small plan, and hand its next step to any coding agent.

The examples below use a terminal. If command-line tools are new to you, copy each line that begins with $ and run it in order. The $ is the prompt; do not type it.

1 · Install the CLI

# a) global command from a clone
$ git clone https://github.com/leemeichin/marionette && cd marionette
$ npm install && npm link          # installs deps, builds, puts `marionette` on PATH
$ marionette version

# b) zero-clone, from anywhere (npm builds it transparently on first use)
$ npx --yes github:leemeichin/marionette validate plan.mar

Use npm link if you expect to run Marionette often. Use npx if you only want to try it or run it in automated checks.

2 · Write a small first plan

Start with a workflow you already understand. This example picks up three issues, opens a pull request for each one, updates their status, then posts a final update. Each === name === section is a stage of the project—not a tiny implementation task.

# project: issue-to-pr
VAR prs_opened = 0

=== work_issue ===
Move the next ready issue to "In progress", implement it, open a pull
request, and move the issue to "In review".
~ prs_opened += 1
+ {prs_opened < 3} [Pick up the next issue] ~loop~ -> work_issue
* {prs_opened >= 3} [Queue is clear] -> share_update

=== share_update ===
Post a short status update with links to the open pull requests.
-> END

$ marionette validate plan.mar --strict   # check for problems
$ marionette summarize plan.mar           # read a plain-language summary
$ marionette render plan.mar              # create a flowchart

If validation fails, every diagnostic carries a line number and a help: suggestion — see docs · check it for what that looks like, and the diagnostic table for the full list. You can also paste the plan into the playground and fix it live.

3 · Set it up with your coding agent

You do not have to learn the plan syntax. Marionette ships two skills — plain Markdown playbooks any agent can follow. The authoring skill turns ordinary notes into a checked draft; the execution skill has the agent work through a finished plan, record decisions, and stop when a person is needed. Set them up once for your agent of choice:

Claude Code

This repository is a single-plugin marketplace; the plugin installs both skills in every project. In any Claude Code session:

/plugin marketplace add leemeichin/marionette
/plugin install marionette@marionette

Codex

Codex reads AGENTS.md. Copy the skills into your project and point to them:

$ mkdir -p .agents/marionette
$ curl -fsSL https://raw.githubusercontent.com/leemeichin/marionette/main/skills/marionette-authoring/SKILL.md \
    -o .agents/marionette/authoring.md
$ curl -fsSL https://raw.githubusercontent.com/leemeichin/marionette/main/skills/marionette-execution/SKILL.md \
    -o .agents/marionette/execution.md

Then add two lines to AGENTS.md (create it in the project root if it doesn't exist):

To plan a project as a Marionette trajectory (.mar), follow .agents/marionette/authoring.md.
To execute or resume a .mar plan, follow .agents/marionette/execution.md.

OpenCode

OpenCode also reads AGENTS.md, so the Codex setup above works as-is. If you prefer a global install, put the two files under ~/.config/opencode/ and reference them from your global AGENTS.md instead.

Anything else

The skills assume nothing about the agent beyond reading files and running a CLI. Point your tool at the two SKILL.md files in skills/ however it ingests instructions — system prompt, rules file, or a plain "follow this document". The CLI is the enforcement layer, so the guarantees hold no matter which agent drives it.

Then give it real notes

Use the marionette authoring skill. Plan this for me: we're migrating the
billing service off Stripe Classic. Spike the new API first — if metered
billing isn't supported we stay put. Up to two spike attempts. Finance
signs off before any customer is switched, and we roll back if error
rates spike.

The skill creates the .mar file, checks it, fixes any problems, and shows you a flowchart and summary. It clearly marks every decision that needs a person.

4 · Start and follow the plan

$ marionette state init plan.mar        # start a run and create the progress file
$ marionette brief plan.mar             # show the agent's next assignment
$ marionette state show plan.mar        # show current progress and available choices
$ marionette state observe plan.mar remaining 7 --actor agent --rationale "source"
$ marionette state choose plan.mar 1 --actor agent --rationale "why"
$ marionette state advance plan.mar --actor agent   # follow an automatic next step
$ marionette state rebind plan.mar      # accept a plan edit and keep the history
$ marionette render plan.mar            # show progress on the flowchart

Marionette applies three important rules. An agent cannot take a choice marked @human. Every choice needs a written reason. If the plan changes after the run starts, Marionette stops until you accept the edit with state rebind. To let your agent handle this loop, use the execution skill. See the execution guide for the machine-readable interface.

5 · Keep it honest in CI

You can run Marionette in automated checks. A successful command returns 0; problems return a different number so the check can stop. This minimal setup checks plans for errors and notices if a running plan has been edited:

$ marionette validate plans/*.mar --strict     # plans stay sound
$ marionette state show plans/project.mar      # exit 3 = plan edited without rebind