StepBack

StepBack lets you review coding agent responses in a browser. You can select any passage, ask a separate read-only sub-agent about it, and send only the context you choose back to your Claude Code session, with your next prompt.

Your review stays separate from the main conversation. Claude Code does not see your side questions or their answers unless you add something to Carry back.

What you can do

• Read completed Claude Code responses in a clean browser view.
• Select text and ask questions about the response, project files, conversation history, or project documentation.
• Choose who answers: by default the same harness and model that wrote the response, or the Codex CLI for a second opinion.
• Continue a question with follow-ups or branch into a separate line of inquiry.
• Save a line of context for Claude Code to receive with your next prompt.
• Send that next prompt from the browser, with the context along, when Claude Code runs with StepBack's channel.
• Browse responses by project and session.

Requirements

• Node.js 22 or newer
• Claude Code, which is both the harness whose responses are collected and the default sub-agent
• Optional: the Codex CLI installed, signed in, and available as codex on your PATH, for questions that start with @codex
• Optional, for sending prompts from the browser: a Claude Code account on which channels are available. Channels are a research preview: on by default for Pro and Max, enabled by an administrator for Team and Enterprise, and not available through Bedrock, Vertex, or Foundry.

Install and start

Install StepBack globally:

npm install -g @johardi/stepback

Set it up in a project:

cd your-project
stepback init

Restart Claude Code if it was already running. Claude Code loads hooks and MCP servers when a session starts, so an existing session will not notice the new setup until it is restarted. To be able to send prompts from the browser, start it with stepback claude instead of claude; see Send a prompt from the browser.

Start StepBack:

stepback start --open

The server starts in the background, and the command returns once it answers. It keeps running after you close the terminal or end the Claude Code session, until you run stepback stop. The default server address is http://127.0.0.1:7486/.

Run stepback start --open from any project to open that project's page. When the server is already running, the command says so and opens the page without starting another.

Finish a response in Claude Code. It will appear in StepBack automatically.

Install StepBack globally before running stepback init. Do not use npx @johardi/stepback init: the saved hook can stop working when the temporary npx cache is removed.

Review a response

1. Select text in the response.
2. Type a question in the box that appears.
3. Press Enter. Escape closes the box instead.
4. Read the answer in the right-hand column.

The answering sub-agent runs with read-only access. It can inspect the project, the Claude Code transcript, and project documentation, but it cannot change files or run commands. Before it answers a new thread, StepBack cuts the reviewed response's own slice out of the transcript, with the prompt that started it, the reasoning and tool calls recorded for it, and its final message, so the sub-agent can read what happened without searching the whole transcript.

Each answer shows where its information came from:

• code - the current project files
• transcript - the Claude Code conversation
• spec - project documentation or specifications
• none - no documented answer was found

“No documented intent found” is a valid answer. It means the sub-agent checked the available sources instead of guessing.

A small line above each answer says who produced it, "Claude answered:" or "CODEX answered:". Hover over it to see the model.

You can ask follow-up questions in the field at the bottom of the answers column. Press Enter to send and Shift+Enter for a new line. To branch from an answer when you want to explore a different question without changing the original thread, select the branch icon under it, type the question, and press Enter. Escape closes the field without sending.

Choose who answers

By default, a new question is answered by Claude Code running the same model that wrote the response. Nothing extra has to be installed for that.

Put @codex anywhere in a question to have the Codex CLI answer it instead, or @claude to insist on Claude Code. The tag has to stand as a word of its own, at the start, in the middle, or before a punctuation mark: "does @codex agree?" works. It is removed before the question is sent. An address such as [email protected], a domain such as @codex.com, and an escaped \@codex are ordinary text. When a question carries two tags, the first one decides.

Follow-ups stay with the sub-agent that answered last. Ask a follow-up with @codex or @claude to switch. When you switch, the new sub-agent receives the thread so far as question and answer text, so a second opinion can address what the first one said. When you switch back, the earlier sub-agent continues its own conversation and is told what the other one answered in between.

Both sub-agents receive the same instructions, the same forwarded conventions, and the same question. The only differences are how each CLI is started and kept read-only.

Carry context back to Claude Code

StepBack never sends the full review to your Claude Code session. You decide what crosses back.

