npm package: @rezkam/storyof
Description: Explore any codebase — generate rich architecture docs with diagrams, then chat with an AI that already read the code
Author: Reza Kamali
Latest version: 0.1.0

# StoryOf

[![Test](https://github.com/rezkam/storyof/actions/workflows/test.yml/badge.svg)](https://github.com/rezkam/storyof/actions/workflows/test.yml)
[![Release](https://github.com/rezkam/storyof/actions/workflows/release.yml/badge.svg)](https://github.com/rezkam/storyof/actions/workflows/release.yml)
[![npm version](https://badge.fury.io/js/storyof.svg)](https://www.npmjs.com/package/storyof)
[![npm downloads](https://img.shields.io/npm/dm/storyof.svg)](https://www.npmjs.com/package/storyof)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**Run `storyof` in any project and an AI agent reads your codebase, generates a rich HTML architecture doc with mermaid diagrams, then stays around as a chat partner you can ask questions about the code.**

You join a new project. There's no architecture doc. The README says "see the code." You spend half a day clicking through files trying to understand how anything connects to anything.

StoryOf fixes that. It spawns an AI agent that reads your entire codebase, builds a mental model of the architecture, and writes it up as a rich HTML document with mermaid diagrams, module breakdowns, data flow explanations, and real code walkthroughs. You watch it happen live in your browser.

But the document is just the starting point. Once the agent has explored the codebase, it **stays around as a knowledgeable colleague**. The chat sidebar lets you ask follow-up questions, dig into specifics, or ask it to explain something differently. The agent already has context from reading the actual source, so the conversation is grounded in what's really in the code, not hallucinated guesses.

## See It in Action

Here's StoryOf exploring [karpathy/nanochat](https://github.com/karpathy/nanochat) — a full-stack ChatGPT clone covering tokenization, pretraining, fine-tuning, RL, and serving.

### Architecture Document with Diagrams

The left panel shows the generated document. The right panel shows the agent's activity — file reads, tool calls, validation status.

![Architecture overview with pipeline diagram](assets/screenshots/01-overview.png)

### Mermaid Diagrams Generated from Code

Flowcharts, state diagrams, and decision trees — all generated by reading the actual source, not from comments or docs.

![Flash attention decision flowchart](assets/screenshots/03-data-flow-diagram.png)

### Code Walkthroughs with Syntax Highlighting

Real code from the codebase with inline explanations of what it does and why.

![Code walkthrough with syntax highlighting](assets/screenshots/04-code-walkthrough.png)

### Chat with Rich Responses

Ask follow-up questions after the document is generated. The agent responds with markdown tables, code blocks, and structured explanations.

![Chat response with tables and code](assets/screenshots/06-chat-response.png)

![Chat response continued — comparison table](assets/screenshots/07-chat-code-blocks.png)

## Install

### Standalone CLI

```bash
npm install -g storyof
```

### Tab Completion (Optional)

Enable shell completion for commands, providers, and flags:

```bash
# Bash
storyof completion bash >> ~/.bashrc
source ~/.bashrc

# Zsh
storyof completion zsh > ~/.zsh/completions/_storyof
# Or for Oh My Zsh: storyof completion zsh > ~/.oh-my-zsh/completions/_storyof

# Fish
storyof completion fish > ~/.config/fish/completions/storyof.fish
```

After installing, you can tab-complete:
- Commands: `storyof auth <TAB>`
- Providers: `storyof auth set <TAB>`
- OAuth providers: `storyof auth login <TAB>`
- Flags: `storyof --<TAB>`

## Quick Start

```bash
storyof
```

That's it. A browser tab opens with a split-panel UI. The agent starts reading your codebase and generating the document on the left. The URL and session token are printed in your terminal. Paste the token in the browser to connect.

## What You Get

### Architecture Document (left panel)
- **Mermaid diagrams**: system architecture, data flows, sequence diagrams, state machines — all generated from the actual code
- **Syntax-highlighted code blocks**: real code from your codebase with explanations of what it does and why
- **Metrics cards**: lines of code, file counts, language, key stats at a glance
- **Sticky navigation**: jump between sections, wraps responsively on narrow viewports
- **Dark theme**: designed for developers who live in dark mode

### Live Chat (right panel)
- **Ask anything** about the codebase — the agent has already read the files
- **Select text** from the document, click "📎 Ask about this" to use it as context
- **Rich responses**: tables, code blocks, headings, bold/italic, bullet lists — all rendered inline
- **Streaming**: watch the response arrive word by word
- **Token usage & costs**: see per-request and session-total token counts and estimated costs

### Reliability
- **Auto-restart**: if the agent crashes, it restarts automatically (up to 3 times with exponential backoff)
- **Health monitoring**: server pings the agent every 15s; if it stops responding, the UI shows "Unresponsive" immediately
- **Mermaid validation**: every diagram is validated with `mermaid-cli`; broken diagrams get sent back to the agent to fix automatically (up to 3 cycles)
- **Session persistence**: stop and come back later with `storyof resume`

## Usage

```
storyof [prompt] [--path ./subdir] [--depth level] [--model name]
```

Everything that isn't a flag is your prompt. No quotes needed.

| Flag | Description |
|------|-------------|
| `prompt` | Topic or question to focus on (no quotes needed) |
| `--path` | Subdirectory to scope the exploration (repeatable) |
| `--depth` | `shallow` · `medium` (default) · `deep` |
| `--model` | LLM model to use (default: `claude-sonnet-4-5`) |
| `--dangerously-allow-edits` | Allow the agent to edit files (disabled by default) |
| `--help` | Show usage examples |

### Full Exploration (no prompt)

Explores the entire codebase: project structure, entry points, all major modules, dependency graph.

```bash
storyof                              # explore everything
storyof --depth deep                 # more diagrams, more code examples
storyof --depth shallow              # quick overview, faster
storyof --path ./src                 # full exploration scoped to ./src
```

### Focused Exploration (with prompt)

Give it a question and it explores **only** what's relevant, skipping unrelated modules entirely. Faster than a full exploration.

```bash
storyof how does authentication work
storyof explain the WebSocket reconnection logic
storyof error handling patterns --path ./src --depth deep
```

### Scoping with `--path`

Narrow exploration to specific subdirectories. The agent reads project config for context but focuses the document on the scoped area.

```bash
storyof --path ./src/api             # explore only the API module
storyof --path ./src --path ./lib    # focus on src and lib
storyof auth flow --path ./src/auth  # focused prompt + scoped directory
```

### Depth Levels

| Depth | Full Exploration | Focused Exploration |
|-------|-----------------|---------------------|
| `shallow` | 3-5 diagrams, ~800 lines, fast | 2-3 diagrams, ~500 lines, very fast |
| `medium` | 7-12 diagrams, ~1500 lines | 4-7 diagrams, ~1000 lines |
| `deep` | 12-18+ diagrams, 2000+ lines | 8-12+ diagrams, 1500+ lines |

## Commands

| Command | What it does |
|---------|-------------|
| `storyof` | Start a new exploration |
| `storyof resume` | Resume a previous session in this directory |
| `storyof stop` | Stop the running agent |

`storyof resume` shows a picker if you have multiple sessions:

```
Resume which session?
  1) 📄 "how does auth work?" (medium) — 2h ago
  2) 📄 full exploration (deep) — 1d ago
  3) ⏳ "error handling" [./src/api] (shallow) — 3d ago
```

## Authentication

StoryOf needs an API key for your chosen LLM provider.

### Option 1: Environment Variables

```bash
export STORYOF_ANTHROPIC_API_KEY=sk-ant-xxx
# or use standard env vars as fallback:
export ANTHROPIC_API_KEY=sk-ant-xxx
```

### Option 2: Store a Key

```bash
storyof auth set anthropic sk-ant-xxx
```

### Option 3: OAuth Login

```bash
storyof auth login anthropic      # Claude Pro/Max
storyof auth login github-copilot # GitHub Copilot
storyof auth login google         # Google Gemini CLI
storyof auth login antigravity    # Google Cloud
storyof auth login openai-codex   # ChatGPT OAuth
```

### Manage Credentials

```bash
storyof auth list                 # show configured providers
storyof auth logout anthropic     # remove credentials
```

Credentials are stored in `~/.storyof/auth.json` with 600 permissions.

### Supported Environment Variables

| StoryOf Variable | Standard Fallback |
|---|---|
| `STORYOF_ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` |
| `STORYOF_OPENAI_API_KEY` | `OPENAI_API_KEY` |
| `STORYOF_GEMINI_API_KEY` | `GEMINI_API_KEY` |
| `STORYOF_GROQ_API_KEY` | `GROQ_API_KEY` |
| `STORYOF_XAI_API_KEY` | `XAI_API_KEY` |
| `STORYOF_OPENROUTER_API_KEY` | `OPENROUTER_API_KEY` |
| `STORYOF_MISTRAL_API_KEY` | `MISTRAL_API_KEY` |
| `STORYOF_CEREBRAS_API_KEY` | `CEREBRAS_API_KEY` |
| `STORYOF_GITHUB_TOKEN` | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` |

## Token Usage & Costs

StoryOf tracks token usage per-request and per-session:

- **Per-request**: input tokens, output tokens, cache read/creation tokens
- **Per-session**: cumulative totals with estimated cost in dollars
- **Visible in browser UI**: token counts and costs displayed in the chat sidebar

## Agent Control

From the browser chat panel you can:

- **Stop**: halt the agent completely
- **Abort**: cancel the current operation (e.g., a long bash command)
- **Steer**: send a new message while the agent is working — it interrupts and responds

## Session Management

Sessions are stored locally in your project:

```
your-project/
  .storyof/
    a3f29b12/          # session 1
      document.md      # generated markdown
      document.html    # rendered architecture doc
      meta.json        # session metadata
      agent.log        # debug log
    c7e4d001/          # session 2
      ...
```

- **Resume**: `storyof resume` to pick up where you left off
- **Multiple concurrent**: run separate `storyof` instances in different terminals
- **No conflicts**: each gets its own port and session

## Configuration

### Global Settings

`~/.storyof/settings.json`:

```json
{
  "compaction": { "enabled": true },
  "retry": { "enabled": true, "maxRetries": 5 },
  "thinking": "medium",
  "maxTokens": 16384
}
```

### Project Settings

`.storyof/settings.json` — overrides global settings for this project.

### Custom Skills

Add custom skills to extend the agent's capabilities:

- Global: `~/.storyof/skills/`
- Project: `.storyof/skills/`

## How It Works

```
Terminal (storyof CLI)
    ↕ In-process agent session
Agent Runtime (reads files, runs tools)
    ↕ Events
HTTP + WebSocket Server
    ↕ WebSocket
Browser (split-panel UI)
```

1. You run `storyof` and the CLI creates an in-process agent session and starts an HTTP + WebSocket server
2. The agent reads files, follows imports, and builds understanding — streaming events to the browser
3. When the agent writes a markdown document, the system renders it to styled HTML
4. Mermaid diagrams are validated; broken ones are sent back to the agent for auto-fix
5. You ask questions in the chat — the agent already has full context from its exploration
6. Token usage and costs are tracked and displayed in the browser UI

## Safety: Read-Only by Default

StoryOf runs in **read-only mode** by default. The agent can read your files, run analysis commands (grep, find, git log, etc.), and generate architecture documents — but it **cannot modify, create, or delete** any files in your codebase.

This means:
- No `edit` or `write` tools are available to the agent
- Bash commands that modify files are blocked (rm, mv, cp, sed -i, redirects, etc.)
- Package managers (npm install, pip install) are blocked
- Git write operations (commit, push, merge) are blocked
- Inline script execution (python -c, node -e) is blocked

The only file the agent writes is its own architecture document in the `.storyof/` session directory.

If you want the agent to make changes to your codebase (e.g., apply suggested refactors), you can opt in:

```bash
storyof --dangerously-allow-edits
storyof resume --dangerously-allow-edits
```

This enables the full tool set: read, bash (unrestricted), edit, and write.

## Security

The server generates a random session token on startup, printed in your terminal. Paste it in the browser to connect. This prevents other localhost processes from accessing the document or controlling the agent.

## Pi Extension

If you use [Pi](https://github.com/badlogic/pi) as your coding agent, there's a separate extension that wraps StoryOf — uses Pi's existing auth, no global install needed:

```bash
pi install git:github.com/rezkam/pi-storyof
```

See [pi-storyof](https://github.com/rezkam/pi-storyof) for details.

## License

Copyright 2026 Reza Kamali. Licensed under [Apache License 2.0](LICENSE).