Pneuma Session

Refining your session's identity

Every Pneuma session has a row in the launcher (Recent Sessions) and inside its project (ProjectPanel). The row has two slots:

• Title — defaults to "<Mode> session" (e.g. "WebCraft session"). Mode-only.
• Description / preview — defaults to the first user prompt. For project sessions, the first prompt is the server-emitted <pneuma:env reason="opened" /> synthetic tag — which carries zero information for a human scanning the list.

Until you refine, both fields are placeholders. Three "WebCraft session" rows look identical except for their thumbnails. The user has to remember by time, which they won't.

This skill is how you fix that. You write a meaningful title + one-sentence summary into <sessionDir>/session.json, and the launcher row updates in place. The data persists across reopens; the launcher's own listing always reads from your last refine.

The mechanism

$PNEUMA_CLI session refine --json '{"displayName": "<≤40 chars>", "description": "<≤280 chars>"}'

Always call through the $PNEUMA_CLI env var, not the literal pneuma binary. The env var resolves to the right invocation regardless of how Pneuma was installed (npm-global, dev worktree, desktop bundle); writing the literal pneuma session refine only works when the binary happens to be on PATH, which it usually isn't inside the agent's sandbox. $PNEUMA_CLI is a single executable path, so the call behaves the same in bash, zsh, and fish, quoted or unquoted.

The command POSTs to the running Pneuma server (via $PNEUMA_SERVER_URL), which atomically rewrites <sessionDir>/session.json, syncs the global registry at ~/.pneuma/sessions.json, and broadcasts an event so any open browsers refresh the row without a reload.

Both fields are optional. Sending just displayName rewrites only the title; just description rewrites only the summary. Send both when the session has changed enough to warrant a fresh pair. The server validates lengths and rejects empties.

Run it from your default Bash tool. It's a one-shot HTTP call — no background process, no follow-up needed. On success the command prints Session meta refined. and exits 0; on failure it prints the server's error to stderr and exits non-zero.

What goes in each field

The goal is to make the row useful to a human scanning a list a week from now. Two principles:

Describe the session, not the work. The row is a session identifier, not a worklog. Write what the session is about, the user-facing concern, not the sequence of edits you made.

Match the user's register. If the user has been writing in Chinese, the refined title should be in Chinese too — they're scanning their own list. If the project's displayName in project.json is English, English is fine. Read the room.

displayName (≤40 chars)

The new title. Short. A scannable label, not a sentence. Capitalize as you would a headline. No trailing period.

Replacement, not augmentation — the mode is shown via the row's icon (and a hover tooltip), so don't prefix with "WebCraft · ". Just the topic.

Good shapes:

• 加载状态卡片调研
• Hero section iteration
• Pricing page · v3 layout
• 负熵痕迹 · 写作框架

If the user has explicitly renamed the session (via --session-name or a future rename UI), your displayName is recorded but the explicit name still wins in the listing — user intent beats inference. You don't need to detect this; the server handles precedence.

description (≤280 chars)

The new summary. One or two sentences. Should fit on one line in the row, with the second sentence as overflow on hover. Plain prose, no markdown.

Tell a user re-encountering this row in a week: "what was I doing here?" and "should I open it?". Concrete enough to disambiguate from sibling sessions, abstract enough to survive minor reshuffles.

Good shapes:

• Iterating on three loading-state card variants for the dashboard's data-fetching screens. Picked a skeleton + shimmer combo; still tuning the timing curve.
• Drafting the hero section for the launch site. Brand voice: "calm and clinical and careful". Holding on grayscale palette until copy lands.
• 负熵痕迹（写作框架）的第一稿,聚焦"代码 agent 留下的 entropy 痕迹"这条主线。结构定了三段,标题待定。

When to refine

You'll find two natural triggers. Both go through the same CLI; only the framing differs.

When the user asks

Phrases like:

• "整理一下会话信息"
• "重新概括下这个 session"
• "refresh the title / summary"
• "rename this session based on what we've done"
• "give this session a real title"

Run $PNEUMA_CLI session refine synchronously (no subagent). The user is asking right now; they're waiting for confirmation. Read the conversation so far, compose displayName + description, call the CLI, then reply with a one-line acknowledgment showing the new title.

On your own judgment

The intent here is: when the row would actually be more useful with a refined title than the default, refine. When it wouldn't, don't. Default to not refining — premature refines write a title before the session has a clear shape, and you'll either churn it later or leave a misleading row.

Strong signals to refine:

• The conversation has gone past a clear inflection point: a brief was agreed, a direction was picked, a deliverable was produced. The session has a topic now.
• The user has been working for a while (rule of thumb: 15+ substantive user turns, or 3+ artifacts produced), and the default title is still "<Mode> session".
• You hit a milestone the user will care about — a feature shipped, a draft completed, a critique pass finished — and the row should reflect the new state of play.

Weak signals (don't refine on these alone):

• A single message was exchanged.
• The user is still in the discovery / interview phase (their intent isn't settled yet).
• You wrote one file but the session's purpose is unclear.

When you decide to refine proactively, use a subagent so the main turn isn't blocked. Use the active harness's delegation tool, when available, to create a fresh worker that reads the project atlas + the conversation so far and writes the refined fields. Pattern:

1. Identify that a refine would be useful.
2. Launch a subagent with the available delegation tool. Brief it:
   - "Read $PNEUMA_PROJECT_ROOT/.pneuma/project.json and project-atlas.md."
   - "Read the current conversation transcript above this prompt."
   - "Compose displayName (≤40 chars) and description (≤280 chars) describing
      what this session is *about* — the user-facing concern, in the user's
      language. Don't list what was done."
   - "Run: $PNEUMA_CLI session refine --json '<your json>'. Print the result and stop."
3. The subagent returns; you don't need to mention the refine to the user
   unless the user asks. The row updates silently.

If delegation is unavailable in the active harness, do the refine inline at a natural pause — between two unrelated turns, or right before you hand the conversation back to the user with a question. Don't refine mid-task; the user is watching you work.