@claudetools/tools 0.7.1 → 0.7.2

package/dist/cli.js

@@ -10,6 +10,7 @@ import { dirname, join } from 'node:path';
 import { runSetup, runUninstall, runInit, runCleanup } from './setup.js';
 import { startServer } from './index.js';
 import { startWatcher, stopWatcher, watcherStatus } from './watcher.js';
+import { generateCodebaseMap, generateCodebaseMapLocal } from './helpers/codebase-mapper.js';
 // Get version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -53,6 +54,8 @@ Commands:
   watch            Start the file watcher daemon
   watch --stop     Stop the watcher daemon
   watch --status   Check watcher status
+  map              Generate codebase map for current project
+  map --local      Generate map locally without uploading
 
 Running without options starts the MCP server.
 
@@ -103,6 +106,65 @@ else if (positionals[0] === 'watch') {
         });
     }
 }
+else if (positionals[0] === 'map') {
+    // Handle map command
+    const mapArgs = process.argv.slice(3); // Get args after 'map'
+    const isLocal = mapArgs.includes('--local');
+    (async () => {
+        const cwd = process.cwd();
+        if (isLocal) {
+            console.log(`Generating codebase map for: ${cwd}`);
+            const { index, markdown } = generateCodebaseMapLocal(cwd);
+            console.log(`\nGenerated map with ${index.summary.totalFiles} files, ${index.summary.totalSymbols} symbols`);
+            console.log(`\n--- CODEBASE MAP ---\n`);
+            console.log(markdown);
+        }
+        else {
+            // Load config to get API key and project ID
+            const { existsSync: exists, readFileSync: read } = await import('fs');
+            const { join: pathJoin, basename } = await import('path');
+            const { homedir } = await import('os');
+            const configPath = pathJoin(homedir(), '.claudetools', 'config.json');
+            const projectsPath = pathJoin(homedir(), '.claudetools', 'projects.json');
+            if (!exists(configPath)) {
+                console.error('Not configured. Run: claudetools --setup');
+                process.exit(1);
+            }
+            const config = JSON.parse(read(configPath, 'utf-8'));
+            if (!config.apiKey) {
+                console.error('No API key configured. Run: claudetools --setup');
+                process.exit(1);
+            }
+            // Find project ID for current directory
+            let projectId = null;
+            if (exists(projectsPath)) {
+                const projects = JSON.parse(read(projectsPath, 'utf-8'));
+                const binding = projects.bindings?.find((b) => b.local_path === cwd);
+                if (binding) {
+                    projectId = binding.project_id;
+                }
+            }
+            if (!projectId) {
+                console.error('Current directory is not a registered project.');
+                console.error('Run: claudetools init');
+                process.exit(1);
+            }
+            console.log(`Generating codebase map for: ${basename(cwd)} (${projectId})`);
+            const result = await generateCodebaseMap(cwd, projectId, config.apiKey);
+            if (result.success) {
+                console.log('Codebase map generated and uploaded successfully!');
+                console.log(`View at: ${config.apiUrl || 'https://api.claudetools.dev'}/api/v1/codebase/${projectId}/map`);
+            }
+            else {
+                console.error('Failed to generate map:', result.error);
+                process.exit(1);
+            }
+        }
+    })().catch((error) => {
+        console.error('Map generation failed:', error);
+        process.exit(1);
+    });
+}
 else {
     // Start MCP server
     startServer();

package/dist/handlers/tool-handlers.js

@@ -758,7 +758,7 @@ export function registerToolHandlers(server) {
                                 blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
                             };
                             const emoji = statusEmoji[t.status] || '📝';
-                            let line = `- ${emoji} **${t.title}** (${t.id.slice(0, 8)}...)`;
+                            let line = `- ${emoji} **${t.title}** (\`${t.id}\`)`;
                             line += ` [${t.status}]`;
                             if (t.priority !== 'medium')
                                 line += ` [${t.priority}]`;
@@ -817,12 +817,12 @@ export function registerToolHandlers(server) {
                         }
                         if (data.parent) {
                             output += `\n## Parent\n`;
-                            output += `- **${data.parent.title}** (${data.parent.id.slice(0, 8)}...) [${data.parent.status}]\n`;
+                            output += `- **${data.parent.title}** (\`${data.parent.id}\`) [${data.parent.status}]\n`;
                         }
                         if (data.subtasks?.length) {
                             output += `\n## Subtasks (${data.subtasks.length})\n`;
                             data.subtasks.forEach(s => {
-                                output += `- ${s.title} (${s.id.slice(0, 8)}...) [${s.status}]\n`;
+                                output += `- ${s.title} (\`${s.id}\`) [${s.status}]\n`;
                             });
                         }
                         if (data.context?.length) {
@@ -1430,14 +1430,20 @@ export function registerToolHandlers(server) {
                 // =========================================================================
                 case 'codebase_map': {
                     // Use raw fetch since this endpoint returns markdown, not JSON
+                    // But we still need auth header
+                    const { getConfig } = await import('../helpers/config-manager.js');
+                    const config = getConfig();
+                    const apiKey = config.apiKey || process.env.CLAUDETOOLS_API_KEY || process.env.MEMORY_API_KEY;
                     const url = `${API_BASE_URL}/api/v1/codebase/${projectId}/map`;
-                    const response = await fetch(url);
+                    const response = await fetch(url, {
+                        headers: apiKey ? { 'Authorization': `Bearer ${apiKey}` } : {},
+                    });
                     mcpLogger.toolResult(name, response.ok, timer());
                     if (!response.ok) {
                         return {
                             content: [{
                                     type: 'text',
-                                    text: `# No Codebase Map Found\n\nThe codebase map hasn't been generated yet. Use the file watcher or API to generate one.`,
+                                    text: `# No Codebase Map Found\n\nThe codebase map hasn't been generated yet. Use the file watcher or API to generate one.\n\n**Debug:** \`${url}\` returned ${response.status}`,
                                 }],
                         };
                     }

package/dist/helpers/codebase-mapper.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Codebase Mapper
+ *
+ * Client-side AST analysis to generate codebase maps.
+ * Runs in the MCP server and uploads results to the API.
+ */
+export interface FileSymbol {
+    name: string;
+    type: 'function' | 'class' | 'interface' | 'type' | 'const' | 'enum' | 'component';
+    exported: boolean;
+    line: number;
+    signature?: string;
+    description?: string;
+}
+export interface FileEntry {
+    path: string;
+    relativePath: string;
+    role: FileRole;
+    symbols: FileSymbol[];
+    imports: string[];
+    exports: string[];
+    dependencies: string[];
+    dependents: string[];
+    linesOfCode: number;
+}
+export type FileRole = 'entry-point' | 'route-handler' | 'api-endpoint' | 'mcp-tool' | 'component' | 'hook' | 'utility' | 'type-definitions' | 'config' | 'test' | 'model' | 'service' | 'extractor' | 'unknown';
+export interface DirectoryEntry {
+    path: string;
+    role: string;
+    fileCount: number;
+    primaryLanguage: string;
+    keyFiles: string[];
+}
+export interface CodebaseIndex {
+    version: string;
+    generatedAt: string;
+    projectRoot: string;
+    summary: {
+        totalFiles: number;
+        totalSymbols: number;
+        languages: Record<string, number>;
+        frameworks: string[];
+    };
+    directories: Record<string, DirectoryEntry>;
+    files: Record<string, FileEntry>;
+    symbols: Record<string, {
+        file: string;
+        line: number;
+        type: string;
+        exported: boolean;
+    }[]>;
+    callGraph: Record<string, string[]>;
+    reverseCallGraph: Record<string, string[]>;
+}
+export declare function generateCodebaseMap(projectRoot: string, projectId: string, apiKey: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Generate a codebase map locally without uploading
+ * Useful for previewing or debugging
+ */
+export declare function generateCodebaseMapLocal(projectRoot: string): {
+    index: CodebaseIndex;
+    markdown: string;
+};

package/dist/helpers/codebase-mapper.js

@@ -0,0 +1,634 @@
+/**
+ * Codebase Mapper
+ *
+ * Client-side AST analysis to generate codebase maps.
+ * Runs in the MCP server and uploads results to the API.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, relative, extname, basename, dirname } from 'path';
+import * as ts from 'typescript';
+import { API_BASE_URL } from './config.js';
+// =============================================================================
+// File Discovery
+// =============================================================================
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo',
+    '__pycache__', '.venv', 'venv', '.tox', 'target', '.idea', '.vscode',
+]);
+const SUPPORTED_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+]);
+function discoverFiles(root) {
+    const files = [];
+    function walk(dir) {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            if (entry.startsWith('.') || IGNORED_DIRS.has(entry))
+                continue;
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (stat.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(root);
+    return files;
+}
+// =============================================================================
+// AST Analysis
+// =============================================================================
+function analyzeFile(filePath, root) {
+    const content = readFileSync(filePath, 'utf-8');
+    const relativePath = relative(root, filePath);
+    const lines = content.split('\n').length;
+    const symbols = [];
+    const imports = [];
+    const exports = [];
+    // Parse with TypeScript
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, filePath.endsWith('.tsx') || filePath.endsWith('.jsx')
+        ? ts.ScriptKind.TSX
+        : ts.ScriptKind.TS);
+    function visit(node) {
+        const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
+        // Track imports
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (ts.isStringLiteral(moduleSpecifier)) {
+                imports.push(moduleSpecifier.text);
+            }
+        }
+        // Track exports
+        if (ts.isExportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (moduleSpecifier && ts.isStringLiteral(moduleSpecifier)) {
+                exports.push(moduleSpecifier.text);
+            }
+        }
+        // Check for export modifier using canHaveModifiers
+        const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+        const isExported = modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        // Functions
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            symbols.push({
+                name: node.name.text,
+                type: 'function',
+                exported: isExported,
+                line,
+                signature: getSignature(node),
+            });
+        }
+        // Arrow functions and const declarations
+        if (ts.isVariableStatement(node)) {
+            const varModifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const isConstExported = varModifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name)) {
+                    const name = decl.name.text;
+                    let symbolType = 'const';
+                    // Detect React components (PascalCase + returns JSX)
+                    if (/^[A-Z]/.test(name) && decl.initializer) {
+                        if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+                            symbolType = 'component';
+                        }
+                    }
+                    // Detect hooks
+                    if (name.startsWith('use') && name.length > 3) {
+                        symbolType = 'function';
+                    }
+                    symbols.push({
+                        name,
+                        type: symbolType,
+                        exported: isConstExported,
+                        line: sourceFile.getLineAndCharacterOfPosition(decl.getStart()).line + 1,
+                    });
+                }
+            }
+        }
+        // Classes
+        if (ts.isClassDeclaration(node) && node.name) {
+            symbols.push({
+                name: node.name.text,
+                type: 'class',
+                exported: isExported,
+                line,
+            });
+        }
+        // Interfaces
+        if (ts.isInterfaceDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'interface',
+                exported: isExported,
+                line,
+            });
+        }
+        // Type aliases
+        if (ts.isTypeAliasDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'type',
+                exported: isExported,
+                line,
+            });
+        }
+        // Enums
+        if (ts.isEnumDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'enum',
+                exported: isExported,
+                line,
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return {
+        path: filePath,
+        relativePath,
+        role: detectFileRole(relativePath, symbols),
+        symbols,
+        imports,
+        exports,
+        dependencies: [], // Populated later
+        dependents: [], // Populated later
+        linesOfCode: lines,
+    };
+}
+function getSignature(node) {
+    if (!node.parameters.length && !node.type)
+        return undefined;
+    const params = node.parameters
+        .map((p) => {
+        const name = p.name.getText();
+        const type = p.type?.getText() || 'any';
+        return `${name}: ${type}`;
+    })
+        .join(', ');
+    const returnType = node.type?.getText() || 'void';
+    return `(${params}) => ${returnType}`;
+}
+function detectFileRole(relativePath, symbols) {
+    const path = relativePath.toLowerCase();
+    const fileName = basename(path, extname(path));
+    // Test files
+    if (path.includes('.test.') || path.includes('.spec.') || path.includes('__tests__')) {
+        return 'test';
+    }
+    // Config files
+    if (fileName.includes('config') || fileName.includes('settings')) {
+        return 'config';
+    }
+    // Entry points
+    if (['index', 'main', 'app'].includes(fileName) && !path.includes('/')) {
+        return 'entry-point';
+    }
+    // Type definitions
+    if (path.includes('/types') || fileName.endsWith('.d') || path.includes('types.ts')) {
+        return 'type-definitions';
+    }
+    // Route handlers (Next.js, Remix, etc.)
+    if (path.includes('/routes/') || path.includes('/pages/') || path.includes('/app/')) {
+        return 'route-handler';
+    }
+    // API endpoints
+    if (path.includes('/api/') || path.includes('/handlers/')) {
+        return 'api-endpoint';
+    }
+    // MCP tools
+    if (path.includes('/tools') || path.includes('tool-handlers')) {
+        return 'mcp-tool';
+    }
+    // Components
+    if (path.includes('/components/') || symbols.some((s) => s.type === 'component')) {
+        return 'component';
+    }
+    // Hooks
+    if (path.includes('/hooks/') || symbols.some((s) => s.name.startsWith('use'))) {
+        return 'hook';
+    }
+    // Models
+    if (path.includes('/models/') || path.includes('/entities/') || path.includes('/schema')) {
+        return 'model';
+    }
+    // Services
+    if (path.includes('/services/') || path.includes('/providers/')) {
+        return 'service';
+    }
+    // Extractors
+    if (path.includes('/extraction/') || path.includes('/extractors/')) {
+        return 'extractor';
+    }
+    // Utilities
+    if (path.includes('/utils/') || path.includes('/helpers/') || path.includes('/lib/')) {
+        return 'utility';
+    }
+    return 'unknown';
+}
+// =============================================================================
+// Dependency Analysis
+// =============================================================================
+function buildDependencyGraph(files, root) {
+    // Build a map from relative import paths to file entries
+    const filesByPath = {};
+    for (const file of Object.values(files)) {
+        // Add with and without extension
+        const relPath = file.relativePath;
+        filesByPath[relPath] = relPath;
+        filesByPath[relPath.replace(/\.[^.]+$/, '')] = relPath;
+        // Add index files
+        if (basename(relPath).startsWith('index.')) {
+            filesByPath[dirname(relPath)] = relPath;
+        }
+    }
+    // Resolve dependencies
+    for (const file of Object.values(files)) {
+        const fileDir = dirname(file.relativePath);
+        for (const imp of file.imports) {
+            // Skip external packages
+            if (!imp.startsWith('.') && !imp.startsWith('/'))
+                continue;
+            // Resolve relative import
+            let resolved = imp.startsWith('.')
+                ? join(fileDir, imp).replace(/\\/g, '/')
+                : imp;
+            // Normalize
+            resolved = resolved.replace(/^\.\//, '');
+            // Find matching file
+            const target = filesByPath[resolved];
+            if (target && target !== file.relativePath) {
+                file.dependencies.push(target);
+                // Add reverse dependency
+                const targetFile = files[target];
+                if (targetFile) {
+                    targetFile.dependents.push(file.relativePath);
+                }
+            }
+        }
+    }
+}
+// =============================================================================
+// Call Graph Building
+// =============================================================================
+function buildCallGraph(files) {
+    const callGraph = {};
+    const reverseCallGraph = {};
+    // Build symbol lookup
+    const symbolFiles = {};
+    for (const file of Object.values(files)) {
+        for (const symbol of file.symbols) {
+            if (symbol.exported) {
+                symbolFiles[symbol.name] = file.relativePath;
+            }
+        }
+    }
+    // For now, use a simple heuristic based on dependencies
+    // Full call graph would require more sophisticated AST analysis
+    for (const file of Object.values(files)) {
+        for (const symbol of file.symbols) {
+            if (symbol.type === 'function' || symbol.type === 'component') {
+                callGraph[symbol.name] = [];
+                reverseCallGraph[symbol.name] = [];
+                // Infer calls from dependencies
+                for (const dep of file.dependencies) {
+                    const depFile = files[dep];
+                    if (depFile) {
+                        for (const depSymbol of depFile.symbols) {
+                            if (depSymbol.exported && (depSymbol.type === 'function' || depSymbol.type === 'component')) {
+                                callGraph[symbol.name].push(depSymbol.name);
+                                if (!reverseCallGraph[depSymbol.name]) {
+                                    reverseCallGraph[depSymbol.name] = [];
+                                }
+                                reverseCallGraph[depSymbol.name].push(symbol.name);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { callGraph, reverseCallGraph };
+}
+// =============================================================================
+// Directory Analysis
+// =============================================================================
+function analyzeDirectories(files, root) {
+    const directories = {};
+    const dirFiles = {};
+    // Group files by directory
+    for (const file of Object.values(files)) {
+        const dir = dirname(file.relativePath) || '.';
+        if (!dirFiles[dir]) {
+            dirFiles[dir] = [];
+        }
+        dirFiles[dir].push(file);
+    }
+    // Analyze each directory
+    for (const [dir, filesInDir] of Object.entries(dirFiles)) {
+        const languages = {};
+        const keyFiles = [];
+        for (const file of filesInDir) {
+            const ext = extname(file.relativePath);
+            languages[ext] = (languages[ext] || 0) + 1;
+            // Key files are entry points or have many exports
+            if (file.role === 'entry-point' || file.symbols.filter((s) => s.exported).length > 5) {
+                keyFiles.push(file.relativePath);
+            }
+        }
+        const primaryLang = Object.entries(languages)
+            .sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+        directories[dir] = {
+            path: dir,
+            role: detectDirectoryRole(dir, filesInDir),
+            fileCount: filesInDir.length,
+            primaryLanguage: primaryLang,
+            keyFiles: keyFiles.slice(0, 3),
+        };
+    }
+    return directories;
+}
+function detectDirectoryRole(dir, files) {
+    const dirLower = dir.toLowerCase();
+    if (dirLower.includes('component'))
+        return 'components';
+    if (dirLower.includes('hook'))
+        return 'hooks';
+    if (dirLower.includes('route') || dirLower.includes('page'))
+        return 'routes';
+    if (dirLower.includes('api') || dirLower.includes('handler'))
+        return 'api';
+    if (dirLower.includes('util') || dirLower.includes('helper') || dirLower.includes('lib'))
+        return 'utilities';
+    if (dirLower.includes('type'))
+        return 'types';
+    if (dirLower.includes('test') || dirLower.includes('spec'))
+        return 'tests';
+    if (dirLower.includes('config'))
+        return 'configuration';
+    if (dirLower.includes('model') || dirLower.includes('schema'))
+        return 'models';
+    if (dirLower.includes('service') || dirLower.includes('provider'))
+        return 'services';
+    // Check file roles
+    const roleCounts = {};
+    for (const file of files) {
+        roleCounts[file.role] = (roleCounts[file.role] || 0) + 1;
+    }
+    const topRole = Object.entries(roleCounts).sort((a, b) => b[1] - a[1])[0];
+    return topRole ? topRole[0] : 'misc';
+}
+// =============================================================================
+// Framework Detection
+// =============================================================================
+function detectFrameworks(root) {
+    const frameworks = [];
+    try {
+        const pkgPath = join(root, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.next)
+                frameworks.push('Next.js');
+            if (deps.react)
+                frameworks.push('React');
+            if (deps.vue)
+                frameworks.push('Vue');
+            if (deps.svelte)
+                frameworks.push('Svelte');
+            if (deps['@tanstack/react-query'])
+                frameworks.push('TanStack Query');
+            if (deps.express)
+                frameworks.push('Express');
+            if (deps.hono)
+                frameworks.push('Hono');
+            if (deps.fastify)
+                frameworks.push('Fastify');
+            if (deps.drizzle)
+                frameworks.push('Drizzle');
+            if (deps.prisma)
+                frameworks.push('Prisma');
+            if (deps.zod)
+                frameworks.push('Zod');
+            if (deps.typescript)
+                frameworks.push('TypeScript');
+        }
+    }
+    catch {
+        // Ignore package.json errors
+    }
+    return frameworks;
+}
+// =============================================================================
+// Markdown Generation
+// =============================================================================
+function generateMarkdown(index) {
+    let md = `# Codebase Map: ${basename(index.projectRoot)}\n\n`;
+    md += `> Generated ${index.generatedAt}\n\n`;
+    // Summary
+    md += `## Summary\n\n`;
+    md += `- **Files:** ${index.summary.totalFiles}\n`;
+    md += `- **Symbols:** ${index.summary.totalSymbols}\n`;
+    md += `- **Frameworks:** ${index.summary.frameworks.join(', ') || 'None detected'}\n\n`;
+    // Languages
+    md += `### Languages\n\n`;
+    for (const [lang, count] of Object.entries(index.summary.languages)) {
+        md += `- ${lang}: ${count} files\n`;
+    }
+    md += '\n';
+    // Directory structure
+    md += `## Structure\n\n`;
+    const sortedDirs = Object.values(index.directories).sort((a, b) => a.path.localeCompare(b.path));
+    for (const dir of sortedDirs) {
+        const indent = '  '.repeat(dir.path.split('/').length - 1);
+        md += `${indent}- **${dir.path}/** (${dir.role}, ${dir.fileCount} files)\n`;
+        if (dir.keyFiles.length > 0) {
+            for (const keyFile of dir.keyFiles) {
+                md += `${indent}  - 📄 ${basename(keyFile)}\n`;
+            }
+        }
+    }
+    md += '\n';
+    // Key entry points
+    const entryPoints = Object.values(index.files).filter((f) => f.role === 'entry-point' || f.symbols.filter((s) => s.exported).length > 10);
+    if (entryPoints.length > 0) {
+        md += `## Entry Points\n\n`;
+        for (const file of entryPoints.slice(0, 10)) {
+            const exportedSymbols = file.symbols.filter((s) => s.exported);
+            md += `### ${file.relativePath}\n`;
+            md += `- **Role:** ${file.role}\n`;
+            md += `- **Lines:** ${file.linesOfCode}\n`;
+            md += `- **Exports:** ${exportedSymbols.length}\n\n`;
+            if (exportedSymbols.length > 0 && exportedSymbols.length <= 20) {
+                for (const sym of exportedSymbols) {
+                    md += `  - \`${sym.name}\` (${sym.type})\n`;
+                }
+                md += '\n';
+            }
+        }
+    }
+    // Key symbols
+    const exportedSymbols = Object.entries(index.symbols)
+        .filter(([_, locs]) => locs.some((l) => l.exported))
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 30);
+    if (exportedSymbols.length > 0) {
+        md += `## Key Symbols\n\n`;
+        md += `| Symbol | Type | Location |\n`;
+        md += `|--------|------|----------|\n`;
+        for (const [name, locs] of exportedSymbols) {
+            const loc = locs[0];
+            md += `| \`${name}\` | ${loc.type} | ${loc.file}:${loc.line} |\n`;
+        }
+        md += '\n';
+    }
+    return md;
+}
+// =============================================================================
+// Main Export
+// =============================================================================
+export async function generateCodebaseMap(projectRoot, projectId, apiKey) {
+    try {
+        // Discover and analyze files
+        const filePaths = discoverFiles(projectRoot);
+        if (filePaths.length === 0) {
+            return { success: false, error: 'No supported files found in project' };
+        }
+        const files = {};
+        const languages = {};
+        let totalSymbols = 0;
+        for (const filePath of filePaths) {
+            try {
+                const entry = analyzeFile(filePath, projectRoot);
+                files[entry.relativePath] = entry;
+                const ext = extname(entry.relativePath);
+                languages[ext] = (languages[ext] || 0) + 1;
+                totalSymbols += entry.symbols.length;
+            }
+            catch (err) {
+                // Skip files that can't be parsed
+                console.error(`Failed to analyze ${filePath}:`, err);
+            }
+        }
+        // Build dependency graph
+        buildDependencyGraph(files, projectRoot);
+        // Build call graph
+        const { callGraph, reverseCallGraph } = buildCallGraph(files);
+        // Analyze directories
+        const directories = analyzeDirectories(files, projectRoot);
+        // Detect frameworks
+        const frameworks = detectFrameworks(projectRoot);
+        // Build symbols index
+        const symbols = {};
+        for (const file of Object.values(files)) {
+            for (const sym of file.symbols) {
+                if (!symbols[sym.name]) {
+                    symbols[sym.name] = [];
+                }
+                symbols[sym.name].push({
+                    file: file.relativePath,
+                    line: sym.line,
+                    type: sym.type,
+                    exported: sym.exported,
+                });
+            }
+        }
+        // Build index
+        const index = {
+            version: '1.0.0',
+            generatedAt: new Date().toISOString(),
+            projectRoot,
+            summary: {
+                totalFiles: Object.keys(files).length,
+                totalSymbols,
+                languages,
+                frameworks,
+            },
+            directories,
+            files,
+            symbols,
+            callGraph,
+            reverseCallGraph,
+        };
+        // Generate markdown
+        const markdown = generateMarkdown(index);
+        // Upload to API
+        const response = await fetch(`${API_BASE_URL}/api/v1/codebase/${projectId}/generate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ index, markdown }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            return { success: false, error: `API error: ${response.status} - ${text}` };
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: String(err) };
+    }
+}
+/**
+ * Generate a codebase map locally without uploading
+ * Useful for previewing or debugging
+ */
+export function generateCodebaseMapLocal(projectRoot) {
+    const filePaths = discoverFiles(projectRoot);
+    const files = {};
+    const languages = {};
+    let totalSymbols = 0;
+    for (const filePath of filePaths) {
+        try {
+            const entry = analyzeFile(filePath, projectRoot);
+            files[entry.relativePath] = entry;
+            const ext = extname(entry.relativePath);
+            languages[ext] = (languages[ext] || 0) + 1;
+            totalSymbols += entry.symbols.length;
+        }
+        catch {
+            // Skip files that can't be parsed
+        }
+    }
+    buildDependencyGraph(files, projectRoot);
+    const { callGraph, reverseCallGraph } = buildCallGraph(files);
+    const directories = analyzeDirectories(files, projectRoot);
+    const frameworks = detectFrameworks(projectRoot);
+    const symbols = {};
+    for (const file of Object.values(files)) {
+        for (const sym of file.symbols) {
+            if (!symbols[sym.name]) {
+                symbols[sym.name] = [];
+            }
+            symbols[sym.name].push({
+                file: file.relativePath,
+                line: sym.line,
+                type: sym.type,
+                exported: sym.exported,
+            });
+        }
+    }
+    const index = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        summary: {
+            totalFiles: Object.keys(files).length,
+            totalSymbols,
+            languages,
+            frameworks,
+        },
+        directories,
+        files,
+        symbols,
+        callGraph,
+        reverseCallGraph,
+    };
+    const markdown = generateMarkdown(index);
+    return { index, markdown };
+}

package/dist/helpers/config.d.ts

@@ -34,7 +34,7 @@ export declare function resolveProjectId(): string;
 export declare function resolveProjectIdAsync(): Promise<string>;
 /**
  * Gets the default project ID (synchronous version)
- * Throws if not already resolved - call resolveProjectIdAsync() first
+ * Checks session-context.md first, then config, then falls back to cwd resolution
  */
 export declare function getDefaultProjectId(): string;
 /**

package/dist/helpers/config.js

@@ -3,6 +3,7 @@
 // =============================================================================
 import { mcpLogger } from '../logger.js';
 import * as fs from 'fs';
+import * as path from 'path';
 import { getConfig, getConfigDir, getProjectsPath, } from './config-manager.js';
 import { getOrRegisterProject } from './project-registration.js';
 // Configuration - now loaded from config manager
@@ -10,6 +11,28 @@ const config = getConfig();
 export const API_BASE_URL = config.apiUrl;
 export const CLAUDETOOLS_DIR = getConfigDir();
 export const PROJECTS_FILE = getProjectsPath();
+const SESSION_CONTEXT_FILE = path.join(CLAUDETOOLS_DIR, 'session-context.md');
+/**
+ * Read project ID from session-context.md (written by session-start hook)
+ * This is the most reliable source since it's set by Claude Code's hook system
+ */
+function getProjectIdFromSessionContext() {
+    try {
+        if (!fs.existsSync(SESSION_CONTEXT_FILE)) {
+            return null;
+        }
+        const content = fs.readFileSync(SESSION_CONTEXT_FILE, 'utf-8');
+        // Parse: **Project ID:** proj_xxxxx
+        const match = content.match(/\*\*Project ID:\*\*\s*(proj_[a-f0-9]{20})/);
+        if (match) {
+            return match[1];
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 // Cache for resolved project ID
 let resolvedProjectId = null;
 /**
@@ -93,6 +116,14 @@ export async function resolveProjectIdAsync() {
         mcpLogger.debug('MEMORY', `Using project ID from env: ${resolvedProjectId}`);
         return resolvedProjectId;
     }
+    // Check session-context.md (written by Claude Code's session-start hook)
+    // This is the most reliable source since MCP server's cwd isn't the project dir
+    const sessionProjectId = getProjectIdFromSessionContext();
+    if (sessionProjectId) {
+        resolvedProjectId = sessionProjectId;
+        mcpLogger.info('MEMORY', `Project resolved from session context: ${resolvedProjectId}`);
+        return resolvedProjectId;
+    }
     const cwd = process.cwd();
     // Check projects.json cache
     const binding = findProjectBinding(cwd);
@@ -134,13 +165,19 @@ export async function resolveProjectIdAsync() {
 let _defaultProjectId = null;
 /**
  * Gets the default project ID (synchronous version)
- * Throws if not already resolved - call resolveProjectIdAsync() first
+ * Checks session-context.md first, then config, then falls back to cwd resolution
  */
 export function getDefaultProjectId() {
     if (_defaultProjectId) {
         return _defaultProjectId;
     }
-    // Try config first
+    // Check session-context.md first (most reliable for MCP server)
+    const sessionProjectId = getProjectIdFromSessionContext();
+    if (sessionProjectId) {
+        _defaultProjectId = sessionProjectId;
+        return _defaultProjectId;
+    }
+    // Try config second
     if (config.defaultProjectId) {
         if (!isValidProjectId(config.defaultProjectId)) {
             // Legacy format - convert to local_ format instead of throwing

package/dist/watcher.js

@@ -4,7 +4,9 @@
 // Monitors project directories for changes and syncs with the API
 import { homedir } from 'os';
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, unlinkSync, watch, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, watch, readdirSync, statSync, mkdirSync } from 'fs';
+import { getProjectTemplate, SECTION_START } from './templates/claude-md.js';
+import { generateCodebaseMap } from './helpers/codebase-mapper.js';
 // -----------------------------------------------------------------------------
 // Constants
 // -----------------------------------------------------------------------------
@@ -136,6 +138,94 @@ function discoverProjects(directories) {
     }
     return projects;
 }
+/**
+ * Ensures .claude/CLAUDE.md exists for a project
+ * Creates it if missing, using the project template
+ */
+function ensureProjectClaudeMd(projectPath, projectId, projectName) {
+    const claudeDir = join(projectPath, '.claude');
+    const claudeMdPath = join(claudeDir, 'CLAUDE.md');
+    // Skip if CLAUDE.md already exists with claudetools section
+    if (existsSync(claudeMdPath)) {
+        try {
+            const content = readFileSync(claudeMdPath, 'utf-8');
+            if (content.includes(SECTION_START)) {
+                return false; // Already has claudetools section
+            }
+            // Has CLAUDE.md but no claudetools section - append it
+            const template = getProjectTemplate(projectId, projectName);
+            writeFileSync(claudeMdPath, content.trimEnd() + '\n' + template);
+            log('info', `Added ClaudeTools section to existing CLAUDE.md: ${projectPath}`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Create .claude directory if needed
+    if (!existsSync(claudeDir)) {
+        try {
+            mkdirSync(claudeDir, { recursive: true });
+        }
+        catch (err) {
+            log('warn', `Could not create .claude directory for ${projectPath}: ${err}`);
+            return false;
+        }
+    }
+    // Create CLAUDE.md with template
+    try {
+        const template = getProjectTemplate(projectId, projectName);
+        writeFileSync(claudeMdPath, template);
+        log('info', `Created CLAUDE.md for project: ${projectPath}`);
+        return true;
+    }
+    catch (err) {
+        log('warn', `Could not create CLAUDE.md for ${projectPath}: ${err}`);
+        return false;
+    }
+}
+/**
+ * Ensures all synced projects have CLAUDE.md files
+ */
+function ensureAllProjectsHaveClaudeMd(bindings) {
+    let created = 0;
+    for (const binding of bindings) {
+        if (binding.local_path && binding.project_id) {
+            if (ensureProjectClaudeMd(binding.local_path, binding.project_id, binding.project_name || 'Unknown')) {
+                created++;
+            }
+        }
+    }
+    if (created > 0) {
+        log('info', `Created CLAUDE.md for ${created} projects`);
+    }
+}
+/**
+ * Generate codebase maps for all synced projects
+ */
+async function generateMapsForProjects(bindings, apiKey) {
+    let generated = 0;
+    for (const binding of bindings) {
+        if (binding.local_path && binding.project_id) {
+            try {
+                log('info', `Generating codebase map for ${binding.project_name || binding.local_path}...`);
+                const result = await generateCodebaseMap(binding.local_path, binding.project_id, apiKey);
+                if (result.success) {
+                    generated++;
+                }
+                else {
+                    log('warn', `Map generation failed for ${binding.project_name}: ${result.error}`);
+                }
+            }
+            catch (err) {
+                log('warn', `Map generation error for ${binding.project_name}: ${err}`);
+            }
+        }
+    }
+    if (generated > 0) {
+        log('info', `Generated codebase maps for ${generated} projects`);
+    }
+}
 // -----------------------------------------------------------------------------
 // API Sync
 // -----------------------------------------------------------------------------
@@ -166,6 +256,12 @@ async function syncProjectsWithAPI(config, system, projects) {
                 projectsData.bindings = data.bindings;
                 projectsData.last_sync = new Date().toISOString();
                 writeFileSync(PROJECTS_FILE, JSON.stringify(projectsData, null, 2));
+                // Auto-create CLAUDE.md for all synced projects
+                ensureAllProjectsHaveClaudeMd(data.bindings);
+                // Generate codebase maps for all projects (async, don't block)
+                generateMapsForProjects(data.bindings, config.apiKey).catch((err) => {
+                    log('warn', `Map generation failed: ${err}`);
+                });
             }
             log('info', `Synced ${projects.length} projects with API`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,8 @@
     "chalk": "^5.6.2",
     "nunjucks": "^3.2.4",
     "ora": "^9.0.0",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "typescript": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",