claude-teach 0.1.0

package/dist/lib/fs-reader.js

@@ -0,0 +1,179 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLocalRepo = readLocalRepo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", ".next", "__pycache__",
+    ".cache", "coverage", ".nyc_output", "vendor", ".turbo",
+]);
+const SOURCE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java",
+    ".rb", ".php", ".cs", ".cpp", ".c", ".h", ".swift", ".kt",
+    ".md", ".yaml", ".yml", ".toml", ".json", ".sh", ".sql",
+]);
+const PRIORITY_FILES = new Set([
+    "package.json", "README.md", "README.rst", "README.txt",
+    "CLAUDE.md", "ARCHITECTURE.md", "Makefile", "Dockerfile",
+    "docker-compose.yml", "pyproject.toml", "go.mod", "Cargo.toml",
+    "tsconfig.json", ".env.example",
+]);
+const MAX_FILE_SIZE = 100 * 1024;
+const TOKEN_BUDGET = 80_000;
+function walkDir(dir, base, results) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        const rel = path.relative(base, full);
+        if (entry.isDirectory()) {
+            walkDir(full, base, results);
+        }
+        else if (entry.isFile()) {
+            results.push(rel);
+        }
+    }
+}
+function buildTree(paths) {
+    const lines = [];
+    for (const p of paths.slice(0, 200)) {
+        const depth = p.split(path.sep).length - 1;
+        const indent = "  ".repeat(depth);
+        lines.push(`${indent}${path.basename(p)}`);
+    }
+    return lines.join("\n");
+}
+function getGitLog(dir) {
+    try {
+        const out = (0, child_process_1.execSync)('git log --oneline --format="%h|%s|%ai|%an" -20', { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });
+        return out
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => {
+            const [sha, message, date, ...authorParts] = line.split("|");
+            return { sha, message, date, author: authorParts.join("|") };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function detectLanguage(files) {
+    const extCount = {};
+    for (const f of files) {
+        const ext = path.extname(f);
+        if (ext)
+            extCount[ext] = (extCount[ext] ?? 0) + 1;
+    }
+    const sorted = Object.entries(extCount).sort((a, b) => b[1] - a[1]);
+    const extToLang = {
+        ".ts": "TypeScript", ".tsx": "TypeScript", ".js": "JavaScript",
+        ".py": "Python", ".go": "Go", ".rs": "Rust", ".java": "Java",
+        ".rb": "Ruby", ".php": "PHP",
+    };
+    return sorted.length > 0 ? (extToLang[sorted[0][0]] ?? sorted[0][0]) : "Unknown";
+}
+async function readLocalRepo(dirPath) {
+    const absPath = path.resolve(dirPath);
+    if (!fs.existsSync(absPath))
+        throw new Error(`Path not found: ${absPath}`);
+    const allPaths = [];
+    walkDir(absPath, absPath, allPaths);
+    const eligible = allPaths.filter((p) => {
+        const ext = path.extname(p);
+        const basename = path.basename(p);
+        const stat = fs.statSync(path.join(absPath, p));
+        if (stat.size > MAX_FILE_SIZE)
+            return false;
+        return PRIORITY_FILES.has(basename) || SOURCE_EXTENSIONS.has(ext);
+    });
+    eligible.sort((a, b) => {
+        const aPriority = PRIORITY_FILES.has(path.basename(a)) ? 0 : 1;
+        const bPriority = PRIORITY_FILES.has(path.basename(b)) ? 0 : 1;
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        return a.split(path.sep).length - b.split(path.sep).length;
+    });
+    const files = [];
+    let totalChars = 0;
+    let truncated = false;
+    for (const rel of eligible) {
+        if (totalChars >= TOKEN_BUDGET) {
+            truncated = true;
+            break;
+        }
+        try {
+            const content = fs.readFileSync(path.join(absPath, rel), "utf-8");
+            files.push({ path: rel, content, size: content.length });
+            totalChars += content.length;
+        }
+        catch {
+            // skip unreadable files
+        }
+    }
+    const repoName = path.basename(absPath);
+    let packageJson = {};
+    const pkgFile = files.find((f) => f.path === "package.json");
+    if (pkgFile) {
+        try {
+            packageJson = JSON.parse(pkgFile.content);
+        }
+        catch { /* ignore */ }
+    }
+    return {
+        owner: "local",
+        repo: repoName,
+        defaultBranch: "main",
+        description: packageJson.description ?? "",
+        stars: 0,
+        language: detectLanguage(allPaths),
+        files,
+        directoryTree: buildTree(allPaths),
+        languages: {},
+        recentCommits: getGitLog(absPath),
+        truncated,
+    };
+}
+//# sourceMappingURL=fs-reader.js.map

package/dist/lib/github-reader.d.ts

@@ -0,0 +1,26 @@
+export interface RepoFile {
+    path: string;
+    content: string;
+    size: number;
+}
+export interface GitCommit {
+    sha: string;
+    message: string;
+    date: string;
+    author: string;
+}
+export interface RepoContext {
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+    description: string;
+    stars: number;
+    language: string;
+    files: RepoFile[];
+    directoryTree: string;
+    languages: Record<string, number>;
+    recentCommits: GitCommit[];
+    truncated: boolean;
+}
+export declare function readGitHubRepo(input: string, githubToken?: string): Promise<RepoContext>;
+//# sourceMappingURL=github-reader.d.ts.map

package/dist/lib/github-reader.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readGitHubRepo = readGitHubRepo;
+const rest_1 = require("@octokit/rest");
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", ".next", "__pycache__",
+    ".cache", "coverage", ".nyc_output", "vendor", ".turbo",
+]);
+const PRIORITY_FILES = new Set([
+    "package.json", "README.md", "README.rst", "README.txt",
+    "CLAUDE.md", "ARCHITECTURE.md", "Makefile", "Dockerfile",
+    "docker-compose.yml", "pyproject.toml", "go.mod", "Cargo.toml",
+    "tsconfig.json", ".env.example",
+]);
+const SOURCE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java",
+    ".rb", ".php", ".cs", ".cpp", ".c", ".h", ".swift", ".kt",
+    ".md", ".yaml", ".yml", ".toml", ".json", ".sh", ".sql",
+]);
+const MAX_FILE_SIZE = 100 * 1024; // 100KB
+const TOKEN_BUDGET = 80_000; // ~80K chars
+function parseGitHubUrl(input) {
+    // Handle: https://github.com/owner/repo, github.com/owner/repo, owner/repo
+    const cleaned = input
+        .replace(/^https?:\/\//, "")
+        .replace(/^github\.com\//, "")
+        .replace(/\.git$/, "")
+        .split("#")[0]
+        .split("?")[0]
+        .trim();
+    const parts = cleaned.split("/").filter(Boolean);
+    if (parts.length < 2)
+        throw new Error(`Cannot parse GitHub URL: ${input}`);
+    return { owner: parts[0], repo: parts[1] };
+}
+function buildTree(paths) {
+    const tree = {};
+    for (const p of paths) {
+        const parts = p.split("/");
+        let node = tree;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (i === parts.length - 1) {
+                node[part] = null;
+            }
+            else {
+                if (!node[part])
+                    node[part] = {};
+                node = node[part];
+            }
+        }
+    }
+    function render(node, indent = "") {
+        return Object.entries(node)
+            .map(([key, val]) => {
+            if (val === null)
+                return `${indent}${key}`;
+            return `${indent}${key}/\n${render(val, indent + "  ")}`;
+        })
+            .join("\n");
+    }
+    return render(tree);
+}
+async function readGitHubRepo(input, githubToken) {
+    const { owner, repo } = parseGitHubUrl(input);
+    const octokit = new rest_1.Octokit({ auth: githubToken });
+    // Fetch repo metadata, tree, languages, and commits in parallel
+    const [repoData, langData, commitsData] = await Promise.all([
+        octokit.repos.get({ owner, repo }),
+        octokit.repos.listLanguages({ owner, repo }),
+        octokit.repos.listCommits({ owner, repo, per_page: 15 }),
+    ]);
+    const defaultBranch = repoData.data.default_branch;
+    // Get full file tree
+    const treeData = await octokit.git.getTree({
+        owner,
+        repo,
+        tree_sha: defaultBranch,
+        recursive: "1",
+    });
+    const allFiles = treeData.data.tree.filter((f) => f.type === "blob" && f.path);
+    // Filter out skipped directories and non-source files
+    const eligible = allFiles.filter((f) => {
+        const parts = f.path.split("/");
+        if (parts.some((p) => SKIP_DIRS.has(p)))
+            return false;
+        if ((f.size ?? 0) > MAX_FILE_SIZE)
+            return false;
+        const ext = "." + f.path.split(".").pop();
+        const basename = f.path.split("/").pop();
+        return PRIORITY_FILES.has(basename) || SOURCE_EXTENSIONS.has(ext);
+    });
+    // Sort: priority files first, then by path length (shorter = closer to root)
+    eligible.sort((a, b) => {
+        const aName = a.path.split("/").pop();
+        const bName = b.path.split("/").pop();
+        const aPriority = PRIORITY_FILES.has(aName) ? 0 : 1;
+        const bPriority = PRIORITY_FILES.has(bName) ? 0 : 1;
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        return a.path.split("/").length - b.path.split("/").length;
+    });
+    // Fetch file contents up to token budget
+    const files = [];
+    let totalChars = 0;
+    let truncated = false;
+    for (const file of eligible) {
+        if (totalChars >= TOKEN_BUDGET) {
+            truncated = true;
+            break;
+        }
+        try {
+            const contentData = await octokit.repos.getContent({
+                owner,
+                repo,
+                path: file.path,
+            });
+            const data = contentData.data;
+            if (!data.content || data.encoding !== "base64")
+                continue;
+            const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+            files.push({ path: file.path, content: decoded, size: decoded.length });
+            totalChars += decoded.length;
+        }
+        catch {
+            // Skip files that fail to fetch
+        }
+    }
+    const recentCommits = commitsData.data.map((c) => ({
+        sha: c.sha.slice(0, 7),
+        message: c.commit.message.split("\n")[0],
+        date: c.commit.author?.date ?? "",
+        author: c.commit.author?.name ?? "unknown",
+    }));
+    return {
+        owner,
+        repo,
+        defaultBranch,
+        description: repoData.data.description ?? "",
+        stars: repoData.data.stargazers_count ?? 0,
+        language: repoData.data.language ?? "",
+        files,
+        directoryTree: buildTree(allFiles.map((f) => f.path).slice(0, 200)),
+        languages: langData.data,
+        recentCommits,
+        truncated,
+    };
+}
+//# sourceMappingURL=github-reader.js.map

package/dist/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./auth";
+export * from "./client";
+export * from "./github-reader";
+export * from "./fs-reader";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auth"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./github-reader"), exports);
+__exportStar(require("./fs-reader"), exports);
+//# sourceMappingURL=index.js.map

package/dist/session.d.ts

@@ -0,0 +1,7 @@
+import type { RepoContext } from "./lib";
+export interface Turn {
+    question: string;
+    answer: string;
+}
+export declare function runSession(ctx: RepoContext, exportPath: string | undefined, stream: boolean): Promise<Turn[]>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSession = runSession;
+const readline = __importStar(require("readline"));
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const lib_1 = require("./lib");
+function buildSystemPrompt(ctx) {
+    const fileIndex = ctx.files.map((f) => `- ${f.path}`).join("\n");
+    const fileContents = ctx.files
+        .map((f) => {
+        const ext = f.path.split(".").pop() ?? "";
+        return `### ${f.path}\n\`\`\`${ext}\n${f.content.slice(0, 6000)}\n\`\`\``;
+    })
+        .join("\n\n");
+    return `You are an expert software engineer teaching a developer how the codebase "${ctx.owner}/${ctx.repo}" works.
+
+## About this repo
+- Description: ${ctx.description || "N/A"}
+- Primary language: ${ctx.language}
+- Default branch: ${ctx.defaultBranch}
+
+## File Index
+${fileIndex}
+
+## File Contents
+${fileContents}
+
+${ctx.truncated ? "\n> Note: Repository was truncated to fit context window. Answer based on what is available." : ""}
+
+## Instructions
+- Answer questions about this codebase specifically, based on the actual code above
+- Always cite specific files and line numbers when referencing code, e.g. \`src/auth.ts:42\`
+- If asked how something works, trace through the actual code step by step
+- If you don't know something from the provided code, say so — don't guess
+- Keep answers focused and practical
+- Use markdown formatting for clarity`;
+}
+async function runSession(ctx, exportPath, stream) {
+    const client = new sdk_1.default({ apiKey: (0, lib_1.resolveAnthropicKey)() });
+    const systemPrompt = buildSystemPrompt(ctx);
+    const history = [];
+    const turns = [];
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+    });
+    console.log(`\nLoaded ${ctx.files.length} files from ${ctx.owner}/${ctx.repo}`);
+    console.log('Ask questions about this codebase. Type "exit" or press Ctrl+C to quit.\n');
+    const ask = () => new Promise((resolve) => rl.question("You: ", resolve));
+    while (true) {
+        let question;
+        try {
+            question = (await ask()).trim();
+        }
+        catch {
+            break; // readline closed
+        }
+        if (!question)
+            continue;
+        if (question.toLowerCase() === "exit" || question.toLowerCase() === "quit")
+            break;
+        history.push({ role: "user", content: question });
+        process.stdout.write("\nClaude: ");
+        let answer = "";
+        if (stream) {
+            const streamResp = client.messages.stream({
+                model: "claude-opus-4-5",
+                max_tokens: 2048,
+                system: systemPrompt,
+                messages: history,
+            });
+            for await (const event of streamResp) {
+                if (event.type === "content_block_delta" &&
+                    event.delta.type === "text_delta") {
+                    process.stdout.write(event.delta.text);
+                    answer += event.delta.text;
+                }
+            }
+        }
+        else {
+            const response = await client.messages.create({
+                model: "claude-opus-4-5",
+                max_tokens: 2048,
+                system: systemPrompt,
+                messages: history,
+            });
+            const block = response.content[0];
+            answer = block.type === "text" ? block.text : "";
+            process.stdout.write(answer);
+        }
+        console.log("\n");
+        history.push({ role: "assistant", content: answer });
+        turns.push({ question, answer });
+        // Trim history to last 20 turns to stay within context
+        if (history.length > 40) {
+            history.splice(0, 2);
+        }
+    }
+    rl.close();
+    return turns;
+}
+//# sourceMappingURL=session.js.map

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "claude-teach",
+  "version": "0.1.0",
+  "description": "Interactive Q&A about any codebase, powered by Claude",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-teach": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@octokit/rest": "^19.0.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/course.ts

@@ -0,0 +1,56 @@
+import { generateText } from "./lib";
+import type { RepoContext } from "./lib";
+import type { Turn } from "./session";
+import * as fs from "fs";
+
+export async function exportCourse(
+  ctx: RepoContext,
+  turns: Turn[],
+  outputPath: string
+): Promise<void> {
+  if (turns.length === 0) {
+    console.log("No session turns to export.");
+    return;
+  }
+
+  const sessionTranscript = turns
+    .map((t, i) => `## Q${i + 1}: ${t.question}\n\n${t.answer}`)
+    .join("\n\n---\n\n");
+
+  const prompt = `You are creating a structured course document from a Q&A session about the codebase "${ctx.owner}/${ctx.repo}".
+
+Here is the Q&A session transcript:
+
+${sessionTranscript}
+
+Convert this into a well-structured course document with:
+
+# ${ctx.owner}/${ctx.repo} — Codebase Guide
+
+## Introduction
+Brief intro to what this codebase does and what a developer will learn from this guide.
+
+## Table of Contents
+Numbered list of sections based on the topics covered in the Q&A.
+
+## [Section for each major topic covered]
+Reorganize and expand the Q&A content into coherent sections with:
+- Clear explanations
+- Code examples (preserve the file:line citations)
+- Key takeaways at the end of each section
+
+## Summary
+What a developer now knows after reading this guide and next steps.
+
+Write the course document only. Make it genuinely useful for onboarding a new developer.`;
+
+  console.log("\nGenerating course document...");
+  const courseContent = await generateText(
+    "You are an expert technical writer creating developer onboarding documentation.",
+    prompt,
+    4096
+  );
+
+  fs.writeFileSync(outputPath, courseContent, "utf-8");
+  console.log(`Course exported to: ${outputPath}`);
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readGitHubRepo, readLocalRepo, resolveGitHubToken } from "./lib";
+import { runSession } from "./session";
+import { exportCourse } from "./course";
+
+const program = new Command();
+
+program
+  .name("claude-teach")
+  .description("Interactive Q&A about any codebase, powered by Claude")
+  .version("0.1.0")
+  .argument("<source>", "GitHub URL or local path")
+  .option("--export <file>", "Export session as a course document when you quit")
+  .option("--no-stream", "Disable streaming output")
+  .option("--github-token <token>", "GitHub token for private/large repos")
+  .action(async (source: string, opts) => {
+    try {
+      console.log(`Loading repository: ${source}`);
+
+      const isGitHub =
+        source.startsWith("https://github.com") ||
+        source.startsWith("github.com") ||
+        /^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+$/.test(source);
+
+      const ctx = isGitHub
+        ? await readGitHubRepo(source, opts.githubToken ?? resolveGitHubToken())
+        : await readLocalRepo(source);
+
+      const turns = await runSession(ctx, opts.export, opts.stream !== false);
+
+      if (opts.export && turns.length > 0) {
+        await exportCourse(ctx, turns, opts.export);
+      }
+
+      console.log("Session ended.");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ERR_USE_AFTER_CLOSE") {
+        process.exit(0);
+      }
+      console.error("Error:", err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+program.parse();