clear_sessions
Remove empty sessions, invalid API key sessions, and orphan agent files to clean up Claude Code conversation storage.
Instructions
Delete all empty sessions and invalid API key sessions
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_name | No | Optional: filter by project name | |
| clear_empty | No | Clear empty sessions (default: true) | |
| clear_invalid | No | Clear invalid API key sessions (default: true) | |
| clear_orphan_agents | No | Clear orphan agent files whose session no longer exists (default: true) |
Implementation Reference
- src/lib/session.ts:203-241 (handler)Core handler function that executes the clear_sessions logic: identifies empty/invalid sessions via previewCleanup, deletes them selectively, and removes orphan agent files.
export const clearSessions = (options: { projectName?: string clearEmpty?: boolean clearInvalid?: boolean clearOrphanAgents?: boolean }) => Effect.gen(function* () { const { projectName, clearEmpty = true, clearInvalid = true, clearOrphanAgents = true, } = options const cleanupPreview = yield* previewCleanup(projectName) let deletedCount = 0 let deletedAgentCount = 0 for (const result of cleanupPreview) { const toDelete = [ ...(clearEmpty ? result.emptySessions : []), ...(clearInvalid ? result.invalidSessions : []), ] for (const session of toDelete) { const deleteResult = yield* deleteSession(result.project, session.id) deletedCount++ deletedAgentCount += deleteResult.deletedAgents.length } // Clean up orphan agents after deleting sessions if (clearOrphanAgents) { const orphanResult = yield* deleteOrphanAgents(result.project) deletedAgentCount += orphanResult.count } } return { success: true, deletedCount, deletedAgentCount } }) - src/mcp/index.ts:107-135 (registration)MCP tool registration for 'clear_sessions', defining input schema with Zod and a thin async handler that delegates to session.clearSessions from src/lib/session.ts.
server.tool( 'clear_sessions', 'Delete all empty sessions and invalid API key sessions', { project_name: z.string().optional().describe('Optional: filter by project name'), clear_empty: z.boolean().default(true).describe('Clear empty sessions (default: true)'), clear_invalid: z .boolean() .default(true) .describe('Clear invalid API key sessions (default: true)'), clear_orphan_agents: z .boolean() .default(true) .describe('Clear orphan agent files whose session no longer exists (default: true)'), }, async ({ project_name, clear_empty, clear_invalid, clear_orphan_agents }) => { const result = await Effect.runPromise( session.clearSessions({ projectName: project_name, clearEmpty: clear_empty, clearInvalid: clear_invalid, clearOrphanAgents: clear_orphan_agents, }) ) return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], } } ) - src/mcp/index.ts:111-121 (schema)Input schema definition for the clear_sessions tool using Zod validators with descriptions and defaults.
project_name: z.string().optional().describe('Optional: filter by project name'), clear_empty: z.boolean().default(true).describe('Clear empty sessions (default: true)'), clear_invalid: z .boolean() .default(true) .describe('Clear invalid API key sessions (default: true)'), clear_orphan_agents: z .boolean() .default(true) .describe('Clear orphan agent files whose session no longer exists (default: true)'), },