Metadata-Version: 2.5
Name: kenly
Version: 0.1.1
Summary: AI-guided codebase walkthroughs in your terminal — Claude Code walks you through any repo like a senior dev giving KT.
Project-URL: Homepage, https://github.com/Vishesh-Paliwal/docent
Author: kenly contributors
License: MIT
Keywords: code,explorer,terminal,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: claude-agent-sdk<0.3,>=0.2.135
Requires-Dist: pygments<3,>=2.18
Requires-Dist: rich<16,>=14
Requires-Dist: textual<9,>=8.2
Provides-Extra: dev
Requires-Dist: claude-agent-sdk<0.3,>=0.2.135; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<10,>=8.2; extra == 'dev'
Requires-Dist: textual-dev<2,>=1.7; extra == 'dev'
Provides-Extra: kt
Requires-Dist: claude-agent-sdk<0.3,>=0.2.135; extra == 'kt'
Description-Content-Type: text/markdown

# 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.

```bash
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

```bash
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)

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

## Tests

```bash
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`](docs/architecture.md) and
[`docs/driver-api.md`](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.

![kenly kt — an AI walkthrough of a repo](docs/kt-session.png)

### Setup

```bash
# 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

| Key | Action |
| --- | --- |
| `Ctrl+J` | ask a question — pre-empts the guide mid-sentence |
| `Ctrl+N` | next step |
| `Ctrl+G` | go deeper on what's on screen |
| `Ctrl+S` | skip this step |
| `Ctrl+E` | explore on your own — you take the wheel |
| `Ctrl+R` | resume the guide from where you're looking |
| `Ctrl+T` | stop and wrap up |

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
