session_start
Bootstrap a coding session by pinning the workspace and retrieving orientation data: language, git branch, memory list, recent files, commits, tool policy, and LSP errors in a single call.
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. 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. | |
| 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. |