GitHub - anthonyclarka2/sothspell: An LLM-guided and narrated walkthrough of your codebase

Sóþspell

Sóþspell (Old English for "truth story") is an AI/LLM-guided walkthrough of a software project. It explains a codebase from the top down like a film: a narrator describes the system, diagrams build and change with the story, and the relevant code is highlighted and linked as each module, class, function, object, or feature is discussed.

The explanation can play continuously when the user has nothing to ask. The user can pause at any moment, open the code, click a diagram node, or ask a question; answering does not lose their place. Progress is recorded so the walkthrough can resume later.

Contributors

I welcome PRs and issues! I request that a human reads the whole bug report or pull request before it is submitted. I also would much prefer smaller PRs rather than huge ones. Please create PRs that merge into the dev branch, not main.

If you are able to tip me for this work, I'd be eternally grateful. I'm currently looking for work.

Quick start

Prerequisites:

Node.js 26 or newer
pnpm 12.14.0 (corepack enable, or npm install -g pnpm@12.14.0)
Optional: an ElevenLabs API key for cloud narration, and an LLM API key for authoring or in-tour questions. Browser speech and the fixture model work without either key.

Releases

Tagged releases are source releases on GitHub Releases. There is no npm package and no hosted service. See the release notes for what changed and the releasing guide for the maintainer checklist.

To install a specific release, replace v0.3.1 with the newest tag:

git clone --branch v0.3.1 --depth 1 https://github.com/anthonyclarka2/sothspell.git

Web

<in a suitable parent directory>
git clone https://github.com/anthonyclarka2/sothspell.git
cd sothspell
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm sothspell --version
pnpm sothspell help
pnpm sothspell serve

http://127.0.0.1:4319/ is opened automatically. From here you can run through the demo narration.

To Analyse and Narrate a Different Repo

Run the web interface as above. (pnpm sothspell serve)
Open settings near the top right corner of the browser window.
Click "New authoring profile" and add an LLM API key. Test the connection and save it.
If you have an ElevenLabs API key, you can do the same for "New narration profile".
Then click "New Tour".
You can choose either a local git repo, or a remote GitHub repo (other Git hosts coming soon!).
Check that the repository is accessible via "Check repository".
Choose "Active authoring profile".
Choose the level of narration: New contributor, Technical evaluator, or Maintainer.
Choose a target runtime (TODO: suggest runtime length based on repo size + level of narration)
Click "Author the tour" and wait a few minutes.
Follow the tour in your web browser!

When in the tour of the repository, you can listen to a narrator or read along at your own pace. To listen to a narrator, choose one of "Browser voice" or "Cloud voice". Browser voice uses the built in web speech API, while Cloud voice uses the credentials and voice you chose earlier in the Narration Profile setup.

Enjoy the tour!

Terminal

