Repository navigation
docs(cli): document opening a specific agent session via deep link - #5032
Conversation
Document the previously-undocumented superset://v2-workspace/<id> deep-link query params (?chatSessionId= / ?terminalId= / &focusRequestId=) used to focus a specific agent session in the desktop app (ParadevAI#5029). - cli-reference.mdx: add "Opening a specific session" subsection under `workspaces open` with the kind->param mapping from `agents run --json`. - SKILL.md: add "Opening sessions in the desktop app" section plus a kind note in Agents and an `--agent superset` mention. The SKILL.md edit propagates to the bundled plugin (symlinked) and the marketing-served copy (read dynamically), so only the one tracked file changes.
|
Ready to review this PR? Stage has broken it down into 2 individual chapters for you:
Chapters generated by Stage for commit cdb7944 on Jun 5, 2026 9:40pm UTC. |
|
Capy auto-review is paused for this organization because the monthly auto-review limit has been reached. Increase the limit or turn it off in billing settings to resume automatic reviews. |
|
Too many files changed? Review this PR in Change Stack to see how the pieces fit before you dive in. No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (2)
📝 WalkthroughWalkthroughThis PR adds documentation for opening specific agent sessions via deep links in the Superset desktop app. It expands the ChangesAgent Session Deep-Link Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThis is a documentation-only PR that surfaces the previously undocumented
Confidence Score: 4/5Docs-only change with no runtime code altered; safe to merge. Both changed files are documentation. The deep-link params, kind values, and anchor references all check out against the source components. Minor style gaps (inconsistent placeholder casing between the two files, no end-to-end shell snippet showing how to extract sessionId from agents run --json) do not affect correctness. No files require special attention; apps/docs/content/docs/cli/cli-reference.mdx has small style inconsistencies noted in the comments.
|
| Filename | Overview |
|---|---|
| apps/docs/content/docs/cli/cli-reference.mdx | Adds an 'Opening a specific session' subsection after the workspaces open Command block, documenting the chatSessionId/terminalId/focusRequestId deep-link params. The anchor reference to #superset-agents-run resolves correctly per the Command component's slugify logic. Placeholder naming style (camelCase here, kebab-case in SKILL.md) is inconsistent, and the bash examples omit any agents run --json invocation showing how to obtain sessionId. |
| skills/superset/SKILL.md | Expands the Agents section to mention superset as a valid --agent value, adds agents run --json return shape, and introduces a new 'Opening sessions in the desktop app' section with the kind-to-param table and three shell examples including the $SUPERSET_WORKSPACE_ID/$SUPERSET_TERMINAL_ID shortcut. Content is accurate and the internal anchor resolves correctly. |
Sequence Diagram
sequenceDiagram
participant User
participant CLI as superset CLI
participant Desktop as Desktop App (deep link)
User->>CLI: agents run --workspace id --agent preset --prompt ... --json
CLI-->>User: "{ kind, sessionId, label }"
alt "kind == chat (agent: superset)"
User->>Desktop: "open superset://v2-workspace/id?chatSessionId=sessionId"
else "kind == terminal (agent: claude, codex)"
User->>Desktop: "open superset://v2-workspace/id?terminalId=sessionId"
end
Note over Desktop: validateSearch parses params, focuses/adds pane. Add focusRequestId=unique to force re-focus.
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
apps/docs/content/docs/cli/cli-reference.mdx:642-648
**Missing `--json` call in code examples**
The prose correctly explains that you must run `agents run --json` to get the `kind` and `sessionId`, but the bash block jumps straight to the `open` call with `<sessionId>` as a placeholder — without any example of how to capture that value from the JSON output. A reader following this doc literally has no shell snippet showing the full round-trip (run → parse → open). Even a one-liner using `jq` or `$(…)` substitution would make the intent actionable without forcing them to infer the plumbing.
### Issue 2 of 2
apps/docs/content/docs/cli/cli-reference.mdx:637-640
**Placeholder naming style inconsistent with `SKILL.md`**
The examples here use camelCase placeholders (`<workspaceId>`, `<sessionId>`) while the parallel section in `skills/superset/SKILL.md` uses kebab-case (`<workspace-id>`, `<sessionId>`). Since these two files document the same URL scheme and are meant to stay in sync, consistent placeholder casing makes it easier to correlate them at a glance. Consider aligning on one convention across both files.
Reviews (1): Last reviewed commit: "docs(cli): document opening a specific a..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files
Architecture diagram
sequenceDiagram
participant CLI as CLI (workspaces open)
participant Runner as agents run
participant User as Desktop User
participant Desktop as Desktop App
participant Route as v2-workspace Route
participant Pane as Session Pane
Note over CLI,Pane: Opening a specific agent session via deep link
User->>CLI: superset agents run --agent superset --json
CLI->>Runner: Execute agent run
Runner-->>CLI: { kind: "chat", sessionId: "sess_xxx", label: "..." }
CLI-->>User: JSON output
User->>CLI: superset workspaces open <workspaceId> --print
CLI-->>User: superset://v2-workspace/<workspaceId>
User->>User: Build deep link with query params
Note over User: Choose param by kind:<br/>chat → ?chatSessionId=<sessionId><br/>terminal → ?terminalId=<sessionId><br/>Optional: &focusRequestId=<unique>
User->>Desktop: Open deep link<br/>superset://v2-workspace/<workspaceId>?chatSessionId=<sessionId>
Note over User,Desktop: Platform opener: open/xdg-open/start
Desktop->>Route: Navigate to v2-workspace/<workspaceId>
Route->>Route: Parse query params (validateSearch)
Route->>Route: Verify session belongs to workspace
alt chatSessionId present
Route->>Pane: Focus chat session pane
else terminalId present
Route->>Pane: Focus terminal session pane
end
opt focusRequestId present
Route->>Pane: Force re-focus even if already opened
end
Pane-->>Route: Pane focused/added
Route-->>User: Session visible in workspace view
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Summary
superset://v2-workspace/<id>deep-link query params used to focus a specific agent session in the desktop app (Session deep-linking (chatSessionId/terminalId) is undocumented and not exposed by the CLI #5029):?chatSessionId=(chat sessions),?terminalId=(terminal sessions), and optional&focusRequestId=to force a re-focus.apps/docs/content/docs/cli/cli-reference.mdx: new "Opening a specific session" subsection underworkspaces open, with thekind→param mapping fromagents run --json, bash examples, and a cross-platform opener note.skills/superset/SKILL.md: new "Opening sessions in the desktop app" section (same scheme/table/examples plus the$SUPERSET_WORKSPACE_ID/$SUPERSET_TERMINAL_IDshortcut and the "fresh session is invisible until opened" gotcha), an--agent supersetmention, and akindnote in the Agents section.Why / Context
superset workspaces open <id>only ever targets a workspace — it firessuperset://v2-workspace/<id>with no query string, and a session created viaagents runhas no pane and no session-list entry until you navigate to it, so a freshly created session is effectively invisible. The desktop route already parseschatSessionId/terminalId/focusRequestIdand focuses/adds the matching pane, but the only way to use it was to hand-build the URL — and that was undocumented. This PR documents the workflow.Verification (docs vs. source)
Every command, URL, param, and the
kind→param mapping was checked against the code:--print:packages/cli/src/commands/workspaces/open/command.tsagents run --json→{ kind, sessionId, label };kindischatforsuperset,terminalforclaude/codex:packages/cli/src/commands/agents/run/command.ts+ host-serviceagents.ts(input.agent === "superset"→runChatAgent)validateSearchparses all three params and the pane is focused/added with workspace-ownership enforced: desktopv2-workspace/$workspaceIdroute +useConsumeAutomationRunLink(focusRequestIdis part of the consume key, so it forces re-focus)open/xdg-open/start) matches the CLI's ownopenUrlplatform branching.Testing
.md/.mdx, so no lint impact.Notes
SKILL.mdedit lands in one tracked file but applies in three places:plugins/superset/skills/supersetis a symlink toskills/superset, and the marketing.well-known/agent-skillsroute readsskills/superset/SKILL.mddynamically — so the bundled plugin and the served skill stay in sync with no duplicate blobs.robertn702:adorable-chimpanzee) as the author lacks direct push access.Summary by cubic
Document deep links for opening a specific agent session in the desktop app. CLI docs and
skills/superset/SKILL.mdnow show how to buildsuperset://v2-workspace/<workspaceId>URLs with?chatSessionId=/?terminalId=(optional&focusRequestId=), include thekind→param mapping with a bash--jsonround-trip example, and align placeholder casing and opener notes.Written for commit cdb7944. Summary will update on new commits.
Summary by CodeRabbit