ted-mosby

"Kids, I'm going to tell you an incredible story... the story of your codebase architecture."

An AI-powered CLI that does two things:

1. Generates architectural wikis with source code traceability (file:line references)
2. Works as an agentic coding assistant like Claude Code

Built with buildanagentworkshop.com

Point Ted Mosby at any codebase and get a complete architectural wiki:

ted-mosby generate -r ./my-project --site

This creates:

• Architecture Overview with Mermaid diagrams
• Module Documentation with source traceability
• Data Flow Documentation
• Getting Started Guides
• Interactive static site with search, keyboard nav, dark mode

Every concept links directly to source code (src/auth/jwt.ts:23-67), so you can navigate from docs to implementation.

Under the hood, Ted Mosby is a full agentic coding assistant powered by Claude. It doesn't just template docs—it:

• Explores your codebase using filesystem tools
• Searches semantically via RAG embeddings (FAISS + all-MiniLM-L6-v2)
• Reasons about architecture to identify patterns and relationships
• Writes and verifies documentation with automatic link checking

# The agent runs autonomously, reading files, searching code, writing docs
ted-mosby generate -r ./my-project --verbose

# Continue where you left off—agent resumes with cached context
ted-mosby continue -r ./my-project --skip-index

The same RAG system that powers documentation generation gives the agent deep, semantic understanding of your codebase—like Claude Code, but with your entire project pre-indexed for instant retrieval.

• Node.js >= 18.0.0
• Anthropic API key - Get one at console.anthropic.com

export ANTHROPIC_API_KEY=your-api-key-here

# Generate wiki with interactive site in one command
ted-mosby generate -r ./my-project --site

# Or for a GitHub repository
ted-mosby generate -r https://github.com/user/repo --site

• Markdown wiki: Open wiki/README.md
• Interactive site: Open wiki/site/index.html in your browser

The static site includes search, navigation, keyboard shortcuts, and works offline.

# Basic: Generate wiki for current directory
ted-mosby generate -r .

# With interactive static site
ted-mosby generate -r ./my-project --site

# Custom site title and theme
ted-mosby generate -r ./my-project --site --site-title "My Project Docs" --theme dark

# Generate site only (if wiki already exists)
ted-mosby generate -r ./my-project --site-only

# Specify output directory
ted-mosby generate -r ./my-project -o ./docs/architecture

# Focus on a specific subdirectory
ted-mosby generate -r ./my-project -p src/core

# Verbose output (see what the agent is doing)
ted-mosby generate -r ./my-project -v

# Estimate time/cost before running (dry run)
ted-mosby generate -r ./my-project -e

Resume generation to fix broken links or add missing pages:

# Check for and generate missing pages
ted-mosby continue -r ./my-project -o ./wiki

# Just verify (don't generate)
ted-mosby continue -r ./my-project -o ./wiki --verify-only

# Use cached index for faster iteration
ted-mosby continue -r ./my-project -o ./wiki --skip-index

Search your wiki from the command line:

# Search wiki content
ted-mosby search "authentication flow" -w ./wiki

# Hybrid search (keyword + semantic)
ted-mosby search "how does login work" -w ./wiki --hybrid

Start an MCP server for AI assistant integration (Claude Desktop, Claude Code):

# Start MCP server for a wiki
ted-mosby mcp-server -w ./wiki

# With code search (requires RAG index)
ted-mosby mcp-server -w ./wiki -r ./my-project

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-wiki": {
      "command": "ted-mosby",
      "args": ["mcp-server", "-w", "/path/to/wiki"]
    }
  }
}

Create portable wiki packages for sharing:

# Create package (includes wiki + RAG index)
ted-mosby pack -w ./wiki -o ./my-wiki.archiwiki

# Extract package
ted-mosby unpack -p ./my-wiki.archiwiki -o ./extracted

# Extract wiki only (no RAG index)
ted-mosby unpack -p ./my-wiki.archiwiki -o ./extracted --wiki-only

For repositories with 10,000+ files:

# Limit indexed chunks (reduces memory usage)
ted-mosby generate -r ./large-project --max-chunks 5000

# Reduce search results per query
ted-mosby generate -r ./large-project --max-results 5

# Batched processing (for very large repos)
ted-mosby generate -r ./large-project --batch-size 3000

Bypass Claude Code billing and use your API credits directly:

# Uses ANTHROPIC_API_KEY directly
ted-mosby generate -r ./my-project --direct-api

# Combine with skip-index for fast iteration
ted-mosby generate -r ./my-project --direct-api --skip-index

# Skip re-indexing (use cached embeddings)
ted-mosby generate -r ./my-project --skip-index

