sidewalk

Your agent builds something, then writes the checklist for you to walk. Cards open in a Chrome side panel next to the live site. Each one says where to go and what to look for. Answer it, and the answer goes back to the agent with a screenshot and your exact words.

The agent writes the walk through an MCP. Your answers come back to it as data.

Install

Node 22 and Chrome. Two lines:

npx -y sidewalk-walkd serve
claude mcp add --scope user sidewalk -- npx -y sidewalk-mcp

Then the extension: sidewalk on the Chrome Web Store, or the same add-on on Firefox. To build it from a checkout instead: npx -y npm@11 install && npm run build, then chrome://extensions → Developer mode → Load unpacked → packages/extension/dist.

walkd makes a token the first time it starts and answers only a caller that has it. Your agent reads it from walkd's own folder. The panel cannot read files, so it asks walkd for the token through the browser. Press Connect in the panel and allow it once; after that the panel picks the token up by itself. The small native messaging host that answers is written at every walkd start.

If your browser cannot reach that host, the token is on your clipboard for a short while after walkd makes it, and npx -y sidewalk-walkd token --copy puts it back. Paste it into the panel's gear. A restart serves the same token, so that is one paste.

Works on macOS, Linux and Windows. MANUAL.md §1–§3 has the longer version, including the JSON form of the MCP entry.

One line

It installs both packages, starts the daemon, and puts the token on your clipboard:

curl -fsSL https://sidewalk.sh/install | sh

From a checkout

npx -y npm@11 install
npm run build
npm start                       # walkd on 8760
# chrome://extensions → Developer mode → Load unpacked → packages/extension/dist
claude mcp add --scope user sidewalk -- node /absolute/path/to/packages/sidewalk-mcp/bin/sidewalk-mcp.js
node packages/walkd/bin/walkd.js token --copy   # only if Connect cannot: paste it into the gear

As a Claude Code plugin

It adds the MCP server and the walk-author skill, with no file path:

claude plugin marketplace add kesensoy/sidewalk
claude plugin install sidewalk@sidewalk

There is no walkd serve on this path: the MCP server starts one the first time you run claude after installing. That daemon puts its token on your clipboard for a short while.

Open the side panel and press Connect; the browser asks once whether the panel may talk to walkd, and after that the panel picks the token up by itself. If that is not possible on your browser, the token is on your clipboard for a short while after walkd starts, and npx -y sidewalk-walkd token --copy puts it back.

Your agent will say the same thing if you ask it for a walk before the panel is open.

How it works

The agent opens a walk and adds cards to it, then blocks in walk_wait. Nothing can push to an agent, so that blocking call is how it hears you. You press Go on a card, do what it says, and answer: Pass, Issue, Skip, a decision on a question, or a question of your own back to the agent. The verdict lands in the agent's conversation with the page's screenshot and console tail attached, and the agent carries on.

Three pieces, one repo:

Piece	What it is
packages/walkd	the local daemon; two append-only streams per walk, HTTP + SSE on 127.0.0.1:8760
packages/sidewalk-mcp	the MCP server an agent session launches; six tools: walk_open, walk_add_items, walk_withdraw, walk_wait, walk_read, walk_close
packages/extension	the Chrome side panel (Manifest V3), on the Chrome Web Store or loaded unpacked from packages/extension/dist

What a card can do

The clips below are from the Lamppost demo, a four-page status site that exists to be walked. node demo/run.mjs runs the same walk on your own machine; demo/README.md says what each card is there to show.

Go

Press Go. It opens the page and points at the thing to check.

A sequence

One page, several steps in order, a tick for each. The verdict carries which steps were ticked, so an Issue says how far it got.

Tick each step as it works. If one breaks, say where.

Undo

An answer stays yours for ten seconds before any agent can read it. Its Undo is green in that window and one click takes the answer back as if it was never filed. Once an agent has it the Undo turns red and asks first.

Every answer has an Undo.

Secrets

A card can carry a key as a row of dots with a Copy button. The value is held in the daemon's memory only: it is not in the walk's record, not in the pane's DOM, and not handed back to the agent that wrote it. On a card that carries one, what the page shows goes back to the agent as a length, not as words.

Demo keys and test accounts only, never a production credential. The daemon's token is not a login: a program that can read your user's files can read a walk, or a value a card carries.

Secrets stay out of the chat and out of the screenshots.

Ask

Ask on any card sends a question to the agent. The card stays answerable while you wait, and the answer lands on the card itself, where the waiting line was.

Ask a question. The answer lands on the card.

The agent's side

Everything the agent does goes through the MCP server, as the reel at the top shows. Your verdicts come back to it as data, your words verbatim, and a question of yours arrives with the line that tells it to answer in the pane.

Read more

• MANUAL.md is the operator manual: running the daemon, adding the MCP entry, a walk from open to close, the item rules, testing.
• CHANGELOG.md is what shipped when.
• PRIVACY.md is what is stored where, and what is sent.
• plugin/skills/walk-author/SKILL.md is how to write a good walk. Agents get the same text as MCP server instructions the moment they connect.

Licence

MIT, see LICENSE.