mcuemcuedocs
Sign in to HubRequest alpha access

Quickstart

This runs the whole local loop once, end to end. It takes about five minutes, makes no network request, and leaves you with real state you can inspect in a text editor afterwards.

You need mcue on your PATH — see Install if mcue doctor does not answer.

1. Register a project

Change into a directory you actually work in, then:

cd ~/work/payments-api
mcue init payments-api --name "Payments API"

init registers the project, scaffolds its state files under $MCUE_HOME, and drops a small .mcue footprint in the current directory so later commands can tell which project you are in without being told.

The positional argument (payments-api) is the stable project id; --name sets the display name ("Payments API" here). --name is optional from v0.14.1 and defaults to the id; before v0.14.1 it is required, and a bare mcue init payments-api fails with required flag(s) "name" not set.

The project id is yours to choose. Keep it short and stable — it appears in every later command, and renaming later means mcue project rename.

2. Do some work

Nothing to run here. Write code, break something, fix it, get interrupted. mcue is not watching; it only records what you tell it at the end.

3. Close out the session

This is the command that matters:

A closeout records five things: what you intended, what actually happened, anything blocking, the next action, and where to resume. They are flags, so a real one looks like this:

mcue closeout payments-api \
  --intent "Wire refunds to the ledger" \
  --outcome "Ledger client assumes idempotency keys are UUIDs; ours are ULIDs, so every retry double-posts. Refund path itself is written but unusable until the key format is settled." \
  --blockers "Whether to change our key format or wrap the ledger client" \
  --next-action "Ask Sam which one the ledger team will support" \
  --resume-pointer "internal/ledger/client.go:88, TestRefundRetry fails"

Checkpoint written: ~/.mcue/projects/payments-api/checkpoints/20260817T173512Z.md
Lane: default
Project state refreshed for "payments-api"
Scores: clarity high | cost low | trust medium | quality high (100/100)

If you would rather write prose than assemble flags, mcue closeout payments-api --editor opens your editor with the five fields laid out, and --outcome-from-file ./notes.md reads any of them from disk.

Answer honestly and briefly — a closeout that says "fixed the thing" is worth nothing in three weeks, and the score on that last line will tell you so. The gap between intent and outcome is the most valuable part: this one records that the session did not do what it set out to do, and exactly why.

A closeout writes a timestamped checkpoint and refreshes the project's governed state. It is the only routine way state advances.

4. Come back later

Days pass. Come back and ask for a way in:

mcue resume payments-api

You get a resume packet: a bounded brief capped at roughly 300 or 1000 tokens depending on the tier you ask for. Small enough to hand straight to an agent, big enough to re-enter without re-reading everything.

That cap is deliberate. An unbounded dump of project history is exactly as useless as no history at all.

5. See everything at once

mcue index

The derived portfolio view across every registered project — what is active, what is blocked, what has gone quiet. Name a project to scope it to that one:

mcue index payments-api

6. Read the state yourself

Nothing here is opaque:

ls ~/.mcue/projects/payments-api/
cat ~/.mcue/projects/payments-api/project_state.md

Markdown with YAML front matter. Diffable, greppable, and editable by hand when something needs repairing. If mcue vanished tomorrow, your state would still be readable.

Where to go next