Live agent loop

Live editing is an optional local development mode for active review sessions. An agent stays attached to the local artifact, receives new comments as they arrive, revises it, and publishes the next immutable version without asking anyone to copy feedback back into chat.

Publishing does not start this mode. The agent shares the review URL first and asks whether you want to enter live editing mode. Decline when you want to send the link to guests and collect comments asynchronously without keeping a local agent session active.

publish → listen → human comments → agent revises → publish again

Start listening

After opting in, run listen from the same artifact folder:

npx artifact-cafe@latest listen --json

listen is the live-loop entry point — the same thing as comments --wait, named for what it does. It does not run a local server or auto-republish on save; cutting the next version stays an explicit publish.

The command snapshots the comments that already exist, then waits for a new thread or a new reply. While it runs, the review page shows Agent is listening, so reviewers know feedback left now can be acted on now. When feedback is handed over, the indicator flips to Agent is editing, and publishing shows Agent is publishing — reviewers watch the whole loop.

What reviewers see

One pill, morphing through the agent's states as the loop runs:

The presence pill moving listening → editing → publishing. Each state is a heartbeat from the CLI; the pill fades once the agent goes quiet.

While the agent works, reviewers can keep reading and commenting — the pill just says what's happening.

When the agent publishes, an open review page follows the new version live: the artifact updates in place, on the same page and scroll position the reviewer was on, with a brief version tick as the only announcement.

A new version just landed: the pending section is now written, the reviewer hasn't moved, and nothing reloaded.

If the reviewer is mid-comment or browsing an older version, the page never switches under them — it offers a banner instead, and View latest swaps in place when they're ready:

Publishing early and often works well with this: each small immutable version streams to reviewers as it lands.

When feedback arrives, the command returns only the threads that changed:

{
  "artifactId": "art_123",
  "versionNumber": 1,
  "timedOut": false,
  "threads": [
    {
      "change": "new",
      "id": "thr_123",
      "author": "Mia",
      "versionNumber": 1,
      "status": "open",
      "anchor": {
        "type": "text",
        "elementPath": "html > body > main > section:nth-child(2)",
        "startOffset": 0,
        "endOffset": 10,
        "quote": "Week 4: 9%"
      },
      "body": "Are trials filtered out of this cohort?",
      "createdAt": "2026-07-11T09:30:00.000Z",
      "replies": []
    }
  ]
}

The agent receives the comment together with its version and text or element anchor. It can inspect the exact part of the artifact the reviewer meant rather than interpreting a detached message. Comments stay attached to the version they were made on — later versions never silently rewrite an earlier discussion.

Run the complete loop

# 1. Publish and share the review URL
npx artifact-cafe@latest publish . --json --no-open

# 2. Wait for new reviewer feedback
npx artifact-cafe@latest listen --json --timeout 540

# 3. Revise locally — refresh the "Agent is editing" indicator as you work
npx artifact-cafe@latest status editing

# 4. Publish the next immutable version
npx artifact-cafe@latest publish . --json --no-open

# 5. Listen again while review continues
npx artifact-cafe@latest listen --json --timeout 540

After the first comment arrives, the command waits briefly so a burst of reviewer comments returns as one batch. A successful feedback result exits with code 0. If no feedback arrives before --timeout, it returns "timedOut": true and exits with code 2. Start another listening window only when the user confirms they want to continue live editing.

Requirements and boundaries

• Run the command from a folder already linked by artifact-cafe publish, or point it at the artifact directly with --artifact <id> (or ARTIFACT_CAFE_ARTIFACT_ID) plus ARTIFACT_CAFE_TOKEN — so the agent can listen from CI or a different machine than the one that published.
• Treat live editing as an explicit, temporary session; publishing and guest commenting continue to work without it.
• listen uses the Node CLI; the bash comment helper only performs one-time pulls.
• The publish token (from the folder or ARTIFACT_CAFE_TOKEN), or a signed-in account key, authorizes presence heartbeats and access to a password-protected artifact.
• Presence is ephemeral. The indicator disappears shortly after the command stops.
• Use a timeout shorter than the execution limit of the agent environment.

See the CLI reference for every flag and Reviewing for the human side of comments, anchors, threads, and versions.