Documentation

Everything you need to run teep next to your coding agent. Version 0.1.0 — expect rough edges, report bugs on GitHub.

Install

On macOS and Linux, via Homebrew:

brew install teep-app/teep/teep

Binaries and source in the teep-app/teep repo. Dual-licensed MIT or Apache 2.0.

Requirements

Terminal — Ghostty is the primary target. Kitty, iTerm2, WezTerm, and Zellij also work. Any terminal supporting Kitty, iTerm2, or Sixel graphics will render images natively; everything else falls back to halfblocks.
tmux — if you run teep inside tmux, you must enable graphics passthrough or images will be pixelated halfblocks:

tmux set -g allow-passthrough on

Mermaid (optional) — install mmdc for diagram rendering:

brew install mermaid-cli
# or
npm i -g @mermaid-js/mermaid-cli

Without mmdc, mermaid blocks render as a bordered placeholder.

Running teep

The CLI is intentionally tiny — a single optional path argument:

teep .
teep path/to/repo

If no path is given, teep opens the current working directory.

The core workflow

Split your terminal in two. Run your agent on the left. Run teep . on the right. As the agent writes files, teep's change log fills up. Press n to jump to the next file the agent touched; press N to step backward. When you're caught up, press u to mark everything as seen.

Teep is viewer-first. Editing exists (i, e, Ctrl-S), but the agent is the real IDE. Don't fight it.

Keybindings

Key	Action
`↑ ↓`	Move selection in tree, scroll viewer (depends on focus)
`→ ←`	Expand / collapse directory
`Enter / o`	Open file (or toggle directory)
`n`	Jump to next agent-changed file
`N`	Jump to previous agent-changed file
`u`	Mark all changes seen (checkpoint)
`r`	Force tree refresh
`Tab`	Switch focus between tree and viewer
`/ or Ctrl-P`	Fuzzy file finder
`:`	Command palette
`?`	Help overlay
`d`	Toggle inline diff vs HEAD
`m`	Toggle markdown live preview (on .md files)
`g`	Git status overlay
`b`	Worktree switcher
`i`	Enter insert edit mode
`e`	Edit entire line
`Esc`	Exit edit mode
`Ctrl-S`	Save edited file
`Ctrl-B`	Toggle sidebar visibility
`PgUp / PgDn`	Scroll viewer
`Home / End`	Jump to start / end of viewer
`Ctrl-C Ctrl-C`	Quit (double-tap)

Press ? in the app for the same list, offline.

Command palette

Press : to open a fuzzy-filtered list of commands:

refresh — re-walk the file tree
checkpoint — mark all agent changes as seen
sidebar — toggle sidebar visibility
git — open git status overlay
worktrees — switch worktrees
help — keybinding cheatsheet
quit — exit

Markdown rendering

GitHub-flavored markdown. Tables, task lists, code blocks, styled inlines, and nested structure. Two display modes:

Rendered — default for .md files. Pretty output.
Live preview — press m. The cursor's current block shows raw markdown; the rest stays rendered. Obsidian-style reveal-on-cursor.

Inline images

PNG, JPEG, GIF, WebP. Images embedded with ![alt](path) render inline using the best protocol your terminal supports (Kitty > iTerm2 > Sixel > halfblocks). Capped at 8 megapixels for safety.

Mermaid diagrams

```mermaid fenced blocks are rendered via an external mmdc process. Output is cached on disk by content hash (blake3), so repeated renders are instant.

Git integration

d — toggle inline git diff HEAD for the current file.
g — status overlay (modified, added, deleted, renamed, untracked, ignored, conflicted).
b — worktree switcher.

Teep shows the current branch and short HEAD hash in the header. If the agent overwrites a file you were in the middle of editing, teep drops a conflict banner so you don't lose work.

Small edits

Press i to insert at the cursor or e to edit the whole line. Esc exits edit mode, Ctrl-S saves. Teep suppresses the fs-change event it generates itself on save, so you don't see a phantom change-log entry.

Editing is auxiliary. For anything bigger than a typo, drive the agent or reach for your editor.

Configuration

Config lives at ~/.config/teep/config.toml on macOS/Linux and %APPDATA%\teep\config\config.toml on Windows. Minimal for now:

[theme]
theme = "base16-ocean.dark"

theme accepts any theme from the two-face / syntect default set. Keybindings are not yet user-customizable.

Logs

Logs are written to ~/.local/share/teep/teep.log. Increase verbosity with the TEEP_LOG environment variable:

TEEP_LOG=debug teep .

Accepts error, warn, info, debug, trace.

Troubleshooting

Images look like pixelated blocks

You're almost certainly inside tmux without passthrough. Run tmux set -g allow-passthrough on and reload tmux config.

Mermaid blocks show a bordered placeholder

mmdc isn't on your PATH. Install mermaid-cli.

Syntax highlighting looks plain

Files larger than ~2 MB fall back to plain text. This is intentional — highlighting a 10 MB file would stall the UI.

Teep isn't picking up agent changes

Check the log (~/.local/share/teep/teep.log). On some filesystems, notify can miss events — r forces a tree refresh.