Skip to main content

/moai todo NEW

UPDATED 2026-10-17 17 min read EDIT ON GITHUB ↗
NEW · v3.1
Info
moai gtd and /moai gtd remain a fully supported compatibility surface for existing automation and scripts. The canonical names are /moai todo and moai todo; both names use the same SQLite queue, card IDs, ordering, archive, and restore behavior.

A backlog queue where you stack up what to do next, one line at a time. The factory queue’s backlog has no session assigned to it, so nobody pushes work into it on its own. Putting a card in the queue is therefore always a human’s judgment, and /moai todo is that window.

Info
One-line summary: /moai todo records what to work on next. You add an item, view the list, archive completed work, and pick the next card. Picking does not create a SPEC; the card class determines the workflow.
Info
Slash command: Type /moai:todo in Claude Code to run it immediately. Typing /moai alone shows the list of all available subcommands.

Overview

A backlog item is one line of intent, not a SPEC or a plan. After a human picks it, Class A proceeds directly to close, Class B follows run → sync without a SPEC, and Class C follows plan → run → sync with SPEC authoring in plan.

The queue is deliberately thin. It holds nothing that a SPEC, git history, or the factory record records better — only what the human wants next.

flowchart TD
    Add["/moai todo description
add an item"] --> Queue["backlog queue"] Queue --> Pick["via the factory leader question channel
a human picks one"] Pick --> Class{"Card class"} Class --> A["A: direct close"] Class --> B["B: run → sync"] Class --> Plan["C: plan → run → sync
SPEC is authored in plan"] Plan --> Spec["SPEC ID recorded on the item"]

Usage

bash
# Add an item
> /moai todo "clean up error paths in auth middleware"

# View the queue
> /moai todo
InvocationBehavior
/moai todo "<description>"Appends an item to the end of the queue and shows the added item and its position.
/moai todoShows the queue in order, with position numbers.

Removing an item and picking the next card are not verbs on the slash surface. Those two belong to the terminal CLI below (moai todo done, moai todo next) or to the pick made through the leader session.

Any other argument shape is treated as a description. /moai todo fix flaky CI cache is not an error but an item add — the cost of a misunderstanding is a human deleting one line.

State file

For a regular project directory, the queue is stored in one SQLite database at ~/.moai/db/<project-key>/todo/backlog.db. When the project originates in a temporary directory (os.TempDir(), /tmp, or /var/folders), the queue stays project-local at <base>/.moai/state/todo/backlog.db instead — an absolute MOAI_HOME override wins even then. The project key binds linked worktrees to one home-scoped queue, and the database is never committed. The shape below is the record as moai todo list --json and moai todo export-json emit it — the database holds the same fields. For migration and downgrade details, see .moai/docs/todo-queue-storage.md in your project.

Find the database paths with moai paths instead of guessing them. Opening a guessed path such as ~/.moai/db/todo.db with sqlite3 creates an empty file, so never do it. If you must read directly, read only a snapshot copy of .db, .db-wal, and .db-shm together; otherwise prefer the CLI, such as moai todo list --json and moai factory status.

json
{
  "version": 1,
  "project_uuid": null,
  "items": [
    {
      "id": "t1",
      "text": "clean up error paths in auth middleware",
      "added_at": "<RFC3339 timestamp>",
      "spec_id": null,
      "state": "queued",
      "card_uuid": null
    }
  ],
  "findings": [
    {
      "subject_id": "t2",
      "related_id": "t1",
      "relation": "near-duplicate",
      "source": "mechanical",
      "score": 0.83,
      "note": "",
      "at": "<RFC3339 timestamp>"
    }
  ],
  "runtime": {
    "runs": [
      {
        "project_uuid": null,
        "run_id": "run-1",
        "backend": "claude",
        "manifest_json": "{}"
      }
    ],
    "assignments": [
      {
        "project_uuid": null,
        "card_uuid": null,
        "run_id": "run-1",
        "card_id": "t1",
        "owner_label": "lane-1",
        "reported_state": "picked",
        "event_kind": "card.assigned",
        "provenance_json": "{}"
      }
    ]
  }
}
FieldMeaning
idA short, stable identifier assigned at add time. Never reused after removal.
project_uuid / card_uuidPersistent identities for the project and card. Older records without identities still emit these keys as null from list --json; that pure read neither issues UUIDs nor changes the database. A later authorized write fills them with canonical lowercase UUIDv7 strings. The same contract applies to Git repositories and ordinary folders without Git.
spec_idAn optional link to a SPEC identifier. Filled when the pick records it via --spec; when the id is not yet known it stays null even in the picked state.
runtimeThe latest run-start and card-assignment reports. runs and assignments are always arrays, and their UUID fields are logical projections of Todo identity; the runtime tables do not store separate UUID columns. reported_state is a report, not authority over the card’s completed state.
findingsThe records kept about pairs of cards. A relation belongs to the pair rather than to either card, which is why it lives here and not in an item. Always an array — a file written before this feature loads with an empty one, so “no findings” never has to be told apart from “no such feature”. source is mechanical (a measured text similarity) or agent (a judgment written by a human or an agent). A finding leaves the file when its card does.
stateThe lifecycle discriminator. One of queued · picked · dropped — this value is what separates “still a backlog item” from “already a card handed to a lane”. A picked item stays in the file so ongoing work is visible. The only way an item leaves the live queue is an explicit moai todo done run by a human — nothing removes it automatically when its work completes. done does not delete the card and its findings; it archives them: they stop appearing in list / next / why / analyze, and moai todo undone <n> restores both, at the position the card held. Discarding is different from archiving: moai todo drop <n> "<reason>" moves a card to dropped while keeping it in the live queue file, prefixing its text with the reason, and moai todo undrop <n> reverses that exactly. A dropped card is not a pick candidate.

Changes commit in a SQLite transaction under the queue lock, using WAL mode. A missing queue is an empty queue; unreadable or malformed data is reported and left untouched. The console displays an unavailable state when it cannot read the queue, rather than presenting a zero count.

Automatic analysis

The queue reads itself on every add, and across the whole queue on moai todo analyze, looking for cards that resemble each other and recording what it finds. A record changes no card: not its text, not its position, not its state.

Exactly one thing is ever blocked. A card whose normalized text is identical to one already queued or picked is refused at the door. The refusal erases nothing and leaves the queue file byte-identical; you see an error instead of an id. When you want it anyway, --force admits it and records that the duplicate was forced.

A card that resembles another without matching it (token-set Jaccard at or above 0.80) is added verbatim and carries a near-duplicate record. Two cards that mean the same thing in different words go unnoticed, and that limit is deliberate: a false positive here throws away a card someone wrote, while judging meaning is what moai todo relate is for — and there a mistake costs one line of output.

The four relations contains · absorbs · replaces · conflicts are written by hand, by a human or an agent. Despite their names they do nothing — writing absorbs absorbs no card. What to do about a record is your decision, carried out with drop, edit, or move.

moai todo list prints each record as an indented line under the card it names, marked machine-only while nothing human-written names the same pair. The mark says only that the record is machine-made — never that nobody reviewed the pair, because the CLI cannot know who called it.

Picking the next card

The pick is made by a human through the leader session’s question channel. The leader presents the queue as choices — one item at a time, oldest first, up to the four the tooling allows, with the rest summarized in the body so nothing is hidden — the same way it presents the queue as the first move after a /clear. From the terminal, a bare moai todo next prints the same list read-only when you just want to see the candidates.

Warning
A human does the picking. Nothing is pre-selected, no estimated priority reorders the queue, and “just start from the top” is never a default. If the queue is empty, it says so and stops — an empty backlog is a normal state, not a signal to invent work.

You can also approve several cards at once — by pointing at the cards, or by saying to proceed in order until the queue is empty. That is still a human choice, just made in one batch instead of one at a time. The leader admits the cards in the approved order and does not ask again. What that approval permits is exactly that and nothing more — it is not a license to add items, reorder the queue, or decide cards whose judgment falls outside the approved scope.

After a card is picked, it continues like this:

  1. The picked item is marked picked with one locked write: moai todo next <n> [--spec <SPEC-ID>]. When the identifier is already known, it is attached right here.
  2. Follow the card class: A direct close, B run → sync without a SPEC, or C plan → run → sync with SPEC authoring in plan.
  3. For a card that requires a SPEC, re-run moai todo next <n> --spec <SPEC-ID> once its identifier is known. This attachment is explicit; a picked card may legitimately have no SPEC.

Outside Factory Mode

/moai todo works as-is in an ordinary single session — it is just a queue. It does not dispatch, though. Without lane sessions there is nobody to instruct, so reading and writing the queue is all there is, and the rest proceeds by hand.

Boundaries

  • Not a work-management tool. No priorities, no assignees, no deadlines, no dependency graph. Work that needs those belongs in an issue tracker or a SPEC.
  • Not the run record. Which stage a card is in is held by the lane carrying it and the SPEC status, not by this file.
  • Not the source of truth for work in progress. Once a card has a SPEC, the SPEC artifacts are the reference; the backlog item is only a pointer to it.
  • It does not fill itself. The tool never scrapes TODO comments, open issues, or audit findings into the queue. A human puts items in.
  • The guidance surfaces can be switched off. The session-start summary, the statusline TODO segment, and the automatic routing turn off with workflow.todo.enabled: false in workflow.yaml (see the configuration reference). The command and its verbs keep working when off.

CLI surface

The same queue is also operable from the terminal. The slash command /moai todo and the terminal CLI moai todo are two distinct surfaces — they operate on the same file, but their syntax differs.

bash
# Add an item — prints the issued id and queue position on one line
$ moai todo add "clean up error paths in auth middleware"

# Two or more words add even without `add` (natural-language fallthrough)
$ moai todo rename the stale hint

# View the queue (id · state · text) — a bare call with no verb gives the same result
$ moai todo
$ moai todo list

# View as structured records
$ moai todo list --json

# Archive an item — accepts a number (t4) or an explicit id
$ moai todo done 4

# Reverse it: restore an archived card back to where it was
$ moai todo undone 4

# Only proceed when the text starts with the prefix — guards against closing the wrong card
$ moai todo done 4 --expect "auth middleware"

# Ask whether the card landed, and refuse only on a positive "not landed" answer
$ moai todo done 4 --require-landed

# Batch-close landed cards (leader only, after the batch push is confirmed) — dry-run first
$ moai todo auto-done --fetch --dry-run
$ moai todo auto-done --fetch

# Print queued items oldest-first (read-only)
$ moai todo next

# Record a pick — optionally attaching the SPEC identifier
$ moai todo next 4 --spec SPEC-AUTH-001

# Add and pick in one locked write
$ moai todo add "tidy up the graph query docs" --pick

# Revert the picked mark — on a card not yet handed to plan
$ moai todo unpick 4

# Re-analyse the whole queue, recording only (no card is touched)
$ moai todo analyze

# Add an exact duplicate anyway — the queue records that it was forced
$ moai todo add "clean up error paths in auth middleware" --force

# Record a relation between two cards (a record only; both cards stay put)
$ moai todo relate t2 t1 --relation absorbs --note "t2 covers t1"

# Print everything the queue knows about this card
$ moai todo why t1

# Remove one record — the index is the one `why` prints
$ moai todo unrelate 2
CommandBehavior
moai todo (bare)Prints the queue. Same output as list.
moai todo <two or more words>Adds the natural-language text as an item. A single word (including a typo’d verb) is an error, not an add. A verb-shaped first token followed by a card id (moai todo pick t151) is read as a mistyped verb and errors — a card that merely mentions an id later in the sentence still adds.
moai todo add "<text>" [--pick]Adds an item and prints the issued id and position. With --pick, the add and the picked mark land in one locked write.
moai todo list / --jsonRenders the queue. --json emits the full records as JSON.
moai todo done <n> [--expect <prefix>] [--require-landed]Takes item n out of the live queue under the lock. The explicit t<n> id form is preferred — queue positions move under concurrent adds. The card and every finding naming it are archived, not deleted — undone restores both. Archived rows do not appear in list / next / why / analyze or the duplicate-analysis input. --expect <prefix> refuses unless the card’s text starts with the prefix — a guard against closing the wrong card. --require-landed asks a landing predicate and refuses only on a positive “not landed” answer, proceeding when the predicate is inconclusive — the predicate reads the commit subject on the answered ref and asks whether it attributes the card in one of six positional forms: a conventional-commit scope, a trailing parenthetical credit, that credit followed by a pull-request reference, a card-led merge, an integration merge carrying a card token in its trailing group, or merge: <card>. A body mention, a mid-sentence mention, and a branch name count for nothing — attribution is a position in the subject, never a token occurring anywhere in a message. The ref resolves through the project setting (git_strategy.worktree_base_branch), then refs/remotes/origin/HEAD, then the compiled-in default (origin/main); when an unconfigured project’s answer comes from a lower level, the source is disclosed on stderr. Without the flag, done runs no landing query and adds no cost; every refusal path leaves the queue record byte-identical. Every successful done prints exactly one landing-verdict token on stdout — `done landing=landed
moai todo undone <n>Restores an archived card, along with every finding that named it, to the live queue at the position it held, and empties the archive entry. done followed by undone returns the queue record to the same bytes. Refused, naming the collision, when the id has since been reissued to a different live card — the live card is left alone.
moai todo nextPrints queued items oldest-first. Read-only.
moai todo next <n> [--spec <SPEC-ID>]Marks the item picked; with --spec, records the identifier verbatim. One locked write.
moai todo unpick <n>Reverts the picked mark. Because the pick itself is a human judgment, the revert is also done directly by a human.
moai todo drop <n> "<reason>" [--expect <prefix>]Moves a queued card to dropped, prefixing its text with a [DROPPED — <reason>] marker. Both arguments are required; an empty reason, or one containing ], is refused. The card stays in the file and only leaves the pick candidates. --expect runs the drop only when the card’s text starts with that prefix.
moai todo undrop <n> [--expect <prefix>]Returns a dropped card to queued, stripping the marker when one is present. The state is the authority, not the marker — a card marked dropped by hand undrops with its text untouched. An exact reversal of drop.
moai todo edit <n> "<text>" [--expect <prefix>]Rewrites only the card’s text. id, added_at, state, and spec_id are preserved, so a correction never churns the card’s identity the way done + re-add does. The confirmation prints both the new and the prior text.
moai todo move <n> (--top | --bottom | --before <m> | --after <m>)Repositions the card within the queue file’s order. Exactly one destination flag is required — none, or two, is a malformed invocation and is refused. The move permutes the items and nothing else, so a wrong move is reversed by another move.
moai todo add "<text>" --forceAdmits a card the analyser reads as an exact duplicate. The queue records that the duplicate was forced, so the collision stays visible.
moai todo analyzeRe-analyses the whole queue and records what it finds. Appends, removes, reorders, and edits nothing; re-running never stacks the same record twice.
moai todo relate <a> <b> --relation (contains | absorbs | replaces | conflicts) [--note <text>]Records one relation between two cards. It is a record only — both cards stay exactly as they were, and absorbs performs no absorption.
moai todo unrelate <index>Removes the addressed record. The index is the one why prints. No card changes.
moai todo why <n>Prints every record naming the card, or says explicitly that there are none — printing nothing would be indistinguishable from a crash.
moai todo export-jsonWrites the live queue out as a legacy-format backlog.json beside the database, so a release predating the database can read it. It is a copy taken at the moment you run it, not a live mirror — export immediately before swapping binaries. Unlike live items, archived cards ARE included in this export — but whenever the exported record actually carries archived rows, the command discloses on stderr that a binary predating the archive feature will drop that field on its first write. Later todo verbs leave the file exactly where it was put. The read verbs — list, show, why, pr, history — additionally disclose on stderr that the file beside the database is not the queue, so a stale export is not mistaken for live state.

The CLI never prompts. It takes arguments and flags, prints one line, and reports errors on stderr — a shape that is safe in scripts and CI.

Run it inside a linked worktree and the queue still resolves to the primary checkout’s project key — the contract is one repository, one queue. A moai todo add from a card worktree lands in the same database the leader and the foreman loop read. Projects without git metadata use the same home layout — unless they originate in a temporary directory, in which case the queue is project-local at <base>/.moai/state/todo/backlog.db (an absolute MOAI_HOME override applies even then).

Both surfaces share the same storage layer. Mutations hold the sibling lock file (backlog.lock) next to the database and land inside one SQLite transaction in WAL mode; reads take no lock. Item ids are issued from the persisted high-water mark (last_seq), advanced in the same transaction as the insert and guarded by a UNIQUE constraint on the id, so a removed item’s id is never reused even if a process dies mid-mutation.

Info
Installed binary: the CLI ships with the distributed binary. An already-installed moai binary only gains this command after reinstalling.