Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"planboard": patch
---

The session overlay gives the lists more room: the totals sit beside a shorter chart that you can widen or hide. Call lists preview two lines with More, and the timeline can show only your messages. Idle gaps longer than the prompt cache break the chart and the timeline, with clock times on both sides. The timeline shows each tool's kind and what it touched, your messages stand out, and the agent menu describes every subagent. Shell commands are split into statements and colored.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ The server is TypeScript run by `node --experimental-strip-types`. There is no `
| Outbound drafts (task assets with `outbound:` front matter): fields, the hash of the outgoing text, Approve and send through `outbound.send`, Send back, Drop, Mark sent (`/api/outbound/*`); the approval panel on a draft's page | `outbound.ts` (server), `public/outbound.js` (panel and its delegated handlers) |
| Steps page (`?view=steps`; lint rules in `stepErrors` and `draftErrors` in `check-planning.ts`; the Today plan's lead in `todayLeadHtml`, Outbox at `&kind=outbound`): open steps from every task's work breakdown with their next move (`deriveSteps`) and priority score (`scoreStep`, `downstreamCount`, `byPriority`; task `priority:` front matter written by `/api/steps/priority`), machinery files by `step:`, Pick on choices, Start with agent slots, Approve and run, Apply, Mark done (`/api/steps`, `/api/steps/{pick,start,run,apply,done}`); the `{kind, size}` suffix is parsed in `parseWorkBreakdown` | `steps.ts` (server; task folders are walked by `task-files.ts`, which skips symlinks and `node_modules`), `public/steps-page.js` (table, toolbar, inspector), `stepsIndex` and routes in `server.ts`, page wiring in `public/app.js` |
| Chat Threads page (`?view=chat-threads`): local Codex and Claude Code threads from session metadata, `lsof` and the Codex state database; spawned threads (`parent`) nest under their parent and do not count toward the history limit; model names and family colors in `modelInfo` | `chat-threads.ts` (server, `/api/chat-threads`), `public/chat-threads.js` (client) |
| Session overlay (`?session=claude:<id>` or `codex:<id>`): one Codex or Claude Code log read in full (requests with token use and what the agent said, tool calls with IDs, arguments, durations and errors, user messages, model, effort and compaction marks, subagents), served by `/api/chat-session`; Findings (failed and retried calls, loops, rereads, large results, cache misses, slow calls), timeline by turn, tools, files, agents and notes beside an inspector; notes on tool calls in `reference/session-notes/` (`/api/session-notes`), and Review with an agent (`/api/session-notes/prompt`, `prompts/session-review.md`); opened from a Chat Threads token count and the chart button `sessionButton` adds beside chat links. `examples/agent-logs/` is fictional logs from `scripts/agent-logs-sample.mjs` | `agent-session.ts` (server), `public/session-findings.js` (detectors, run under Node in tests), `session-notes.ts`, `public/session.js` (client), `session` entry in `OVERLAYS` |
| Session overlay (`?session=claude:<id>` or `codex:<id>`): one Codex or Claude Code log read in full (requests with token use and what the agent said, tool calls with IDs, arguments, durations and errors, user messages, model, effort and compaction marks, subagents), served by `/api/chat-session`; Findings (failed and retried calls, loops, rereads, large results, cache misses, slow calls), timeline by turn, tools, files, agents and notes beside an inspector; notes on tool calls in `reference/session-notes/` (`/api/session-notes`), and Review with an agent (`/api/session-notes/prompt`, `prompts/session-review.md`); opened from a Chat Threads token count and the chart button `sessionButton` adds beside chat links. `examples/agent-logs/` is fictional logs from `scripts/agent-logs-sample.mjs` | `agent-session.ts` (server), `public/session-findings.js` (detectors, run under Node in tests), `session-notes.ts`, `public/session.js` (client: chart with idle breaks, agent menu, timeline), `public/shell.js` (shell one-liners split into statements and colored), `session` entry in `OVERLAYS` |
| Setup page (`?view=setup&tab=&item=`; four tabs, each one list in a shared row grid beside an inspector, the Code-view toolbar and split): live integration checks (`gh`, `acli`, Linear, Slack, Codex app server, draftably, agent apps), every `config/viewer.json` key with its meaning read from `docs/configuration.md` (a key missing there fails `setup.test.ts`), scalar edits and Reset (`/api/setup/config`), the Config files list and read-only view (`/api/setup/file`, never `config.toml`), helper prompts through the note popover (`/api/setup/agent`), and Getting started at the top while the workspace has no daily plan or no task (`gettingStarted`, `firstTaskPrompt`; boot opens Setup then) | `setup.ts` (server), `public/setup-page.js` (client) |
| Prompt templates: every agent prompt the server builds (handoffs, work items, PR notes, worktree cleanup, Plans Update and Retire, Slack Discuss, and the `routine: true` daily plan, daily review and Up next sweep that the Setup page Starts through `routinePrompt` in `setup.ts`) is `prompts/<id>.md` with `{slots}`, overridden by the workspace's `config/prompts/<id>.md`; builders call `fillPrompt`. Change the words in the `.md`, not in code | `prompts.ts`, `prompts/` |
| Codex Desktop deep links | `codex-desktop.ts` |
Expand Down
18 changes: 9 additions & 9 deletions docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,24 +54,24 @@ The list shows every live thread and the 50 most recent finished top-level threa

The session overlay reads one Codex or Claude Code session's log in full, so you can see what the agents did, where the tokens and time went, and what went wrong. Open it from a thread's **Tokens** number on Chat Threads, or from the chart button beside a Codex or Claude Code chat link in a document (a task's `## Chats` list, for example). The URL keeps it open: `?session=claude:<session id>` or `?session=codex:<thread id>`, with `session-tab`, `session-agent` and `session-pick` for the tab, agent and selected row.

- **Header.** The session's title, the models and effort levels it used in order (`Opus 5.5 · medium → high`), its folder, branch and start time, **Review with an agent**, and **Open in Claude** or **Open in Codex**.
- **Totals.** Cost, requests, input, the share read from the prompt cache, output, the largest single prompt, tool calls with failures, turns (messages you typed), subagents, duration, and **Waiting on you**: the time between the agent's last step and your next message. Cost is Claude Code's own total when the transcript has one; otherwise it is an estimate from public API prices, marked **est.**, and a dash when the model has no known price. Hover a number for the exact count.
- **Chart.** One bar per model request, in order: the prompt stacked as cache read, cache write and uncached input, with output below the axis on its own scale. A blue line traces the running total of tokens. A dashed purple rule marks each compaction, a triangle on top marks each message you typed, a short label marks a model or effort change, and a red tick under a bar marks a failed call. A dotted line shows Codex's context window when the prompts come near it. Hover a bar for its numbers and what the agent said; click it to select that request in the timeline. While a finding is selected, its requests stay lit and the rest dim.
- **Header.** The chart runs to the top of the overlay. On its left sit the session's title, the models and effort levels it used in order (`Opus 5.5 · medium → high`), its folder, branch and start time, and the totals. The bar above the chart starts with **Review with an agent** and **Open in Claude** or **Open in Codex**, then the chart buttons, then the key, with × at the far right.
- **Totals.** Under the title, in four columns: cost, requests, input, the share read from the prompt cache, output, the largest single prompt, tool calls with failures, turns (messages you typed), duration, and **Waiting on you**: the time between the agent's last step and your next message. Cost is Claude Code's own total when the transcript has one; otherwise it is an estimate from public API prices, marked **est.**, and a dash when the model has no known price. Hover a number for the exact count. The chart buttons widen it to the full width and a taller plot (the totals go on one line above it), put it back beside the totals, or hide it (then **Show chart** in the bar shows it again). The choice is kept in this browser.
- **Chart.** One bar per model request, in order: the prompt stacked as cache read, cache write and uncached input, with output below the axis on its own scale. A blue line traces the running total of tokens. A dashed purple rule marks each compaction, a triangle on top marks each message you typed, a short label marks a model or effort change, and a red tick under a bar marks a failed call. A dotted line shows Codex's context window when the prompts come near it. When no request ran for longer than the 5-minute prompt cache, the bars break with a hatched gap that names its length (`9m`, `4h12m`): amber when the next request had to write the context again, gray when the cache held. Breaks share at most a fifth of the chart, so a long session keeps its longest gaps as breaks and marks the rest with a short tick on the axis. A session longer than a day adds the date to the clock labels where it changes, and many messages show as thin ticks instead of triangles. Clock labels sit at both ends of the chart and on both sides of every break, so a jump in time reads as one. Every bar in **All agents** carries its agent's color at its foot. The key sits above the plot. Hover a bar for its numbers and what the agent said; click it to select that request in the timeline. While a finding is selected, its requests stay lit and the rest dim, and the bar says **Highlighting** with the finding's name (in place of the key) and × to clear it.
- **Findings.** The tab the overlay opens on when it finds something, grouped as Problems, Waste and Worth a look, each with a token estimate (characters ÷ 4, counted again for every later request that carried them):
- a tool that failed, and whether it was run again with nothing changed in between;
- the same call three or more times in a row with no edit between them (polling, or a loop);
- the same call three or more times in a row with no edit between them (polling, or a loop); runs of one check at different times make one finding, even when its arguments vary (it counts the variants);
- a file read again with no change to it in between, and a subagent reading a file its parent had already read;
- results over about 5k tokens, and how many later requests carried them;
- cache misses, where a request sent most of its prompt again (usually after an idle gap longer than the cache keeps a prompt);
- calls that took over a minute, and a context near its window.

Select a finding to see what it means and what usually does better, with its calls; click a call to see it in the timeline, where the finding's rows stay tinted until you clear it with × in the toolbar.
- **Timeline.** Your messages head each turn with its requests, calls, failures, time and cost. Below each, requests in time order with what the agent said before acting, the tools it called (a count for repeats, a red alert for a failure, a pen for a call you noted), the prompt size, the share read from cache, new input and output. Compactions and model or effort changes sit between them.
- **Tools.** One row per tool: calls, failures, total, median and longest time from call to result, and the tokens its results returned, with a bar for comparison. Select a tool to list every call.
A finding's detail shows two lines in the list and four in the inspector, with **More** when it runs longer; calls are named by their command (without a leading `cd`), file, pattern or title, never raw arguments, and slow calls list the slowest first. Select a finding to see what it means and what usually does better, with its calls (in the same two-line form as on the Tools tab); click a call to see it in the timeline, where the finding's rows stay tinted until you clear it with × beside **Highlighting** in the chart bar.
- **Timeline.** Your messages head each turn on a blue tint: the turn number above its time, your message (two lines), and the turn's requests, calls, failures, time and cost on the right. Below each, requests in time order, one line where they fit: **Said** is what the agent said before acting (two lines at most, Markdown marks removed), and **Did** lists the tools it called, each with an icon for its kind (read, edit, shell, search, subagent, web, MCP), a count for repeats, and what it touched in monospace: the programs a shell call ran (`git head tail`, leaving out `cd` and the text of a heredoc), a file's name, or a search pattern. A red alert marks a failure and a pen a call you noted. The numbers are the prompt size, the share read from cache, new input and output; the cache share turns amber and bold under 50%, and new input over 20k is bold. Compactions, model or effort changes, and idle gaps sit between them: striped and amber when the cache expired, and gray for a gap of 30 minutes or more that the cache rode out. Automation runs, whose messages arrive as tagged text, read as "Automation · <name>" with their instructions, and the agent's reply as **Quiet** or **Notified** with its message. A message that repeats an earlier turn's shows as one line marked "same as turn N". In **All agents**, each row names its agent with that agent's color. **Your messages only**, at the right of the toolbar on this tab, keeps just your messages, each with the agent's last word for that turn, so the list reads as the conversation; the inspector shows the selected turn.
- **Tools.** One row per tool: calls, failures, total, median and longest time from call to result, and the tokens its results returned, with a bar for comparison. Select a tool to list every call. Each call is two lines: the time, tool and duration, then what it ran, cut to two lines with **More** to read the rest. A shell call's leading `cd` shows as "in <folder>" beside the tool, and its command is formatted and colored as in the inspector.
- **Files.** Every file a tool read, edited or wrote, with counts per action, how many agents touched it, and when it was last touched. A file read more than once without a change is marked.
- **Agents.** The main agent and each subagent with its model, a strip of its activity on the session's clock (one tick per request), requests, cost, tool calls, findings and duration. Click one to scope the whole overlay to it; the **Agent** menu in the toolbar does the same, and **All agents** mixes them in time order (subagent bars show lighter). A spawning call in the inspector has **Open subagent**.
- **Agents.** The main agent and each subagent with its model, a strip of its activity on the session's clock (one tick per request), requests, cost, tool calls, findings and duration. Click one to scope the whole overlay to it. The agent button in the toolbar does the same: it names the agent in scope (and how many subagents there are), and its menu lists the main agent, then each subagent with its description, kind and model, requests, calls, failures, duration and cost, and a bar of when it ran on the session's clock. Up and Down move through the menu, Enter picks, and Esc closes only the menu. **All agents** mixes them in time order (subagent bars show lighter). A spawning call in the inspector has **Open subagent**.
- **Notes.** Notes you left on this session. **Note** beside any tool call in the inspector (or `N` with a request selected) asks what the call was for or what would have done better; **Note on the session** adds one about the whole run. Notes are saved in the workspace at `reference/session-notes/<claude|codex>-<id>.md`, one heading per note with the call's ID and first line, so the file reads on its own.
- **Inspector.** The selected request: the findings it is part of, what the agent said, and every tool call laid out for its kind (a shell command, an edit as a diff, a written file, a subagent's prompt, a search), with its duration, result tokens, result and your notes on it. Hover the line under the heading for the full token breakdown. A selected turn shows your message, the agent's last word and every call it made.
- **Inspector.** The selected request: the findings it is part of, what the agent said, and every tool call laid out for its kind (a shell command with one statement per line and colors for commands, flags, strings, paths and operators, a `cd` line dimmed; an edit as a diff, a written file, a subagent's prompt, a search), with its duration, result tokens, result and your notes on it. Hover the line under the heading for the full token breakdown. A selected turn shows your message, the agent's last word and every call it made.
- **Review with an agent.** Opens the note popover with a prompt (`prompts/session-review.md`) that hands an agent the log's path, the findings and your notes, and asks it to explain each one and propose the smallest lasting fix: an AGENTS.md rule, a skill, a script, a tool permission or a better prompt. **Save note** queues it for Up next; the clipboard icon copies it.

The filter (`/`) narrows the current tab by tool name, arguments, file path, message text or what the agent said. Up and Down move between rows. Claude Code sessions include each Agent-tool subagent's own transcript; Codex sessions include subagent threads from the state database. The overlay reads only this computer's logs (`~/.claude/projects` and `~/.codex/sessions`, or `CLAUDE_CONFIG_DIR` and `CODEX_HOME`); `examples/agent-logs/` holds fictional ones for the demo, made by `scripts/agent-logs-sample.mjs`.
Expand Down
Binary file modified docs/images/session.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading