claude-teach 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# claude-teach
+
+**Ask any question about any codebase and get answers with exact file and line citations — powered by Claude.**
+
+[![npm version](https://img.shields.io/npm/v/claude-teach)](https://www.npmjs.com/package/claude-teach)
+[![npm downloads](https://img.shields.io/npm/dm/claude-teach)](https://www.npmjs.com/package/claude-teach)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+`claude-teach` loads an entire codebase into memory and opens an interactive terminal session where you can ask questions about it. Claude answers using the actual code — not general knowledge — and cites exact file paths and line numbers. When you're done, export the whole session as a structured course document.
+
+![Demo](demo.gif)
+
+---
+
+## Why this exists
+
+Understanding an unfamiliar codebase is one of the most time-consuming parts of software engineering. `claude-teach` gives you a guide who has read every file and can answer:
+
+- *"How does authentication work in this app?"*
+- *"Walk me through the request lifecycle end to end"*
+- *"What's the correct way to add a new API endpoint here?"*
+- *"Where is rate limiting implemented?"*
+
+Every answer cites the real `file:line`. No hallucination. No guessing.
+
+---
+
+## Installation
+
+```bash
+npx claude-teach <target>          # run without installing
+npm install -g claude-teach        # or install globally
+```
+
+Requires Node.js 18+ and `ANTHROPIC_API_KEY`:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Usage
+
+```bash
+npx claude-teach https://github.com/expressjs/express   # GitHub repo
+npx claude-teach expressjs/express                       # short form
+npx claude-teach .                                       # current directory
+npx claude-teach ~/projects/my-app                       # local path
+npx claude-teach . --export onboarding-guide.md          # export session as doc
+npx claude-teach . --no-stream                           # disable streaming
+```
+
+### Session example
+
+```
+Loading repository: expressjs/express
+Read 47 files from expressjs/express
+
+Ask questions about this codebase. Type "exit" or Ctrl+C to quit.
+
+You: how does routing work?
+
+Claude: Express routing is built around a Router class in `lib/router/index.js`.
+
+When you call `app.get('/path', handler)`, Express calls `router.route(path)`
+(lib/router/index.js:491) which creates a Route object (lib/router/route.js)
+and adds it to the stack.
+
+Each request passes through `router.handle()` (lib/router/index.js:136), which
+iterates the Layer stack. Each Layer wraps a middleware function or a Route...
+
+You: what's a Layer?
+
+Claude: A Layer is defined in `lib/router/layer.js:1`. It wraps:
+- A path pattern (converted to regexp via path-to-regexp)
+- A handler function
+- Match options (case sensitivity, strict mode)
+
+The key method is `layer.match(path)` at line 103...
+```
+
+---
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--export <file>` | — | Export full session as a course document on exit |
+| `--no-stream` | streaming on | Disable token-by-token streaming |
+| `--github-token <token>` | `$GITHUB_TOKEN` | Token for private repos / higher rate limits |
+
+### Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key |
+| `GITHUB_TOKEN` | No | Raises GitHub rate limit from 60 to 5,000 req/hr |
+
+---
+
+## How it works
+
+```
+Input (URL or path)
+  → Load repo: fetch files via GitHub API or walk filesystem
+  → Build system prompt: embed all file contents + file index
+  → REPL loop: each question appended to message history, streamed response
+  → On exit with --export: reorganize Q&A into structured course document
+```
+
+**File prioritization:** When the repo is too large for one context window, files are prioritized by: entry points and configs first, then by directory depth (shallower = higher priority). Up to ~80,000 chars total.
+
+**Citations:** Claude is instructed to always reference code as `filename.ts:42`. It traces through actual functions in the loaded files rather than relying on general framework knowledge.
+
+**Context window management:** Session history is trimmed to the last 20 turns to prevent context overflow during long sessions.
+
+---
+
+## The `--export` course document
+
+When you quit with `--export course.md`, Claude generates a proper onboarding document from your session:
+
+```markdown
+# expressjs/express — Codebase Guide
+
+## Introduction
+## Table of Contents
+1. Routing System
+2. Middleware Pipeline
+3. Request / Response Lifecycle
+
+## 1. Routing System
+Routing centers on the Router class (`lib/router/index.js`). When you call
+`app.get('/path', fn)`, Express calls `router.route(path)` at line 491...
+
+## Summary
+After reading this guide you understand how requests flow through Express...
+```
+
+Use cases: team onboarding docs, open source contributor guides, personal reference for unfamiliar codebases.
+
+---
+
+## Questions that work well
+
+```
+how does [authentication / caching / queuing] work?
+walk me through a request lifecycle end to end
+what's the difference between [classA] and [classB]?
+how do I add a new [endpoint / command / model]?
+what does [FileName.ts] do and why does it exist?
+which files would I need to change to add [feature]?
+what are the most important files to understand first?
+```
+
+---
+
+## Cost
+
+Typical 10–15 question session on a medium repo: **~$0.10–0.30**. Export adds ~$0.05–0.10.
+
+---
+
+## Troubleshooting
+
+**"I don't have information about that file"** — Repo too large to fully load. Ask about core/entry-point files which are always prioritized.
+
+**GitHub rate limit errors** — `npx claude-teach owner/repo --github-token $(gh auth token)`
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/amritessh/claude-teach && cd claude-teach
+npm install && npm run dev
+node dist/index.js .
+```
+
+## License
+
+MIT

package/dist/course.d.ts

@@ -0,0 +1,4 @@
+import type { RepoContext } from "./lib";
+import type { Turn } from "./session";
+export declare function exportCourse(ctx: RepoContext, turns: Turn[], outputPath: string): Promise<void>;
+//# sourceMappingURL=course.d.ts.map

package/dist/course.js

@@ -0,0 +1,78 @@
+"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.exportCourse = exportCourse;
+const lib_1 = require("./lib");
+const fs = __importStar(require("fs"));
+async function exportCourse(ctx, turns, outputPath) {
+    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 (0, lib_1.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}`);
+}
+//# sourceMappingURL=course.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const lib_1 = require("./lib");
+const session_1 = require("./session");
+const course_1 = require("./course");
+const program = new commander_1.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, 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 (0, lib_1.readGitHubRepo)(source, opts.githubToken ?? (0, lib_1.resolveGitHubToken)())
+            : await (0, lib_1.readLocalRepo)(source);
+        const turns = await (0, session_1.runSession)(ctx, opts.export, opts.stream !== false);
+        if (opts.export && turns.length > 0) {
+            await (0, course_1.exportCourse)(ctx, turns, opts.export);
+        }
+        console.log("Session ended.");
+    }
+    catch (err) {
+        if (err.code === "ERR_USE_AFTER_CLOSE") {
+            process.exit(0);
+        }
+        console.error("Error:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/lib/auth.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveAnthropicKey(): string;
+export declare function resolveGitHubToken(): string | undefined;
+//# sourceMappingURL=auth.d.ts.map

package/dist/lib/auth.js

@@ -0,0 +1,93 @@
+"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.resolveAnthropicKey = resolveAnthropicKey;
+exports.resolveGitHubToken = resolveGitHubToken;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function readEnvFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    const lines = fs.readFileSync(filePath, "utf-8").split("\n");
+    const result = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+        result[key] = val;
+    }
+    return result;
+}
+function resolveAnthropicKey() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return process.env.ANTHROPIC_API_KEY;
+    const envFile = readEnvFile(path.join(process.cwd(), ".env"));
+    if (envFile.ANTHROPIC_API_KEY)
+        return envFile.ANTHROPIC_API_KEY;
+    const credFile = path.join(os.homedir(), ".anthropic", "credentials");
+    if (fs.existsSync(credFile)) {
+        const creds = readEnvFile(credFile);
+        if (creds.ANTHROPIC_API_KEY)
+            return creds.ANTHROPIC_API_KEY;
+    }
+    throw new Error("ANTHROPIC_API_KEY not found.\n" +
+        "Set it via:\n" +
+        "  export ANTHROPIC_API_KEY=sk-ant-...\n" +
+        "  or add it to .env in your current directory");
+}
+function resolveGitHubToken() {
+    if (process.env.GITHUB_TOKEN)
+        return process.env.GITHUB_TOKEN;
+    const envFile = readEnvFile(path.join(process.cwd(), ".env"));
+    if (envFile.GITHUB_TOKEN)
+        return envFile.GITHUB_TOKEN;
+    try {
+        const { execSync } = require("child_process");
+        const token = execSync("gh auth token 2>/dev/null", { encoding: "utf-8" }).trim();
+        if (token)
+            return token;
+    }
+    catch {
+        // gh CLI not available or not logged in
+    }
+    return undefined;
+}
+//# sourceMappingURL=auth.js.map

package/dist/lib/client.d.ts

@@ -0,0 +1,11 @@
+import Anthropic from "@anthropic-ai/sdk";
+export declare function generateText(system: string, prompt: string, maxTokens?: number): Promise<string>;
+export declare function streamText(system: string, prompt: string, maxTokens?: number): AsyncGenerator<string>;
+export type MessageParam = Anthropic.MessageParam;
+export type Tool = Anthropic.Tool;
+export interface ToolLoopResult {
+    finalText: string;
+    iterations: number;
+}
+export declare function runToolLoop(system: string, initialPrompt: string, tools: Tool[], toolExecutor: (name: string, input: Record<string, unknown>) => Promise<unknown>, maxIterations?: number): Promise<ToolLoopResult>;
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateText = generateText;
+exports.streamText = streamText;
+exports.runToolLoop = runToolLoop;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const auth_1 = require("./auth");
+let _client = null;
+function getClient() {
+    if (!_client) {
+        _client = new sdk_1.default({ apiKey: (0, auth_1.resolveAnthropicKey)() });
+    }
+    return _client;
+}
+const DEFAULT_MODEL = "claude-opus-4-5";
+async function generateText(system, prompt, maxTokens = 4096) {
+    const client = getClient();
+    const response = await client.messages.create({
+        model: DEFAULT_MODEL,
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: "user", content: prompt }],
+    });
+    const block = response.content[0];
+    if (block.type !== "text")
+        throw new Error("Unexpected response type");
+    return block.text;
+}
+async function* streamText(system, prompt, maxTokens = 4096) {
+    const client = getClient();
+    const stream = client.messages.stream({
+        model: DEFAULT_MODEL,
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: "user", content: prompt }],
+    });
+    for await (const event of stream) {
+        if (event.type === "content_block_delta" &&
+            event.delta.type === "text_delta") {
+            yield event.delta.text;
+        }
+    }
+}
+async function runToolLoop(system, initialPrompt, tools, toolExecutor, maxIterations = 20) {
+    const client = getClient();
+    const messages = [
+        { role: "user", content: initialPrompt },
+    ];
+    let iterations = 0;
+    let finalText = "";
+    while (iterations < maxIterations) {
+        iterations++;
+        const response = await client.messages.create({
+            model: DEFAULT_MODEL,
+            max_tokens: 8096,
+            system,
+            tools,
+            messages,
+        });
+        const assistantContent = response.content;
+        messages.push({ role: "assistant", content: assistantContent });
+        if (response.stop_reason === "end_turn") {
+            const textBlock = assistantContent.find((b) => b.type === "text");
+            if (textBlock && textBlock.type === "text")
+                finalText = textBlock.text;
+            break;
+        }
+        if (response.stop_reason === "tool_use") {
+            const toolResults = [];
+            for (const block of assistantContent) {
+                if (block.type !== "tool_use")
+                    continue;
+                try {
+                    const result = await toolExecutor(block.name, block.input);
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: block.id,
+                        content: typeof result === "string" ? result : JSON.stringify(result),
+                    });
+                }
+                catch (err) {
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: block.id,
+                        content: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                        is_error: true,
+                    });
+                }
+            }
+            messages.push({ role: "user", content: toolResults });
+            continue;
+        }
+        break;
+    }
+    return { finalText, iterations };
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1,3 @@
+import type { RepoContext } from "./github-reader";
+export declare function readLocalRepo(dirPath: string): Promise<RepoContext>;
+//# sourceMappingURL=fs-reader.d.ts.map