Skip to Content
GuidesChat

Chat

Chat in the web UI’s sidebar lists every conversation you have with Shep and its agents, and opens one full height next to the list. Use it to start work, steer a feature, and answer what agents ask. Features still run in their own worktrees with their usual gates; the chat is another way to drive them, not a replacement for that pipeline.

The Chat page: conversations grouped as Shep, Repositories, Features and Applications on the left; on the right the Shep conversation with an inline spec review, an HTML preview of a pricing card, and a plan card

Conversations

The list is grouped by what the conversation is about. Each row shows a dot while the agent is working on a turn.

GroupConversationThe agent works in
ShepOne global conversation about all your workShep’s home folder (~/.shep, or $SHEP_HOME)
RepositoriesOne per repositoryThe repository
FeaturesOne per feature that isn’t archived or deletedThe feature’s worktree
ApplicationsOne per appThe app’s repository

The URL is /chats for the list and /chats/<scope> for one conversation. A feature conversation shows the feature’s lifecycle and an Open on canvas link to its drawer in the Control Center, so the chat and the pipeline stay two views of the same work.

The Shep conversation is the place to start: ask for a change, and the agent creates a feature with shep feat new. The feature then runs in its worktree and appears in the list.

The same conversations appear elsewhere:

  • The Chat tab in a feature’s drawer and in a repository’s drawer.
  • A floating chat window on every page for the Shep conversation. Toggle it with Cmd+Shift+K (macOS) or Ctrl+Shift+K, and maximize it with Cmd/Ctrl+Shift+M.
  • o in the terminal console opens a feature’s conversation in your terminal.

Which agents can chat

Chat needs an agent with interactive sessions:

  • Claude Code
  • Cursor CLI (through cursor-agent acp)

The chat uses the agent selected in Settings. With any other agent configured, sending a message fails with “Agent does not support chat sessions yet”; pick Claude Code or Cursor CLI in Settings and send it again. Background feature runs are not limited this way: they work with every supported agent.

Each chat runs a persistent agent process. Under Settings → Interactive Agent you can turn the Chat tab off, set the idle Auto-timeout (15 minutes by default) and the Max concurrent sessions (3 by default, 1–10).

Blocks the agent can show you

Besides text, an agent can put four kinds of interactive blocks in the conversation. Once you answer one, it shows the outcome (“Approved”, “Changes requested: …”, “Implementing”, “Refining: …”) and its buttons are gone, also after a reload.

Spec review

A spec or PRD in Markdown with Approve and Request changes. Request changes asks for a note saying what to change.

A spec review block titled Dark mode toggle: a one-line summary, In scope and Out of scope lists, a metrics table with targets, and Request changes and Approve buttons

HTML preview

A self-contained HTML page, rendered in a sandboxed frame so you can look at a component before it is built into your app. Source shows the HTML and the expand button opens a larger view.

An HTML preview block titled Pricing card showing a Pro plan card with a Choose Pro button, with Source and expand controls and the note "Runs in a sandbox with no network access"

The frame runs scripts but has no network access and no access to the Shep page around it. Images and styles from the internet don’t load, so agents inline their CSS and scripts.

Plan

A plan in Markdown with Implement and Refine. Refine asks for a note.

A plan block titled Add dark mode listing four numbered steps, with Refine and Implement buttons

Decision

A question with options, a recommended option and room for your own answer. This is how agents ask you things in chat; it’s the same panel as everywhere else in Shep. Press 1–9 to pick an option. See Decisions & agent questions.

Your answer to any block is stored in the conversation and sent to the agent as a plain message, for example “The user approved the spec … Continue with it.” That works with every agent and survives restarts.

Approving a spec review in chat tells the chat agent; it does not by itself pass a feature’s approval gate. The agent then runs shep feat approve for you, or you approve in the feature drawer, the terminal console or with shep feat approve <id>.

Post a block yourself: shep chat block

Agents post blocks with a CLI command, so it works with any agent that has a shell. You can run it too, for example from a script.

shep chat block spec-review --title "Login PRD" --file specs/login.md shep chat block preview --title "Pricing card" --file pricing.html shep chat block plan --title "Add dark mode" --content "1. Add color tokens 2. Add a theme toggle"
Argument / optionMeaning
<kind>spec-review, preview or plan
--title <title>Title in the block header (up to 200 characters)
--file <path>Read the body from a file: Markdown, or HTML for preview
--content <text>The body as text. Pass exactly one of --file and --content
--scope <conversation>The conversation to post into. Defaults to $SHEP_CHAT_SCOPE

Every chat session sets SHEP_CHAT_SCOPE, so an agent never needs to know which conversation it is in. Outside a chat, pass --scope: global, repo-<repository id>, app-<application id>, or a feature id. Bodies are capped at 64 KB of Markdown or 256 KB of HTML. A block posted from another process appears in an open chat without a reload.

From an MCP client: post_chat_block

Shep’s MCP server (shep mcp) offers the same thing as the tool post_chat_block:

InputMeaning
scopeglobal, repo-<repository id>, app-<application id> or a feature id
typespec_review, plan_card or html_preview
titleTitle in the block header
markdownBody for spec_review and plan_card
htmlA self-contained HTML document for html_preview

The user’s answer arrives in the conversation as their next message.

See also