kenly

AI-guided codebase walkthroughs in your terminal. Point kenly at any repo and it walks you through the code like a senior dev giving you KT — opening the right files, highlighting the lines it's talking about, explaining how the pieces fit, and answering your questions live. Powered by Claude Code.

pip install kenly
kenly kt /path/to/repo          # AI walks you through the codebase
kenly kt . --focus "auth flow"  # steer the walkthrough
kenly kt . --offline            # free scripted demo (no key, no network, $0)

Why kenly

Onboarding onto an unfamiliar codebase is slow: a doc tells you what it does but not where the logic lives; a chat assistant answers questions but you're left hunting for the files yourself. kenly closes that gap — it drives the screen while it explains, so you see the code as you hear the story, and you can interrupt, ask, go deeper, or take the wheel and explore, then resume.

• 🎙️ Live, interruptible walkthrough — narrated tour of the repo's real flow
• 📂 It opens & highlights the actual code as it talks (not just filenames)
• 💬 Ask anything mid-tour — answered in context of what's on screen
• 🖐️ Grab the wheel — explore freely, then resume where you left off
• 🔑 Your auth, your choice — Claude Code subscription or an API key
• 💸 Cost-safe — a real --max-cost rail; or --offline for a free demo

Under the hood, kenly is built on a fast, read-only terminal code explorer (file tree, syntax-highlighted panes, tabs, fuzzy find) — the surface the AI drives. You can open it on its own with plain kenly [PATH], but the reason to reach for kenly is the walkthrough.

Quick start

pip install kenly                    # ships with the Claude Agent SDK
npm i -g @anthropic-ai/claude-code   # the CLI the SDK drives (Node 18+)
kenly kt /path/to/repo               # first run asks how to authenticate

On first run kenly asks how you want to authenticate — your Claude Code login (subscription) or an ANTHROPIC_API_KEY — and remembers your choice. No key? kenly kt <repo> --offline gives a free scripted demo of the whole experience.

The explorer (foundation)

The AI drives a real read-only code explorer you can also use directly:

kenly /path/to/repo   # just browse — file tree, syntax highlighting, tabs
kenly file.py         # open straight to a file

• File-tree sidebar with lazy expansion (large repos stay instant)
• Code pane with syntax highlighting and line numbers (~500 languages via Pygments)
• Tabs, in-file search, jump-to-line, fuzzy file finder (Ctrl+P)
• Breadcrumb + status bar, responsive layout, mouse support

It never writes to your files.

Install (development)

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
kenly kt .

Tests

pytest

Engine tests are pure and terminal-free. UI tests drive the real app headlessly with Textual's Pilot and assert real outcomes.

Layout

src/kenly/
├── cli.py            # argparse entry point → kenly console script
├── driver.py         # THE DRIVER API contract (typing.Protocol)
├── engine/           # pure, UI-free logic — imports no Textual
│   ├── models.py     # DirEntry, LoadedFile, SearchMatch, FuzzyResult
│   ├── paths.py      # normalisation + root-containment guard
│   ├── ignore.py     # what the tree and index skip
│   ├── tree.py       # lazy directory listing
│   ├── syntax.py     # language detection
│   ├── loader.py     # safe file reading (caps, binary sniff, encodings)
│   └── workspace.py  # the facade the TUI holds
└── tui/              # Textual app, widgets, layout, bindings
    ├── app.py        # KenlyApp — implements the driver API
    ├── kenly.tcss   # stylesheet
    └── widgets/      # file_tree, code_pane, status_bar

See docs/architecture.md and docs/driver-api.md.

Phase 2 — kenly kt (AI knowledge transfer)

kenly kt [PATH] layers a live, interruptible AI walkthrough on top of the exact same read-only explorer. Claude Code drives the screen — opening files, highlighting the lines it's talking about, scrolling to them — while it explains the codebase in the narration panel. You can cut in with a question mid-sentence, tell it to go deeper or skip, or take the wheel and explore on your own, then resume from wherever you're looking.

Setup

# The Claude Agent SDK ships with kenly, so a plain `pip install kenly`
# already includes the AI walkthrough. You only need two more things:
npm i -g @anthropic-ai/claude-code   # the CLI the SDK drives (Node 18+)
echo 'ANTHROPIC_API_KEY=sk-…' > .env # gitignored; .env and .env.* never commit
kenly kt .                          # real, live AI walkthrough
kenly kt . --focus "the auth flow"  # steer it (also offered in-UI at start)
kenly kt . --offline                # scripted demo: no key, no network, $0

With no key, kenly kt doesn't fail — it drops into a clearly-badged OFFLINE DEMO (a scripted, deterministic tour that exercises the same UI path) and tells you, in-panel, exactly how to enable the real thing.

Keys

Every Phase-1 key (tree navigation, tabs, / search, Ctrl+P finder, ? help) still works during a KT. Press ? for the full cheat-sheet.

Cost

The Anthropic key is the only thing in kenly that ever costs money. A short session is a few cents; TurnComplete surfaces the real cumulative spend live in the panel header, --max-turns N caps a runaway session, and --offline is always free. CI runs entirely on the offline brain — no key, no network, no cost.

License

MIT