kenly

A terminal "lite IDE" for exploring codebases — a fast, keyboard- and mouse-driven code explorer in the spirit of lazygit, k9s and yazi.

The base explorer (kenly) is standalone and read-only — no AI, no network. An opt-in AI walkthrough (kenly kt, Phase 2) layers on top of it.

kenly                 # explore the current directory
kenly /path/to/repo   # explore any repo
kenly file.py         # open a file directly

What it does

• File-tree sidebar with lazy expansion (large repos stay instant)
• Code pane with syntax highlighting and line numbers (~500 languages via Pygments)
• Tabs for multiple open files
• Navigation: scroll, page, jump-to-line, top/bottom, in-file search
• Fuzzy file finder (Ctrl+P)
• Breadcrumb + status bar, responsive layout, mouse support

It never writes to your files. It never opens a socket.

Install (development)

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

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