session_start
Orient a coding agent at session start by returning workspace path, language, git branch, memory index, recent files/commits, and live LSP diagnostics. Use 'brief' for a compact subagent re-orientation.
Instructions
Bootstrap tool — call this first at the start of every session. Returns one-shot orientation: workspace path, language, current git branch, first 200 lines of .plumb/context.md, all saved memory names/descriptions, top-5 most-used tools, 5 most recently-modified files, 3 most recent commits, the live git tool policy (whether commits/destructive/push are enabled), and any active LSP errors/warnings. If no workspace is resolved yet, pass an absolute workspace to pin it — clients like Claude Desktop do not report the folder automatically. A subagent that just needs cheap re-orientation should pass detail: "brief" for a ≤1.5 KB summary instead of the full packet. Idempotent — safe to call multiple times.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Override the sticky-pin guard: when this connection is already pinned to a different project by an explicit session_start call, a re-pin is refused unless force is true. Use it only when you are deliberately switching THIS connection to another project — e.g. a new conversation on a connection reused across conversations. On a connection shared by several agents (Cowork, Claude Desktop local-agent-mode), prefer a dedicated plumb serve process per agent over forcing. | |
| detail | No | Orientation packet size. 'brief' (≤1.5 KB) returns workspace path, language, branch, a one-line git policy, diagnostics and active-peer COUNTS, memory NAMES only (no descriptions/sizes), and the edit-lane rule where it applies — cheap re-orientation for a subagent that does not need the full packet. 'full' returns the complete packet documented above. Defaults to 'full', except this default flips to 'brief' automatically when the supplied session_id was already seen by this daemon within the last 24h (a resumed conversation); an explicit value always wins over the automatic default. | |
| purpose | No | Optional human-readable tag describing what this session is for (e.g. 'deploy-fix', 'feature-auth'). Surfaced in the TUI session list, daemon_info, and workspace_sessions so an operator can tell concurrent sessions apart. Allowed characters: letters, digits, and hyphens; max 32 characters. An invalid value is rejected with a clear error. | |
| language | No | Optional override for the workspace's primary language when automatic detection cannot infer it — e.g. an Xcode app that has .swift sources but no SwiftPM Package.swift, so no root marker resolves. Pass the [lsp.<lang>] key (e.g. 'swift', 'typescript', 'rust') to force that language server as the primary, so workspace_symbols and the call/type hierarchies work. The server must be installed and enabled; an unknown, uninstalled, or disabled language is ignored and normal detection applies. Honoured on the connection's current workspace, or alongside an explicit 'workspace' arg. | |
| workspace | No | Absolute workspace path. Use this to pin the project for clients that do not report a folder (e.g. Claude Desktop). If this connection is already pinned to a different project, passing a workspace here re-pins it to the new project — this is how you switch projects on a connection reused across conversations. When the current pin was itself set by an explicit session_start, the re-pin is refused unless you also pass force: true — a guard against a peer agent silently stealing the pin on a shared connection (issue #182). Defaults to the daemon's already-resolved workspace. | |
| session_id | No | Optional opaque identifier linking this plumb session to the caller's own session (e.g. a Claude Code conversation ID). When provided, plumb persists the ID and, if a recent session with the same ID ended within the last 24 h, inherits its name — so a resumed conversation keeps its session name in the TUI. |