# Limit agent turns (reduces cost)
ted-mosby generate -r ./my-project --max-turns 50

When you use --site, Ted Mosby generates a fully interactive documentation site:

• Full-text search - Instant search across all pages (Cmd/Ctrl+K)
• AI Chat Assistant - Ask questions about your codebase (--ai-chat)
• Keyboard navigation - Arrow keys, vim-style (j/k/h/l)
• Dark/light mode - Respects system preference or manual toggle
• Table of contents - Auto-generated from headings
• Mobile responsive - Works on all devices
• Offline capable - No server required, AI runs client-side
• Mermaid diagrams - Rendered automatically

Add an interactive AI assistant to your documentation site:

ted-mosby generate -r ./my-project --site --ai-chat

The chat assistant:

• Runs entirely in the browser (SmolLM2 via transformers.js)
• Searches your docs semantically to answer questions
• Works offline after initial model download
• Includes "codemap" mode for architecture visualization

When you run Ted Mosby:

1. Repository Analysis - The agent scans your codebase structure
2. Semantic Indexing - Creates embeddings for intelligent code search
3. Architecture Discovery - Identifies patterns, components, and relationships
4. Documentation Generation - Writes markdown pages with diagrams
5. Verification Loop - Checks all links and generates missing pages
6. Source Linking - Every concept links to specific file:line references

Use --estimate to get a cost/time estimate before running.

The generated wiki structure:

wiki/
├── README.md                    # Navigation entry point
├── architecture/
│   ├── overview.md              # System architecture + diagrams
│   └── data-flow.md             # Data flow documentation
├── components/
│   └── {module}/
│       └── index.md             # Per-module documentation
├── guides/
│   └── getting-started.md       # Quick start guide
├── glossary.md                  # Concept index
└── site/                        # (with --site flag)
    ├── index.html               # Interactive site entry
    ├── styles.css
    └── scripts.js

Every architectural concept includes clickable source references:

## Authentication Flow

The authentication system uses JWT tokens for stateless auth.

**Source:** [`src/auth/jwt-provider.ts:23-67`](../../../src/auth/jwt-provider.ts#L23-L67)

```typescript
export class JwtProvider {
  async generateToken(user: User): Promise<string> {
    // Token generation logic...
  }
}

---

## Configuration (Optional)

Create a `wiki.json` file in your project root to customize generation:

```json
{
  "repo_notes": [
    { "content": "Focus on the src/core directory for main logic" }
  ],
  "pages": [
    { "title": "Architecture Overview", "purpose": "High-level design", "parent": null },
    { "title": "Authentication", "parent": "Architecture Overview" }
  ],
  "exclude_patterns": ["**/*.test.ts", "**/__mocks__/**"],
  "output": {
    "format": "markdown",
    "diagrams": true
  }
}

Ted Mosby uses a sophisticated retrieval system combining multiple strategies:

• Chunk size: 1,500 characters with 200 character overlap
• Language-aware boundaries: Chunks end at logical points (}, };, end)
• Embedding model: BGE-small-en-v1.5 (384 dimensions, runs locally)
• Hybrid search: BM25 keyword + vector similarity with RRF fusion
• Vector search: FAISS with IndexFlatIP for cosine similarity
• Incremental updates: Only re-embeds changed files on subsequent runs

For large codebases, chunks are prioritized by importance:

• Core directories (src/, lib/, app/): +100 points
• Entry points (index.*, main.*): +50 points
• Config files: +30 points
• Test files: -50 points
• Vendor/generated code: -100 points

Ted Mosby is built with:

• Claude Agent SDK - Orchestrates the AI agent workflow
• RAG (Retrieval Augmented Generation) - Semantic code search using embeddings
• Model Context Protocol (MCP) - Tool integration for file operations
• Mermaid - Architecture diagram generation
• FAISS - High-performance vector similarity search

Use --direct-api to bypass Claude Code's billing check:

ted-mosby generate -r ./my-project --direct-api

Limit the indexed chunks:

ted-mosby generate -r ./large-project --max-chunks 5000 --batch-size 3000

Skip re-indexing with cached embeddings:

ted-mosby generate -r ./my-project --skip-index

Use the continue command to fix:

ted-mosby continue -r ./my-project -o ./wiki

# Clone the repo
git clone https://github.com/your-username/ted-mosby.git
cd ted-mosby

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- generate -r ./my-project

# Watch mode for development
npm run dev

This project was created using the Claude Agent SDK at the Build an Agent Workshop.

Learn to build your own AI agents at buildanagentworkshop.com

MIT