Analyze a local repository read-only and author a tour (use your own checkout path; Bunbun is this project's reference project):

pnpm sothspell analyze /path/to/your/repo --brief
pnpm sothspell analyze /path/to/your/repo --save
pnpm sothspell author /path/to/your/repo --model fixture --out /tmp/your-tour
SOTHSPELL_MODEL=openai/gpt-5.2 pnpm sothspell author /path/to/your/repo --out /tmp/your-tour

OpenCode Plugin

Not published yet; OpenCode V2 can load a local plugin directory, so the plugin runs straight from this checkout.

Prerequisites (once per checkout):

cd /path/to/sothspell
pnpm install
pnpm build            # gives `sothspell serve` a web player to host
pnpm sothspell serve  # terminal 1; player and API on http://127.0.0.1:4319

Point OpenCode at the plugin directory in the project you want to tour, in opencode.jsonc:

Relative paths resolve from the config file that contains the entry, so an absolute path is the least surprising when the plugin lives in another checkout. Restart OpenCode if it was already running (opencode service restart).

Then, in a session:

/sothspell — open the existing tour, or generate one first.
/sothspell status, /sothspell generate, /sothspell ask <question>.
Tools: sothspell_status, sothspell_open, sothspell_generate, sothspell_ask.
Options: playerUrl (4319 for sothspell serve, 5173 for pnpm dev), autoOpen, model, maxMinutes.

The plugin resolves @opencode/plugin and the @sothspell/* workspace packages from this checkout's node_modules, which is why pnpm install runs here first. The terminal only launches the browser; diagrams, code, and narration play in the player. See docs/opencode-plugin.md for the full surface.

Claude Code Plugin

Not published yet; Claude Code loads a plugin directory directly, so no marketplace or registry is needed.

With the same prerequisites (checkout installed, pnpm sothspell serve running):

claude --plugin-dir /absolute/path/to/sothspell/packages/harness-claude-code/plugin

The plugin ships a sothspell skill with four verbs — /sothspell, /sothspell status, /sothspell generate, /sothspell ask <question> — and a SessionStart hook that announces an existing tour. Its userConfig exposes player_url (default http://127.0.0.1:4319) and an optional model.

The bundled wrapper runs pnpm --dir <repo> exec tsx against this checkout. If you copy the plugin elsewhere, set SOTHSPELL_REPO=/path/to/sothspell (or SOTHSPELL_TSX to a tsx-compatible launcher). See docs/harnesses.md.

Codex Plugin

Not published yet; Codex installs plugins from a local marketplace entry, so no registry is needed.

With the same prerequisites, add the plugin to a marketplace file — personal (~/.agents/plugins/marketplace.json) or repo (.agents/plugins/marketplace.json):

Restart Codex, install the plugin, and review and trust its bundled hook in /hooks. Then invoke the skill — $sothspell (or /skills) — with status, generate, open, and ask <question>.

The bundled wrapper runs pnpm --dir <repo> exec tsx against this checkout. If you copy the plugin elsewhere, set SOTHSPELL_REPO=/path/to/sothspell (or SOTHSPELL_TSX). SOTHSPELL_PLAYER_URL overrides the default player URL http://127.0.0.1:4319. See docs/harnesses.md.

Example project

The first reference project is Bunbun, a NestJS + Prisma Next + ATProto discussion service at commit 9fef24d. The Bunbun tree is read-only; all snapshots, tours, audio, and runs live under SOTHSPELL_HOME (default ~/.sothspell). The checked-in golden tour lives in examples/bunbun-tour/ and stores only small, attributed excerpts.

Documentation

Canvas roadmap — the completed canvas era: scene, code relationships, accessibility, export, performance, and risks.
Phase 17 — canvas foundation, evidence links, multiple diagrams, controls, and fullscreen.
Phase 18 — symbol targets, call/reference index, incoming/outgoing containers, definition links, and the shared-symbol bridge.
Phase 19 — keyboard model, screen-reader outline, preferences, contrast, large text, and compact layout.
Phase 20 — PNG/JPG/PDF export, performance budget, coverage, docs, and the final gate.
Phase 22 — Canvas default, Stage fallback, chapter drawer, and fullscreen player chrome.
Canvas feature brief — the original deliverables and constraints.
Archived plans — the completed v1 and v2 eras, with their shipped baselines and binding constraints.
Archived v1 plans — the first-release roadmap and Phases 1–8.
Archived v2 roadmap — the completed next-stage feature inventory, phase sequence, architecture changes, security, testing standards, and risks.
Architecture — packages, pipeline, trust boundaries, and storage.
Tour format — the document, anchors, diagrams, and versioning.
Phase 9 — preferences UI for authoring and narration connections.
Phase 10 — Claude Code and Codex harness plugins.
Phase 11 — public GitHub import with sandboxed cloning.
Phase 12 — GitHub OAuth accounts and cross-device sync.
Phase 13 — Python, Go, Rust, and Java analyzers.
Phase 14 — multi-language narration and translation.
Phase 15 — human review UI for generated tours.
Phase 16 — embeddable player for documentation sites.
Development guide — workspace, commands, and the golden-tour workflow.
Repository analysis — read-only snapshots, symbols, cache, CLI, and project brief.
Tour authoring — model port, context packs, curriculum, validation, repair, quality reports, and the author CLI.
Player and code browser — playback controls, keyboard map, virtualized code pages, stale badges, and progress.
Canvas playback — the default spatial board, evidence and relation links, chapter drawer, fullscreen chrome, keyboard/preferences, export, and performance.
Narration — browser and cloud speech, synchronization, caching, and privacy.
Guide and interludes — in-tour questions, citations, drilldown, and progress.
OpenCode plugin — install, commands, tools, RPC, and the host model adapter.
Harnesses — the adapter contract and the Claude Code and Codex adapters.
Settings and connection profiles — provider profiles, the secret store, and resolution rules.
GitHub import — URL forms, sandbox limits, and the import API/UI/CLI.
Accounts and sync — GitHub OAuth, sessions, sync merge rules, export, and delete.
Embeddable player — export, the host API, progress, CSP, and the docs fixture.
Human review — the review state machine, editing, regeneration, anchor gating, and decisions.
Translation and locales — the locale schema, protected-span pipeline, localized UI, and RTL support.
Open a repository — author a tour from a local git checkout or a public GitHub URL in the web UI.
Tiny notes example — the small demo repository for the open-repository flow.
Self-hosting — install, serve, storage, and upgrades.
Privacy — what stays local and what cloud choices send.
Accessibility — the axe gate and keyboard map.
Troubleshooting — common local failures.
Release notes — the first release and limitations.
Security policy — reporting, posture, accepted risks, and the operator checklist.
Authoring skill — the checklist an agent uses to author or review a tour.
Domain context — the project glossary.
Agent instructions — how agents work in this repository.

Development

Running the dev instance

pnpm install
pnpm dev            # API on 127.0.0.1:4319, web on 127.0.0.1:5173

Open http://127.0.0.1:5173 and play the demo tour.

pnpm typecheck
pnpm lint
pnpm test
pnpm test:browser
pnpm test:a11y
pnpm build
pnpm check:toolchain
pnpm check:version
pnpm check:secrets
pnpm schema:json
pnpm tour:build      # regenerate the golden tour from the pinned Bunbun checkout

Stack

pnpm 12.14.0 · Node.js 26 · TypeScript 7.0.2 · React 19.3.1 · Vite 8.3.4 · TanStack Router 1.170.45 · Hono 4.13.13 · Zod 4.6.7 · Shiki 4.5.0 · React Flow 12.12.0 · ELK 0.12.0 · oxc-parser 0.154.0 · fast-glob 3.3.3 · ignore 7.0.12 · yaml 2.9.1 · Vercel AI SDK 7.0.143 · Vitest 5.0.5 · Playwright 1.64.1 · axe-core 4.14.0.

TypeScript 7.0 has no programmatic compiler API; the analyzer will use oxc-parser, not the TypeScript compiler API. See the roadmap for the full version table and constraints.

Similar work

DeepWiki, CodeSee tours/maps, Swimm, VS Code CodeTour, GitDiagram, Scrimba, and NotebookLM Audio Overviews each solve part of the problem. Sóþspell combines evidence-anchored code, animated diagrams, narration, semi-interactive Q&A, resumable progress, and harness-native plugins. The roadmap has the comparison and sources.

License

Status

v1 release complete (2026-10-17); next stage complete (2026-10-17). The repository contains:

a pnpm workspace on TypeScript 7.0.2, React 19, Vite 8, and Hono 4;
the versioned Sóþspell schema, a generated JSON Schema, and a compiler that resolves anchors, hashes excerpts, highlights code with Shiki, and lays out diagrams with ELK;
a checked-in golden Bunbun tour pinned to commit 9fef24d;
a read-only repository analyzer with oxc-parser: deterministic snapshots, symbol extraction, import/reference graphs, NestJS/Prisma signals, a project brief, a per-file cache, and the sothspell analyze CLI;
an LLM authoring pipeline: GuideModel port, AI SDK adapters, a deterministic fixture model, context packs, curriculum planning, chapter/diagram generation, validation, bounded repair, caching, quality reports, and the sothspell author CLI;
the cinematic player: auto-advance, pause/resume, scrubber, speed, theater mode, completed-beat tracking, keyboard control, a virtualized full-file code browser with stale badges and anchor outlines, and local-first run progress mirrored to a local SQLite table;
narration: browser speech and opt-in ElevenLabs cloud narration with aligned timings, content-addressed audio, range serving, and fallback;
in-tour questions with cited answers, drilldown generation, and a sothspell serve/doctor local runtime;
the OpenCode V2 plugin with commands, tools, typed RPC, a host model adapter, generated-tour serving, and an embedded-host smoke test;
unit, browser, accessibility, and plugin tests, including the Bunbun acceptance pass.

The v1 and v2 plans are archived in plans/archive/. The next stage completed in plans/archive/v2/ROADMAP.md: preferences UI, Claude Code and Codex harness plugins, GitHub import, accounts and sync, Python/Go/Rust/Java analyzers, multi-language narration and translation, the human review UI, and the embeddable player. A reviewed real-model Bunbun tour and live cloud narration remain owner-gated on provider credentials; fixture and browser paths are verified.

The canvas era is complete in plans/ROADMAP.md as Phases 17–20, and Phase 22 makes Canvas the web player default. The first public source release is v0.3.1 (2026-10-26); manual VoiceOver/NVDA, real Save-as-PDF, and real-device touch checks remain owner-gated. The Stage remains the fallback and the embed layout.