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:314-352 (handler)The core handler function for clearing empty sessions, invalid API key sessions, and orphan agent files across projects.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-134 (registration)MCP tool registration for 'clear_sessions', defining schema and handler that delegates to session.clearSessions.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)Zod input schema for the clear_sessions tool parameters.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)'), },
- src/lib/session.ts:226-251 (helper)Helper function previewCleanup used by clearSessions to identify sessions for deletion.export const previewCleanup = (projectName?: string) => Effect.gen(function* () { const projects = yield* listProjects const targetProjects = projectName ? projects.filter((p) => p.name === projectName) : projects const results = yield* Effect.all( targetProjects.map((project) => Effect.gen(function* () { const sessions = yield* listSessions(project.name) const emptySessions = sessions.filter((s) => s.messageCount === 0) const invalidSessions = sessions.filter( (s) => s.title?.includes('Invalid API key') || s.title?.includes('API key') ) return { project: project.name, emptySessions, invalidSessions, } }) ), { concurrency: 5 } ) return results })