Ask any question about any codebase and get answers with exact file and line citations — powered by Claude.
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.
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.
npx claude-teach <target> # run without installing
npm install -g claude-teach # or install globallyRequires Node.js 18+ and ANTHROPIC_API_KEY:
export ANTHROPIC_API_KEY=sk-ant-...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 streamingLoading 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...
| 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 |
| 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 |
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.
When you quit with --export course.md, Claude generates a proper onboarding document from your session:
# 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.
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?
Typical 10–15 question session on a medium repo: ~$0.10–0.30. Export adds ~$0.05–0.10.
"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)
git clone https://github.com/amritessh/claude-teach && cd claude-teach
npm install && npm run dev
node dist/index.js .MIT