The Carry back panel sits at the bottom right of the response, minimized to a bar that shows how many entries are pending. Select the bar to open it, and use its maximize control when the list grows. Each entry is context for the agent's next prompt: a decision you made while reading, in your own words.

1. Select Add context and type a line. Press Enter, or the return control in the field, to store it; the field closes and Add context is ready for the next one. Shift+Enter starts a new line; Escape, or the cross control, closes the field without storing.
2. Or select the carry-back icon under an answer. The answer is stored as an entry at once, and the icon shows it as carried; edit the entry if you want it shorter.
3. Send your next prompt in the same Claude Code session, in the terminal or from the browser.

Entries are numbered in the order they will cross.

Until it crosses, an entry can still change: select its text to edit it in place, press Enter to save, or Escape to leave it as it was. The remove control beside an entry drops it.

When you type the next prompt in the terminal, the pending entries are added to it as context, and the terminal shows them at the same moment, so you can see what crossed. After they cross, they leave the pending list. Side questions, sub-agent answers, and highlighted text are never included.

Send a prompt from the browser

When the session's Claude Code runs StepBack's channel, the panel also holds a prompt field. Type the prompt there and press Enter; Shift+Enter breaks a line. The prompt goes to that Claude Code session at once, followed by every pending entry under the same header the terminal path uses, and the entries leave the list. The terminal shows the message as one inbound line cut at the terminal's width, then, beneath it, the prompt in full and the entries it carried, introduced with "UserPromptSubmit says:" by Claude Code itself. Claude Code answers in the terminal as usual, and the finished response appears in StepBack like any other.

To run the channel, start Claude Code with:

stepback claude

It runs claude with the flag that enables StepBack's channel and passes every other argument through, so stepback claude --resume and stepback claude -p "..." work as usual, and its exit code is Claude Code's. Channels are a research preview of Claude Code, and a channel that is not one of Anthropic's own plugins is loaded with a development flag. Claude Code therefore shows a full-screen warning at each launch; choose to continue. The first time in a project it also asks for consent to use the new MCP server named stepback from .mcp.json; accept it. When channels leave the preview, StepBack will ship as a channel plugin and the warning goes away; stepback claude stays the command.

When a prompt cannot be sent from the browser, a line marked in red takes the field's place and says why and what to do: Claude Code was started without the channel, no channel is attached to the session yet, or the channel cannot be confirmed on your platform. The entries still cross with your next terminal prompt in every case.

A browser prompt is plain text to the model. Slash commands such as /compact, the ! shell shortcut, and @file completion are features of the terminal and do not apply, and permission prompts and questions from the agent still wait in the terminal.

On a Team or Enterprise account whose administrator has not enabled channels, Claude Code prints at launch that the channel is blocked by org policy and that inbound messages will be silently dropped. StepBack cannot see that: the panel still offers the field, and a prompt sent from it is lost together with the entries it carried. Until an administrator sets channelsEnabled for the organisation, send your prompts in the terminal.

Navigate projects and sessions

The home page lists every project that has sent a response to StepBack. Inside a project, the sidebar shows each Claude Code session as a tree: the session's title, and under it one line per response. Hover a response to see when it arrived. Select a session's title to collapse it; a collapsed session shows how many responses it holds. The header shows the project's name in the centre, its full path at the right, and a back arrow at the left that returns to the list of projects.

• A project page shows the newest response from any of its sessions and keeps following as new ones arrive.
• The menu at the right edge of a session row offers Follow this session, which follows new responses from that session only.
• Selecting a specific response pins it, so it stays open when newer ones arrive.
• The tag beside the project name says what the page follows. When the page is pinned or follows one session, select the tag to return to following the project.

If you are typing a question, an entry, or a prompt, StepBack will not replace the response in front of you. It will show a notice linking to the new response instead.

To remove a stored response, hover over it in the sidebar and select the × twice to confirm. Its review threads are removed too. The original response remains in Claude Code's transcript. A session's newest response cannot be removed on its own; it becomes removable once a newer response arrives.

To remove a whole session with every response in it, choose Remove session from the session's menu and confirm. The entries you carried back from that session are kept, because the terminal session may still be running. If the session sends another response later, it reappears.

Arrange the workspace

