3.7 KiB
The Workspace on the Web Console
Part of the web console contract (console.md). Read when open lists more
than one folder, a Workspace: line arrives, or someone writes @name.
The person can add folders beside the one the session started in (a shared
library, a design folder), from the footer's folder label. Together they are
the session's workspace: context for every skill run in this console
session, each folder addressed by a short @name. It outlives dashboard hops,
and it is remembered: every change is saved to workspaces.json beside
looks.json (never into the project), keyed by the folder the session runs
in and then by spec. A session with a spec opens on that spec's list, one with
none on the project's; a spec with nothing saved starts as a copy of the
project's list. The dashboard's picker swaps the list as the selection moves,
and a specDir you post mid-run takes the current list with it. There is
nothing for you to load: open prints the list, and a switch of spec on a
resume reaches you as ordinary workspace changes on your next wait.
What you are told
open (fresh or --resume) prints the whole list under workspace:
{ "ok": true, "sid": "…", "url": "…",
"workspace": {
"folders": [
{ "name": "shop", "path": "/home/sam/code/shop", "original": true },
{ "name": "shared", "path": "/home/sam/code/shared-ui", "description": "Button and form styles" }
],
"missing": ["old-docs"]
} }
missing (only when there is one) names folders no longer on disk. After
open, you hear only of changes, each exactly once:
waitexit0carries them beside a send or chat asworkspace: [...]({ kind, name, path, description?, from? },kindone ofadded,renamed,described,removed,missing,found), with oneWorkspace: …line each at the end ofreply(Workspace: added @shared — /home/sam/code/shared-ui). A change alone never ends a slice: exit10counts it aspendingWorkspaceand it rides on the next send.chathands changes over at once, with or without a Quick question, as{ chat, workspace, reply }.
Act on a change in the same turn it arrives: drop a removed folder, use the new name after a rename, note a missing one. No reply is needed unless the person asked something.
Rules
- Resolve
@namefrom the workspace list.@sharedin an answer, a note or a Quick question means that folder'spath. An@namenot in the list is ordinary text. - Added folders are read-only reference. Read them freely; edit one only
when the person asks for that change in this conversation. Chat edits still
need approval (
console-chat.md→ Edits need approval first). - Read an added folder's
AGENTS.mdbefore you first use it (CLAUDE.mdwhen there is noAGENTS.md), once per folder per skill run. It says how that folder is laid out; the original folder'sAGENTS.mdstill governs this project and the work.
When a folder cannot be read
When a read of an added folder genuinely fails (refused, not found), post, once per folder:
{ "folderIssue": { "name": "shared", "reason": "Permission was refused", "hint": "/add-dir /home/sam/code/shared-ui" } }
and print one terminal line saying which folder and why. The page marks the
folder and tells the person once. hint is optional: an agent that knows it
is Claude Code puts /add-dir <path> there. Your harness asking the person
for permission is not a failure; report only a read that failed after it.
A folderIssue needs non-empty name and reason strings, and hint, when
present, is one too; anything else is exit 3. It goes to the session's
ledger, never into the page state.