claude-sessions-mcp

Instructions

Implementation Reference

• src/lib/session.ts:349-451 (handler)

  The main handler function that executes the split_session tool logic. It reads the session file, finds the split point by message UUID, handles special cases like continuation summaries by duplicating them, creates a new session file with subsequent messages, updates parentUuid chains, and migrates related agent files.
  export const splitSession = (projectName: string, sessionId: string, splitAtMessageUuid: string) => Effect.gen(function* () { const projectPath = path.join(getSessionsDir(), projectName) const filePath = path.join(projectPath, `${sessionId}.jsonl`) const content = yield* Effect.tryPromise(() => fs.readFile(filePath, 'utf-8')) const lines = content.trim().split('\n').filter(Boolean) // Parse all messages preserving their full structure const allMessages = lines.map((line) => JSON.parse(line) as Record<string, unknown>) // Find the split point const splitIndex = allMessages.findIndex((m) => m.uuid === splitAtMessageUuid) if (splitIndex === -1) { return { success: false, error: 'Message not found' } satisfies SplitSessionResult } if (splitIndex === 0) { return { success: false, error: 'Cannot split at first message' } satisfies SplitSessionResult } // Generate new session ID const newSessionId = crypto.randomUUID() // Check if the split message is a continuation summary const splitMessage = allMessages[splitIndex] const shouldDuplicate = isContinuationSummary(splitMessage) // Split messages - if continuation summary, include it in both sessions let remainingMessages: Record<string, unknown>[] const movedMessages = allMessages.slice(splitIndex) if (shouldDuplicate) { // Create a copy of the continuation message with new UUID for the original session const duplicatedMessage: Record<string, unknown> = { ...splitMessage, uuid: crypto.randomUUID(), sessionId: sessionId, // Keep original session ID } remainingMessages = [...allMessages.slice(0, splitIndex), duplicatedMessage] } else { remainingMessages = allMessages.slice(0, splitIndex) } // Update moved messages with new sessionId and fix first message's parentUuid const updatedMovedMessages = movedMessages.map((msg, index) => { const updated: Record<string, unknown> = { ...msg, sessionId: newSessionId } if (index === 0) { // First message of new session should have no parent updated.parentUuid = null } return updated }) // Write remaining messages to original file const remainingContent = remainingMessages.map((m) => JSON.stringify(m)).join('\n') + '\n' yield* Effect.tryPromise(() => fs.writeFile(filePath, remainingContent, 'utf-8')) // Write moved messages to new session file const newFilePath = path.join(projectPath, `${newSessionId}.jsonl`) const newContent = updatedMovedMessages.map((m) => JSON.stringify(m)).join('\n') + '\n' yield* Effect.tryPromise(() => fs.writeFile(newFilePath, newContent, 'utf-8')) // Update linked agent files that reference the old sessionId const agentFiles = yield* Effect.tryPromise(() => fs.readdir(projectPath)) const agentJsonlFiles = agentFiles.filter((f) => f.startsWith('agent-') && f.endsWith('.jsonl')) for (const agentFile of agentJsonlFiles) { const agentPath = path.join(projectPath, agentFile) const agentContent = yield* Effect.tryPromise(() => fs.readFile(agentPath, 'utf-8')) const agentLines = agentContent.trim().split('\n').filter(Boolean) if (agentLines.length === 0) continue const firstAgentMsg = JSON.parse(agentLines[0]) as { sessionId?: string } // If this agent belongs to the original session, check if it should be moved if (firstAgentMsg.sessionId === sessionId) { // Check if any message in moved messages is related to this agent const agentId = agentFile.replace('agent-', '').replace('.jsonl', '') const isRelatedToMoved = movedMessages.some( (msg) => (msg as { agentId?: string }).agentId === agentId ) if (isRelatedToMoved) { // Update all messages in this agent file to reference new sessionId const updatedAgentMessages = agentLines.map((line) => { const msg = JSON.parse(line) as Record<string, unknown> return JSON.stringify({ ...msg, sessionId: newSessionId }) }) const updatedAgentContent = updatedAgentMessages.join('\n') + '\n' yield* Effect.tryPromise(() => fs.writeFile(agentPath, updatedAgentContent, 'utf-8')) } } } return { success: true, newSessionId, newSessionPath: newFilePath, movedMessageCount: movedMessages.length, duplicatedSummary: shouldDuplicate, } satisfies SplitSessionResult })
• src/lib/session.ts:328-335 (schema)

  Output type definition for the splitSession function, used in the tool response.
  export interface SplitSessionResult { success: boolean newSessionId?: string newSessionPath?: string movedMessageCount?: number duplicatedSummary?: boolean error?: string }
• src/mcp/index.ts:170-189 (registration)

  MCP server tool registration for 'split_session', defining input schema with Zod and calling the splitSession handler.
  server.tool( 'split_session', 'Split a session at a specific message, creating a new session with messages from that point onwards', { project_name: z.string().describe('Project folder name'), session_id: z.string().describe('Session ID to split'), message_uuid: z .string() .describe( 'UUID of the message where the split starts (this message becomes the first message of the new session)' ), }, async ({ project_name, session_id, message_uuid }) => { const result = await Effect.runPromise( session.splitSession(project_name, session_id, message_uuid) ) return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], } }
• src/lib/session.ts:338-347 (helper)

  Helper utility to detect if a message is a continuation summary, which determines whether to duplicate it during split.
  const isContinuationSummary = (msg: Record<string, unknown>): boolean => { // isCompactSummary flag is set by Claude Code for continuation summaries if (msg.isCompactSummary === true) return true // Fallback: check message content if (msg.type !== 'user') return false const message = msg.message as { content?: string } | undefined const content = message?.content ?? '' return content.startsWith('This session is being continued from') }