The workspace fills the browser window. The header stays at the top, while the sidebar, the response, and the answers each scroll on their own.

• Drag the edge of the sidebar or of the answers column to change its width.
• A handle also responds to the arrow keys, and to Home and End, once it has keyboard focus.
• Double-click a handle to restore the default width.
• The foot of the sidebar holds the control that hides it, a switch for the colour scheme, and the version.
• Hidden, the sidebar shrinks to a narrow rail that keeps both controls in the same corner.
• The colour scheme switch cycles through following your system, light, and dark.

The browser remembers the widths, whether the sidebar is hidden, the carry-back panel's state, and the colour scheme, so they survive reloads and apply to every project. On a narrow window the panels stack and the page scrolls as one.

The menu bar icon (macOS)

On macOS, stepback start also puts a StepBack icon in the menu bar. Its first menu entry reads "StepBack is running" or "StepBack is stopped", and hovering the icon shows the port and the server's version and process id. The menu offers:

• Open StepBack, which opens the server in your browser.
• Start and Stop, which run stepback start and stepback stop for you.
• Show log, which opens the server log.
• Quit, which removes the icon and leaves the server running.

Run stepback start to bring the icon back after quitting it. The icon runs its commands with the environment stepback start had when it launched the icon. After changing a setting, quit the icon and run stepback start again. The icon's own output goes to menubar.log in the state directory. Set STEPBACK_MENUBAR=off to skip the icon.

The icon is a script run by macOS's own JavaScript interpreter, osascript, so StepBack ships no compiled code for it and nothing has to be built or installed. STEPBACK_MENUBAR_BIN runs another program as the icon instead, with the same arguments; the repository carries a compiled Swift version under native/ for anyone who can sign it.

On Linux and Windows there is no icon and nothing is mentioned about one. The package installs the same way, nothing runs at install time, and every command works as described; the helper's files sit unused.

Set up more projects

Run stepback init once in each project you want to use. It:

• registers the required hooks in .claude/settings.json
• registers the channel server in .mcp.json, so stepback claude can send prompts from the browser
• installs the StepBack guidance file in .claude/skills/stepback/
• preserves settings, servers, and skills that do not belong to StepBack

If your server runs on a port other than 7486, pass it once: stepback init --port 7500 writes the port into the channel's entry.

To register the hooks in your user-level Claude Code settings instead, run:

stepback setup hooks

This updates ~/.claude/settings.json, so responses can be collected from every project. Project-level setup is still useful because it installs the guidance file for Claude Code.

If a Node version manager moves your global packages after you switch Node versions, reinstall StepBack and run stepback init again. This updates the hook to the new installation path.

Commands

| Command | Purpose | | --- | --- | | stepback init | Set up hooks, the channel server, and the guidance file in the current project. | | stepback init --port <number> | The same, for a server on another port. | | stepback init --dry-run | Show what setup would change without editing files. | | stepback claude [arguments] | Start Claude Code with StepBack's channel enabled, passing the arguments through. | | stepback start | Start the local browser app in the background on port 7486 and return. | | stepback start --open | Start the server, or find the one running, and open this project's page. | | stepback stop | Stop the background server and wait for the port to free. | | stepback status | Report whether a server is running, at which version and process id. | | stepback serve | Start the browser app in the foreground, until Ctrl-C. | | ... --port <number> | Any of the four above, on a different port. | | stepback setup hooks | Register hooks in your user-level Claude Code settings. | | stepback setup hooks --project | Register hooks in the current project's settings only. | | stepback setup hooks --dry-run | Check hook setup without editing files. |

The hooks use stepback ingest and stepback carry-back --emit automatically, and Claude Code runs stepback channel from .mcp.json. You do not need to run those commands yourself.

Configuration

Settings are read when the server starts. A background server keeps the environment it was started with, so after changing a setting run stepback stop and then stepback start.

Configuration is optional and uses environment variables.

