manage_projects
Register or unregister projects for indexing to enable semantic search across Claude Code conversations. Use list to view project status.
Instructions
Manage which projects are registered for indexing. Use 'list' to see all projects on disk and their registration status. Use 'add' to register a project for indexing. Use 'remove' to unregister. Projects must be registered before they can be indexed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| project | No |
Implementation Reference
- src/tools/manage-projects.ts:12-203 (handler)The primary handler for the 'manage_projects' tool. It executes add/remove/list actions on projects.
export async function handleManageProjects( db: Database.Database, params: ManageProjectsParams ): Promise<{ content: Array<{ type: string; text: string }> }> { const config = loadUserConfig(); const projectsBaseDir = process.env.CLAUDE_PROJECTS_DIR ?? CONFIG.claudeProjectsDir; const allProjects = scanProjects(projectsBaseDir); if (params.action === "list") { const projectList = allProjects.map((p) => { const sessions = scanSessions(p.dirPath); const isRegistered = config.indexed_projects.includes(p.dirName); return { dir_name: p.dirName, name: p.name, session_count: sessions.length, registered: isRegistered, }; }); // Sort: registered first, then by session count projectList.sort((a, b) => { if (a.registered !== b.registered) return a.registered ? -1 : 1; return b.session_count - a.session_count; }); // Hide projects with 0 sessions (unless registered) const visible = projectList.filter((p) => p.session_count > 0 || p.registered); const hidden = projectList.length - visible.length; return { content: [{ type: "text", text: JSON.stringify({ total_projects: visible.length, registered_count: visible.filter((p) => p.registered).length, hidden_empty: hidden > 0 ? `${hidden} projects with 0 sessions hidden` : undefined, projects: visible, hint: "Use action 'add' with a project name to register for indexing. Use 'remove' to unregister.", }, null, 2), }], }; } if (params.action === "add") { if (!params.project) { return { content: [{ type: "text", text: JSON.stringify({ error: "project parameter is required for 'add' action" }) }], }; } // Exact match first (by dir_name or name) const exact = allProjects.filter( (p) => p.dirName === params.project! || p.name.toLowerCase() === params.project!.toLowerCase() ); const matches = exact.length > 0 ? exact : allProjects.filter( (p) => p.name.toLowerCase().includes(params.project!.toLowerCase()) || p.dirName.toLowerCase().includes(params.project!.toLowerCase()) ); if (matches.length === 0) { return { content: [{ type: "text", text: JSON.stringify({ error: `No project matching "${params.project}" found.`, available: allProjects.filter((p) => scanSessions(p.dirPath).length > 0).map((p) => p.name), }), }], }; } // If multiple matches, don't auto-add — return candidates for user to pick if (matches.length > 1) { return { content: [{ type: "text", text: JSON.stringify({ status: "multiple_matches", message: `"${params.project}" matched ${matches.length} projects. Please be more specific or use the exact dir_name.`, matches: matches.map((m) => ({ dir_name: m.dirName, name: m.name, session_count: scanSessions(m.dirPath).length, })), }), }], }; } // Exactly 1 match — add it const match = matches[0]; if (config.indexed_projects.includes(match.dirName)) { return { content: [{ type: "text", text: JSON.stringify({ status: "ok", message: `${match.name} is already registered.`, total_registered: config.indexed_projects.length }), }], }; } config.indexed_projects.push(match.dirName); saveUserConfig(config); return { content: [{ type: "text", text: JSON.stringify({ status: "ok", added: [match.name], total_registered: config.indexed_projects.length, message: `Added ${match.name} to indexing list. Run 'index' to start indexing.`, }), }], }; } if (params.action === "remove") { if (!params.project) { return { content: [{ type: "text", text: JSON.stringify({ error: "project parameter is required for 'remove' action" }) }], }; } // Block remove during active indexing to prevent DB conflicts if (getIndexProgress().running) { return { content: [{ type: "text", text: JSON.stringify({ error: "Cannot remove projects while indexing is in progress. Wait for indexing to complete or check status.", }), }], }; } // Find which dir_names will be removed const removedDirNames: string[] = []; config.indexed_projects = config.indexed_projects.filter( (dirName) => { const proj = allProjects.find((p) => p.dirName === dirName); const name = proj?.name || dirName; const shouldRemove = name.toLowerCase().includes(params.project!.toLowerCase()) || dirName.toLowerCase().includes(params.project!.toLowerCase()); if (shouldRemove) removedDirNames.push(dirName); return !shouldRemove; } ); saveUserConfig(config); // Delete indexed data from DB for removed projects let chunksDeleted = 0; let sessionsDeleted = 0; for (const dirName of removedDirNames) { const project = db.prepare("SELECT id FROM projects WHERE dir_name = ?").get(dirName) as { id: number } | undefined; if (project) { const sessions = db.prepare("SELECT id FROM sessions WHERE project_id = ?").all(project.id) as { id: number }[]; for (const session of sessions) { deleteSessionChunks(db, session.id); chunksDeleted++; } sessionsDeleted += sessions.length; db.prepare("DELETE FROM sessions WHERE project_id = ?").run(project.id); db.prepare("DELETE FROM projects WHERE id = ?").run(project.id); } } return { content: [{ type: "text", text: JSON.stringify({ status: "ok", removed_count: removedDirNames.length, sessions_deleted: sessionsDeleted, total_registered: config.indexed_projects.length, message: removedDirNames.length > 0 ? `Removed ${removedDirNames.length} project(s) and deleted ${sessionsDeleted} session(s) from index.` : "No matching projects found in the registered list.", }), }], }; } return { content: [{ type: "text", text: JSON.stringify({ error: "Invalid action. Use 'add', 'remove', or 'list'." }) }], }; } - src/tools/manage-projects.ts:7-10 (schema)Input parameter validation schema for the 'manage_projects' tool.
export interface ManageProjectsParams { action: "add" | "remove" | "list"; project?: string; }