Add start_claude_session and start_claude_subagent MCP tools

[saddlepaddle]

Summary

Some hacky tools in the mcp to get us started on multi-agent stuff / automations

Test plan

• start_claude_session creates workspace with task slug as branch name and workspace name
• Claude launches automatically in the new workspace terminal
• Lint, typecheck, and tests pass
• start_claude_subagent adds a terminal pane to the active workspace

Summary by CodeRabbit

Release Notes

• New Features
  • Added ability to create and launch dedicated Claude sessions with isolated workspaces and git branches for task-specific work
  • Added ability to spawn Claude subagents within existing workspaces for concurrent execution with separate execution contexts

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Two new tools—startClaudeSession and startClaudeSubagent—are added to both the desktop renderer and MCP server components. Desktop implementations manage workspace creation, git branching, and terminal command queueing; MCP implementations provide server-side task validation, command composition, and device-level execution registration.

Changes

Cohort / File(s)	Summary
Desktop Tool Implementations apps/desktop/src/renderer/routes/_authenticated/components/AgentHooks/hooks/useCommandWatcher/tools/start-claude-session.ts, start-claude-subagent.ts	New tool definitions with Zod schemas and execute handlers. startClaudeSession creates workspaces with git branches and queues terminal commands; startClaudeSubagent adds panes to active tabs. Both include error handling for missing workspaces and invalid states.
Desktop Tools Registry apps/desktop/src/renderer/routes/_authenticated/components/AgentHooks/hooks/useCommandWatcher/tools/index.ts	Imports and registers the two new tool implementations in the tools registry and name-to-tool mapping.
MCP Server Tool Implementation packages/mcp/src/tools/devices/start-claude-session/start-claude-session.ts	Server-side tool module exporting register() function that creates two MCP tools. Includes task fetching via database, command building with execution context, and device-level tool execution. Handles validation of deviceId and taskId with specific error codes.
MCP Tools Integration packages/mcp/src/tools/devices/start-claude-session/index.ts, packages/mcp/src/tools/index.ts	Index files that re-export and register the new start-claude-session tool in the MCP tools registry.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Desktop as Desktop App
    participant WorkspaceStore as Workspace Store
    participant WSInitStore as WS-Init Store
    participant Navigation as Navigation

    User->>Desktop: Request startClaudeSession
    Desktop->>WorkspaceStore: Get current/recent workspace
    alt No workspaces exist
        Desktop-->>User: Error: No workspaces
    else Workspace found
        WorkspaceStore-->>Desktop: projectId
        Desktop->>WorkspaceStore: Create new worktree
        WorkspaceStore-->>Desktop: New workspaceId
        Desktop->>WSInitStore: Queue command in initialCommands
        WSInitStore-->>Desktop: Updated pending data
        Desktop->>Navigation: Navigate to workspace
        Desktop-->>User: Success with workspaceId & branch
    end

Loading

sequenceDiagram
    participant MCP as MCP Server
    participant DB as Database
    participant Device as Device Handler
    participant Result as Result

    MCP->>MCP: Validate deviceId & taskId
    alt Invalid args
        MCP-->>Result: ERROR_DEVICE_AND_TASK_REQUIRED
    else Valid
        MCP->>DB: fetchTask(taskId, organization)
        alt Task not found
            DB-->>Result: ERROR_TASK_NOT_FOUND
        else Task found
            DB-->>MCP: Task details
            MCP->>MCP: buildCommand(task)
            MCP->>Device: executeOnDevice with command
            Device-->>Result: Success with result
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Hoppity hoppity, new tools sprout,
Sessions and subagents, no doubt!
Workspaces bloom with branches so green,
Commands and contexts flow in between,
From desktop to server, the agents take flight, ✨
Claude's helpers now ready to help day and night!

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is largely incomplete, missing several required template sections including Related Issues, Type of Change checkbox selection, Testing details, Screenshots, and Additional Notes.	Complete the description by filling in all required template sections: select the Type of Change, provide explicit testing steps, and add any other relevant context.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding two new MCP tools for starting Claude sessions and subagents.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch startup-claude

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ✅ Neon database branch
• ✅ Electric Fly.io app

Thank you for your contribution! 🎉