Quickstart

This guide takes you from a clean machine to one verified human decision returning to a connected coding agent. The happy path is:

The decision plane is the local or hosted service that stores asks and answers. Your coding agent connects to it through Revue's MCP server.

install → choose local or hosted → run the demo → connect one agent → answer once → verify the receipt

1. Install Revue

Install or update Revue from the repository:

REVUE_START=0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/ethandaya/revue/main/scripts/install.sh)"

The command downloads the standalone binary to ~/.local/bin/revue, installs the Amp plugin and its human-context skill into your user config (~/.config/amp and ~/.config/agents), and prepares ~/.config/revue. REVUE_START=0 keeps installation deterministic so the script returns to this guide instead of launching Revue immediately. After bootstrap, use revue from any workspace.

Confirm the command is available:

revue --help

When working from a Revue checkout, use pnpm run revue in place of revue.

2. Choose a decision plane

Choose one path. Local and hosted decision memory are separate.

Local — account-free and confined to this machine:

revue service start

The service binds to 127.0.0.1, creates owner-only credentials, and selects the local plane. Use this path when your agents run on the same machine.

Hosted — browser-approved and reachable by remote agents:

revue login

revue login opens browser approval and provisions machine credentials under ~/.config/revue without launching the manager yet. Bare revue can combine approval and manager launch when no plane is configured. Use revue login --api-url <url> only for a non-default supported deployment.

See Local vs hosted for the full comparison, switching behavior, and remote-agent limitation.

3. See the complete loop

Run the product demo before configuring a harness:

revue demo

The demo proves the signature behavior against the active plane:

• two workers ask the same question in different words;
• Revue groups them into one decision asked by two agents;
• one human answer routes back to both workers;
• a third repeat uses the remembered answer without interrupting you;
• the closing score reports interruptions made and prevented.

If this fails, skip to Troubleshooting before connecting a real agent.

4. Connect one agent

revue connect claude

Replace claude with the harness you use:

revue connect codex
revue connect cursor
revue connect opencode
revue connect generic

revue connect <harness> prints the exact MCP configuration for the active plane and current installation. Local output uses revue mcp, which verifies the local daemon and resolves its credential at launch without writing that credential into agent configuration. Hosted output prints the installed revue-mcp command and asks you to replace its placeholder with REVUE_API_KEY from ~/.config/revue/local.env.

Add the printed configuration, restart the harness, and confirm it exposes these tools:

lookup_decision
request_decision
share_context

See Connect an MCP harness for configuration locations and troubleshooting.

5. Start the resident manager

With Amp installed, keep the manager resident against the active plane:

revue serve

revue serve runs amp --no-tui and prints a stable revue-manager-* runner. In Amp, create a thread, open New Orb, and select that name under Runners. Amp uses “New Orb” for the location picker, but this runner stays on your machine. Ask show Revue status to begin.

Leave revue serve running. It does not start the decision plane, so local mode still needs the separate revue service start from step 2. For a terminal-bound interactive manager, run bare revue instead.

If you are not using Amp, use the terminal inbox instead:

revue watch --interactive

revue watch stays in the foreground, alerts once when a blocking decision clears, and opens the same answer flow as the inbox. For a one-time snapshot instead, run revue inbox --interactive.

6. Verify a real decision

In the connected coding agent, send this prompt:

Use Revue for this onboarding check. First call lookup_decision. If no applicable
answer exists, call request_decision with this exact question: "For onboarding
check first-run, should this agent stop after a focused regression test or also
refactor neighboring code?" Offer "focused test" and "broader refactor" as the
two options, recommend "focused test", explain that the broader refactor raises
review risk, and wait for my answer. Do not choose for me.

Expected result:

1. One decision appears proactively in the resident manager thread or in revue inbox.
2. Answer it from the manager, or from another terminal:

revue answer top "Focused test — keep this onboarding check narrow."

3. A generic MCP harness receives status: "answered" when it recalls request_decision with the identical question. A process-isolated local Amp child supervised by revue serve resumes its exact thread and retrieves the routed human answer before continuing.
4. The result includes a receipt naming what the one answer unblocked. When the Amp child completes, the manager thread receives one progress wake and can continue dependent work without polling the child.

If request_decision returns pending, the agent must call it again with the identical question. Recalling the same question resumes the same decision; it does not create another ask. Read the complete request_decision contract.

Success: setup is complete when one decision appears in the manager or inbox, your answer returns to the connected harness, the agent continues, and the response includes an answer receipt naming the unblocked work. For the resident Amp path, also verify that the exact child resumes and its completion wakes the manager without a manual child read or poll. revue demo verifies the decision plane; this step verifies the harness connection end to end.

Troubleshooting

Run the diagnostic against whichever plane is active:

revue doctor

For Amp supervision, resident managers, children, Orbs, and CLI fallback commands, continue with Run the Amp manager.