Amp plugin API

The Amp plugin is Revue's product surface. It registers Revue tools inside Amp and a revue custom mode that tells the agent when to reuse memory, when to publish cheap context, and when to bid for human judgment.

Custom `revue` mode

The plugin registers a revue custom agent mode. Select it when you want the normal Amp coding loop plus Revue's human-context discipline. The mode keeps all Amp tools available and uses Revue-specific instructions for memory lookup, attention bids, and routed answers.

Set REVUE_AGENT_MODEL to override the mode's model. If unset, the plugin uses openai/gpt-5.5.

Default tool surface

Normal Amp users get only the Revue attention and memory tools:

Tool	Use
`revue_plugin_status`	Report plugin/runtime compatibility and the active tool surface
`revue_context_event`	Send compact progress, evidence, risk, or handoff context
`attention_market`	Read the current price and cleared decision state
`attention_account`	Read this thread's credit balance and regeneration state
`decision_lookup`	Search prior human decisions before spending attention
`radio_query`	Search shared context from other threads
`radio_publish`	Publish cheap shared findings without spending attention
`attention_bid`	Ask the human a structured decision question

Bridge-specific tools are not shown by default. They appear only when the plugin is explicitly bound to an advanced bridge session or REVUE_ENABLE_LINEAR_TOOLS=1 is set.

Required pre-bid order

Every agent should follow this order before spending attention:

attention_market
attention_account
decision_lookup
radio_query
if reusable decision applies:
  apply it and continue
else:
  attention_bid

Only attention_bid spends credits. Reads are free.

Bid shape

Good bids are answerable without opening a transcript. Include:

Field	Why it matters
`question`	The decision to answer
`options`	Concrete possible answers; objects can include `label`, `value`, and `consequence`
`recommendedDefault`	The path the agent will take if the human agrees
`risk`	What can go wrong
`reversibility`	How easy it is to undo
`costOfWaiting`	Why this deserves attention now
`costOfWrongDefault`	What happens if the agent guesses wrong
`evidence`	Compact evidence the human can trust
`concepts` / `files`	Scope used for grouping and future reuse

Bidding is non-blocking. The answer returns later as a message that begins Human decision:.

Delivery modes

settlementMode controls how forcefully an answer comes back:

Mode	Behavior
`queue`	Append the answer for the agent to pick up naturally
`steer`	Append with steer semantics so the current thread changes direction sooner
`interrupt`	Highest-force mode for urgent judgment

The plugin reports the deepest route state it can prove: delivered, consumed, applied, resolved, or failed.

Install

Install Revue once:

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

That command installs or updates Revue at ~/.local/share/revue/source, installs the plugin and bidding skill once in user config, writes ~/.local/bin/revue, and prepares ~/.config/revue.

Connect one workspace-scoped API key, then launch the manager Amp session:

revue login
revue

Bare revue syncs the plugin/skill, mints a short-lived manager delegation, sets PLUGINS=all, and starts Amp in Revue manager mode. The manager thread can then launch Revue-supervised local children and remote Orbs.

From a Revue checkout, the equivalent developer command is pnpm run revue.

The plugin source of truth remains .amp/plugins/revue.ts; you can install it manually when needed:

scripts/install-revue-plugin.sh             # user-level install
scripts/install-revue-plugin.sh --workspace # repo-local development install

Amp loads plugins only when PLUGINS=all is set. revue sets that automatically from the generated launch env. The env also includes REVUE_ENABLE_GLOBAL_APPEND_DELIVERY=1 so user-level plugin installs can append routed answers.

Runtime environment

For fallback local runtime/dev paths:

Variable	Purpose
`PLUGINS=all`	Required for Amp plugin loading
`REVUE_RUNTIME_URL`	Local runtime URL, default `http://127.0.0.1:47838`
`REVUE_RUNTIME_TOKEN`	Token printed or provided when the runtime starts
`REVUE_AGENT_MODEL`	Optional model for the `revue` custom mode
`REVUE_ENABLE_GLOBAL_APPEND_DELIVERY=1`	Set by local setup for user-level plugin installs that should append routed answers

Hosted-service variables are written by revue login and the manager launcher. Do not paste those raw values into prompts.

Local CLI

The first UI is the manager Amp thread. The CLI remains scriptable backup glue:

revue
revue doctor --remote
revue smoke
revue ui
revue watch
revue rpc
revue inbox
revue answer top "Use the recommended default."
revue threads
revue steer latest "Follow up on the completed task."
revue archive latest

latest resolves to the newest unarchived Amp workstream observed by Revue.

Verify

pnpm run test:revue-plugin
pnpm run test:hcm-sdk-swarm
pnpm run test:gate:headless

The plugin contract test proves tool registration and routing behavior. The headless gate proves the full Amp transport against the real CLI when available.