Reference

The wanigan command

In short

Every session Wanigan starts can run wanigan, a command that works the project’s board as that session and only inside its project. With it an agent takes a card, notes progress, files what it finds and submits work with evidence, while approving, archiving and accepting from the Inbox stay yours.

On this page

What it is

An agent that cannot see the board works blind: it does not know which card is its own, what you sent back, or what the project has decided. The wanigan command is the board, from inside the agent’s own terminal.

It is on the PATH of every session Wanigan starts, and it acts as that session: it reaches Wanigan’s core with the session’s own token.
Everything it does is in the session’s own project. Another project’s card is refused: “That card belongs to another project.”
A session that has ended can still read the board (status, list, show, decisions) but not change it: “This session has ended; it can read the board but not change it.”
Nothing is written into the project for it. The command is a file in Wanigan’s data folder (bin/wanigan), put on the session’s PATH as it starts.
--json prints any answer as JSON. wanigan help lists every command; an unknown command prints the help and exits with code 2. A flag without its value is refused, so --evidence --note x says “--evidence needs a value.”

Every command

KEY is a card’s key, such as NS-6. Every refusal is printed after “wanigan:” in the core’s own words.
Command	What it does	Refused when
`wanigan status`	Your card, cards sent back to you with your note on each, any other card you hold, the top of Ready, the decisions in force, and whether the project is paused.	Run outside a session: it is a session’s own command.
`wanigan list [--status ready]`	The project’s cards, one line each: key, priority, type, column, title, flags such as “sent back”, and the session holding it. `--status` keeps one column: `inbox`, `ready`, `working`, `review`, `done` or `archived`.	Never, inside a session.
`wanigan show KEY`	One card in full: its description, acceptance criteria with their ticks, comments and evidence.	The card is in another project.
`wanigan claim KEY [--note "…"]`	Takes the card: it moves to Working, held by this session for 30 minutes at a time, renewed while the session is alive. A note becomes a comment.	The card is in the Inbox, in Review, Done or archived; another session holds it; the project is paused.
`wanigan note KEY "…"`	A comment on the card, and the claim renewed.	This session does not hold the card.
`wanigan review KEY --evidence X [--evidence Y] [--note "…"]`	Submits the card for your review: it moves to Review and the claim ends. Each `--evidence` is a file, a link (`http://` or `https://`) or a sentence.	The card is not in Working; this session does not hold it; there is no evidence; an evidence path is a folder.
`wanigan release KEY [--note "…"]`	Gives the card back: it returns to Ready.	This session does not hold the card.
`wanigan file TYPE "title" [--body "…"] [--priority 0-3]`	Files a new card. TYPE is `task`, `bug`, `feature` or `idea`; priority 0 is the most urgent, and 2 if left out. What an agent files always lands in the Inbox, for you to accept.	A type or a priority outside those.
`wanigan ask KEY "question"`	Asks you a question on the card. It shows in your Needs you, and your reply lands on the card.	The card is in another project.
`wanigan criteria KEY "criterion"`	Adds an acceptance criterion.	This session neither holds the card nor filed it into the Inbox itself.
`wanigan decisions`	The project’s decisions in force, each with its text.	Never, inside a session.
`wanigan mcp`	The live view’s tools, as an MCP server on stdin and stdout. Wanigan hands it to the agent itself; see below.	Run outside a session Wanigan started.

Examples

In a session on NS-6

wanigan status
wanigan claim NS-6 --note "starting with the pay button"
wanigan note NS-6 "the button is an icon with no label"
wanigan criteria NS-6 "The label is read in the page’s language"
wanigan review NS-6 --evidence axe-report.txt --evidence https://example.test/checkout --note "fixed; axe is clean"
wanigan file bug "Shipping estimate ignores the postcode" --priority 1
wanigan ask NS-6 "Should the express checkout button get a label too?"
wanigan list --status ready --json

What it answers

$ wanigan claim NS-6
Claimed NS-6. Your claim renews while this session is alive.
$ wanigan review NS-6 --evidence axe-report.txt --note "fixed; axe is clean"
NS-6 is in review. The owner approves it or sends it back; `wanigan status` shows which.
$ wanigan file bug "Shipping estimate ignores the postcode"
Filed NS-14 in the Inbox.
$ wanigan claim NS-14
wanigan: This card is in the Inbox. The owner accepts it to Ready before anyone works on it.

wanigan mcp and the live view’s tools

An agent that edits a site cannot see the page it changed. wanigan mcp is the same command run as an MCP server, the way a coding agent is given extra tools: Wanigan hands it to every Claude Code, Codex and Gemini CLI session it starts, so the agent can look at the project’s local site itself. Nothing is written into the project for it.