| Variable | Default | Purpose | | --- | --- | --- | | STEPBACK_STATE_DIR | $XDG_STATE_HOME/stepback, or ~/.local/state/stepback | Where StepBack stores responses, reviews, and transcript slices. | | STEPBACK_SUBAGENT | parent | Who answers a question with no tag: parent (the harness that wrote the response, on its model), claude, or codex. | | STEPBACK_CLAUDE_BIN | claude | Claude Code CLI command to use for side questions. | | STEPBACK_CODEX_BIN | codex | Codex CLI command to use for @codex questions. | | STEPBACK_CLAUDE_MODEL | The reviewed response's model | Model for Claude Code answers. Set it to override the model recorded for the response. | | STEPBACK_CODEX_MODEL | Codex CLI default | Model for Codex answers. | | STEPBACK_DISPATCH_TIMEOUT_MS | 300000 | Maximum time in milliseconds for one answer. | | STEPBACK_CONVENTIONS_FILES | ~/.claude/CLAUDE.md, ./CLAUDE.md, ./AGENTS.md | Instruction files passed to the sub-agent. Use your operating system's path separator between files. | | STEPBACK_MENUBAR | on | macOS only. Set to off to keep stepback start from showing the menu bar icon. | | STEPBACK_MENUBAR_BIN | The shipped script, through osascript | macOS only. Another program to run as the menu bar icon, with the same arguments. |

Privacy and safety

• The browser server listens only on your computer's loopback address.
• Responses, review threads, transcript slices, and pending entries are stored locally in the state directory. A prompt sent from the browser is not stored.
• Side questions answered by Claude Code run in its restricted mode with only the file-reading tools available, no MCP servers, and every permission prompt denied, and with your user and project settings ignored so StepBack's own hooks never fire inside a sub-agent.
• Side questions answered by the Codex CLI run under its read-only sandbox.
• Claude Code receives only what you explicitly put in Carry back: the entries, and a prompt you send from there.
• StepBack saves the final message from each completed Claude Code response, not intermediate output produced while Claude is working.

Each sub-agent session is a real session of its CLI. Claude Code lists them in claude --resume under the project, named stepback: <your question>, so you can tell them apart from your own sessions and ignore them.

Each CLI still uses its configured model service to answer questions. Review the CLI's own configuration and data policies if your project contains sensitive information.

Troubleshooting

A response does not appear

Run stepback init in the project and restart Claude Code, with stepback claude if you send prompts from the browser. You can check the project hook without changing anything:

stepback setup hooks --project --dry-run

Both hooks should report unchanged when setup is current.

A side question fails

For a Claude Code answer, confirm that claude -p 'hello' works in your terminal and is signed in. For an @codex answer, confirm that codex works in your terminal and is signed in. If a command has another name or location, set STEPBACK_CLAUDE_BIN or STEPBACK_CODEX_BIN before starting the server. The error shown in the thread names the sub-agent and the setting to check.

For long-running questions, increase STEPBACK_DISPATCH_TIMEOUT_MS from its five-minute default.

Port 7486 is already in use

Run stepback status.

• "stepback ... is running at": the server is up. stepback start --open opens your project on it.

• "in use by something other than stepback": another program holds the port. Start on another port and open the address it prints:

  stepback start --port 7487

• "reads , not ": a server started with a different STEPBACK_STATE_DIR holds the port. Stop it with the same variable set, or use another port.

The server does not start

stepback start names the log file when the server exits before answering, and prints its last lines. The log is server.log in the state directory, ~/.local/state/stepback/server.log by default.

After upgrading or before uninstalling

A background server keeps running until it is stopped, even after the package is upgraded or removed. After upgrading, stepback start and stepback status say when the running server is from the older version; run stepback stop and then stepback start to switch. Run stepback init again in each project to refresh the skill it installed and the channel entry in .mcp.json. Before uninstalling, run stepback stop, and remove the stepback entry from each project's .mcp.json so Claude Code stops looking for it.

Development

git clone https://github.com/johardi/stepback.git
cd stepback
npm install
npm link
npm run check

npm link is optional. It makes the checkout's stepback command available on your PATH.

Two additional test modes are available:

STEPBACK_E2E_CLAUDE=1 npm test
UPDATE_SNAPSHOTS=1 npm test

The first runs the tests that use a real Claude Code CLI, the hook test and the restricted sub-agent test, and may use API credits. The second updates the Markdown rendering snapshot.

Planning documents are in openspec/.

License

MIT.

The icons in the browser interface are from Font Awesome Free, used under the CC BY 4.0 license.