start_session
Initialize a work session to organize changes and prevent fragmented auto-commits in ShadowGit repositories.
Instructions
Start a work session. MUST be called BEFORE making any changes. Without this, ShadowGit will create fragmented auto-commits during your work!
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository name | |
| description | Yes | What you plan to do in this session |
Implementation Reference
- src/handlers/session-handler.ts:30-73 (handler)The primary handler function for the 'start_session' tool. Validates input arguments, resolves the repository path, initiates the session using SessionClient, and returns a formatted response with session ID and workflow instructions.async startSession(args: unknown): Promise<MCPToolResponse> { // Validate args if (!this.isStartSessionArgs(args)) { return createErrorResponse( 'Error: Both "repo" and "description" are required for start_session.' ); } // Resolve repository const repoPath = this.repositoryManager.resolveRepoPath(args.repo); if (!repoPath) { return createErrorResponse( `Error: Repository '${args.repo}' not found. Use list_repos() to see available repositories.` ); } // Start session const sessionId = await this.sessionClient.startSession({ repoPath, aiTool: 'MCP Client', description: args.description }); if (sessionId) { log('info', `Session started: ${sessionId}`); return { content: [{ type: 'text', text: `Session started successfully. Session ID: ${sessionId} 📋 **Your Workflow Checklist:** 1. Make your changes 2. Call checkpoint() to commit 3. Call end_session() with this session ID` }] }; } // Fallback if Session API is offline return createErrorResponse( 'Session API is offline. Proceeding without session tracking.' ); }
- TypeScript interface defining the expected input arguments for the start_session tool: repo (string) and description (string).interface StartSessionArgs { repo: string; description: string; }
- src/shadowgit-mcp-server.ts:176-177 (registration)Dispatch logic in the CallToolRequest handler that routes 'start_session' calls to the SessionHandler's startSession method.case 'start_session': return await this.sessionHandler.startSession(args);
- src/shadowgit-mcp-server.ts:98-114 (registration)Tool registration in the ListToolsRequest handler, defining the name, description, and input schema for 'start_session'.name: 'start_session', description: 'Start a work session. MUST be called BEFORE making any changes. Without this, ShadowGit will create fragmented auto-commits during your work!', inputSchema: { type: 'object', properties: { repo: { type: 'string', description: 'Repository name', }, description: { type: 'string', description: 'What you plan to do in this session', }, }, required: ['repo', 'description'], }, },
- src/core/session-client.ts:27-59 (helper)Supporting utility in SessionClient that makes the HTTP request to the ShadowGit Session API to start a session and returns the session ID.async startSession(data: SessionStartRequest): Promise<string | null> { try { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), this.timeout); const response = await fetch(`${this.baseUrl}/session/start`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(data), signal: controller.signal, }); clearTimeout(timeoutId); if (response.ok) { const result = await response.json() as SessionStartResponse; if (result.success && result.sessionId) { log('info', `Session started: ${result.sessionId} for ${data.repoPath}`); return result.sessionId; } } log('warn', `Failed to start session: ${response.status} ${response.statusText}`); } catch (error) { // Silently fail - don't break MCP if Session API is down if (error instanceof Error && error.name !== 'AbortError') { log('debug', `Session API unavailable: ${error.message}`); } } return null; }