Tool	What it answers
`live_status`	Whether the live view is on for the project, the local site and what it runs on, the page you are looking at and how wide, whether Wanigan’s window is open, and whether before and after screenshots are on.
`live_look`	A page rendered fresh in a hidden window, its parts named as Drupal or WordPress names them, each with the file that made it and an id; a picture only when asked.
`live_find`	The parts of a page that match some words: a name, a template or component, a field or block, or words on the page.
`live_part`	One part as the Inspector shows it: whose code made it, the file to create to override it, its content and where to change that in the admin, and its key styles.
`live_problems`	What a page reports as wrong: its error and warning messages, console errors and failed requests, from a fresh load, and what your view of it logged.
`live_diff`	What changed on the card’s page since the end of the session’s last turn that changed files (or since it began), each changed area matched to the edited file that explains it, or said to be unexplained.
`live_site_ai`	The AI the site runs, as its core reports it (never a key), and the code beyond core that runs when content is saved.
`live_library`	What the site can place: Drupal’s components and block library, WordPress’s block types, patterns and block styles.

Every tool reads only, and opens only the project’s own local site, in a hidden window, so your view never moves. Each call is kept on the card, on its Looks tab.
The same reads are offered as five MCP resources, for a client that reads resources rather than calling tools.
Outside a session its tools answer only “The live view’s tools work only inside a session Wanigan started”, and with the core stopped, “Wanigan’s core is not running, so the live view cannot be read now.”

How each agent is told

An agent only uses a command it knows about. As each session starts, Wanigan gives the agent a short briefing: the project, what wanigan does, its card with its acceptance criteria (and your note, if you sent it back), and the decisions in force.

Claude Code gets the briefing from its SessionStart hook. It is given wanigan mcp with --mcp-config, from a file in Wanigan’s data folder, beside your own servers, and the eight tools are allowed by name so a look does not stop to ask.
Codex is told the same at launch, as developer instructions, because its own SessionStart hook fires only once its first turn begins. wanigan mcp reaches it through --config mcp_servers.wanigan… flags for that launch only.
Gemini CLI gets the briefing from its SessionStart hook too, and wanigan mcp is set up in Wanigan’s own Gemini home.
A shell session has the command on its PATH, with no briefing.

Wanigan writes

The briefing, as Claude Code gets it for NS-6

You are working in "Northstar Storefront" (‹the project’s folder›), a project on the owner's Wanigan board.
The `wanigan` command is your board: `wanigan status` shows your card, cards sent back to you and the top of Ready.
Claim a card before working on it (`wanigan claim KEY`), add notes as you go (`wanigan note KEY "..."`),
and submit with evidence when done (`wanigan review KEY --evidence <file|url> --note "..."`). You cannot mark work done; the owner reviews it.
File problems you find but are not fixing with `wanigan file bug "title"`. Ask the owner with `wanigan ask KEY "question"`.

Your card is NS-6: Checkout button has no accessible name (working).
Screen readers announce “button”. Found in the September audit.
Acceptance criteria:
- [ ] The pay button has an accessible name
- [ ] axe reports no violations on /checkout

Decisions in force for this project (follow them):
- Use pnpm, never npm — The lockfile is pnpm-lock.yaml; npm rewrites it.
- No new dependencies without asking

The agent receives Claude Code and Gemini CLI get it as their SessionStart hook’s added context; Codex gets the same words as developer instructions at launch. A card on its own branch adds a line naming the worktree and the branch to stay on.

Words from CODE src/core/briefing.ts readBriefing

What an agent cannot do

The core checks every call against one table of who may call what, so these hold whatever an agent types:

Approve, send back, reopen or archive a card. Only you do, in the window; a paired phone that can act may approve, send back and move cards too.
Take a card from the Inbox, or file one anywhere else: what it files waits in the Inbox until you accept it.
Claim while the project is paused, unless it already holds the card: “The owner has paused this project. Note where you are on your card (wanigan note) and stop.”
Note, add evidence to, submit or release a card it does not hold: “You do not hold this card. Claim it first.”
Tick, reword or remove a criterion, or change a card’s title, description, type or priority. It may only add a criterion.
Reach the rest of Wanigan: other projects, accounts, sessions, git, settings, Jev, saved views, skills and MCP servers are not offered to a session at all.

In depth

Outside a session

Run from your own terminal, wanigan acts as you, the owner. It lives in Wanigan’s data folder, ~/Library/Application Support/Wanigan 2/bin/wanigan, not on your own PATH.

--project KEY says which project list, file and decisions mean: “Outside a session, say which project: --project KEY.”
--data-dir, or WANIGAN_DATA_DIR, says which Wanigan when it is not the usual one, such as the demo’s. With that Wanigan not running, it says so: “Open the app, then try again.”
A session’s own commands (status, claim, note, review, ask) are refused by name, such as “cards.claim is not available to an owner.”
A card you file this way goes straight to Ready, as one you file in the window does.

The rules behind it

A claim is a 30-minute lease, renewed while its session is alive. When the session is gone, the lease runs out and a Working card goes back to Ready, recorded as an expired claim released.
Evidence that starts with http:// or https:// is a link. A value of one line, under 1,024 characters, that names an existing file (from the folder the command runs in) is a file; anything else is a note. The card records whether a file existed when it was offered.
A title is at most 200 characters, a criterion 500, and a note or description 20,000.
The session’s identity is read again on every call, so an ended session keeps its token but loses the right to change anything.
A briefing over 64 KB, or over 256 criteria and decisions, is never cut short: the session refuses to start and says “The session briefing is too large to provide safely.”