Metadata-Version: 2.5
Name: kenly
Version: 0.1.0
Summary: A terminal lite-IDE for exploring codebases.
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

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](#phase-2--kenly-kt-ai-knowledge-transfer))
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)

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

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