sidelight

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# sidelight

Read-only project-awareness TUI for a terminal split pane beside your AI coding agent —
[PI](https://pi.dev), Claude Code, or Codex. Runs entirely locally: no network, no telemetry,
the sidecar never writes, and it only ever spawns `git`.


**Why:** full visibility into the project you're working on — and transparency into
what your AI agent is actually touching — without handing yet another tool write
access to your code.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/1-hero-dark.png">
  <img alt="sidelight running in a Ghostty split beside a PI session: file tree on the left, the agent describing the project on the right" src="assets/1-hero-light.png">
</picture>

## One-minute demo

https://github.com/user-attachments/assets/4ac23c1e-cb85-44ad-87cc-5382e5d32ca3

## Install

From [npm](https://www.npmjs.com/package/sidelight):

```sh
npm install -g sidelight
sidelight [dir]   # dir defaults to the current directory
```

Or from source, if you prefer to read before you run (encouraged):

```sh
git clone https://github.com/annbjer/sidelight && cd sidelight
npm install && npm run build
node dist/src/index.js [dir]
```

## Use in Ghostty

Open a split (`cmd+d` right / `cmd+shift+d` down), size it to taste
(`cmd+ctrl+arrows`), and run `sidelight` in the split next to `pi`.

## PI session awareness (v0.2)

The `[4] Sessions` tab shows your project's PI sessions live (name, activity, prompts,
model, cost). It needs the bundled PI extension, which records **sanitized metadata
only** — never message content. Enable it with:

```sh
pi install npm:sidelight
```

Or try it once without installing: `pi -e npm:sidelight`. Running from a clone instead?
Point `~/.pi/agent/settings.json` at it: `"extensions": ["<path-to-repo>/extension/index.ts"]`.

The extension writes one small JSON snapshot per session under
`~/.local/state/sidelight/sessions/` (or `$XDG_STATE_HOME/sidelight/sessions/`) —
open one with `cat` to see exactly what is recorded: timestamps, counts, tool-call
counts, deny-list-filtered file paths, token totals, cost, the model id, and the session
name you set with `/name`. Nothing else.

## Other agents: Claude Code and Codex (v0.6)

The same Sessions tab works beside Claude Code and Codex through their hooks systems.
Each adapter is a tiny program that ships with sidelight, runs for milliseconds per
event, and records the same sanitized metadata — never message content, never command
strings. Setup is one command:

**Claude Code:**

```sh
sidelight-claude-code-hook --install
```

**Codex:**

```sh
sidelight-codex-hook --install
```

Each shows you the exact change to your agent's config, makes a timestamped backup, and
asks before writing — nothing happens without your explicit yes. `--uninstall` reverses
it just as cleanly, and `--print-config` prints the snippet if you prefer to merge by
hand.

Codex asks you to trust the hooks on first interactive run (non-interactive
`codex exec` needs `--dangerously-bypass-hook-trust`).

Honest limitations, by design: `tokens`/`cost` stay at 0 for both (their hooks don't
expose usage, and sidelight never parses message-bearing transcripts); Codex mostly runs
files through shell commands, so its `filesTouched` stays sparse (command strings are
never read); Codex has no session-end event, so its sessions display as active.

## Keys

- `1` / `2` / `3` / `4` — Files / Git / Search / Sessions panel
- `j` / `k` / arrows — move selection · `g` / `G` — jump to top / bottom (works in every list and preview)
- `Enter` — expand/collapse dir, run search, **preview file**, open diff, session detail
- `y` — yank to clipboard (path from lists; `path:line` from a preview; resume command from sessions) via OSC 52
- In a preview or session detail: `j`/`k` move the cursor line · `Esc` back to where you were (state preserved)
- `/` — jump to search input · `Esc` — toggle input/results focus
- Search is smart-case: all-lowercase queries match any case; an uppercase letter makes it exact
- Search results: `files` section (filename matches) first, then `content` matches, query highlighted
- `r` — refresh all panels (git status and sessions also auto-refresh via fs watchers)
- `q` / `Ctrl+C` — quit


## A closer look

**Review what your agent changed — diff stats on every file, colored diffs on Enter.**

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/2-git-dark.png">
  <img alt="Git panel diff view with green additions, red removals, and dim hunk headers" src="assets/2-git-light.png">
</picture>


**Search finds files and content — smart-case, every match highlighted.**

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/3-search-dark.png">
  <img alt="Search results with a files section and highlighted content matches grouped by file" src="assets/3-search-light.png">
</picture>


**Preview any file or match at its exact line, then Esc back to where you were.**

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/3-search-2-dark.png">
  <img alt="File preview with cursor line and highlighted search matches" src="assets/3-search-2-light.png">
</picture>


**Know what each agent session touched — and what it cost.**

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/4-sessions-dark.png">
  <img alt="Session detail showing prompts, turns, tool calls, tokens, cost, files touched, and a resume command" src="assets/4-sessions-light.png">
</picture>

## Guarantees

- Respects `.gitignore` (files/search built on `git ls-files` / `git grep`) plus a
  built-in deny-list (`.env*`, `*.pem`, `*.key`, `*_rsa*`, `node_modules`, `.git`)
  applied to every surface: file tree, search results, git status, previews.
- The sidecar is read-only: never modifies, writes, or indexes anything.
- The session recorders (PI extension, Claude Code and Codex hook adapters) write only
  their own state dir, only allowlisted metadata fields, and never message bodies,
  prompts, or command strings.
- Works degraded outside git repos (deny-listed file browser; search disabled) and
  without the extension (Sessions tab shows how to enable it).

## Philosophy

Sidelight is deliberately restrained: read-only toward your project, no network, no
telemetry, no daemon, no index, content only on explicit keypress. The boundaries are a
feature — see [PHILOSOPHY.md](https://github.com/annbjer/sidelight/blob/HEAD/PHILOSOPHY.md) for the guarantees and the list of
things we will never add.

## Support

Sidelight is free and open source. If it helps your workflow, you can support
development at [ko-fi.com/annbjer](https://ko-fi.com/annbjer).

## The story

How (and why) sidelight was built — one human, three AIs, one hot July weekend:
[annbjer.com/articles/sidelight-the-visibility-layer-my-terminal-was-missing](https://www.annbjer.com/articles/sidelight-the-visibility-layer-my-terminal-was-missing/)

sidelight

Read-only project-awareness TUI for a terminal split pane beside your AI coding agent — PI, Claude Code, or Codex. Runs entirely locally: no network, no telemetry, the sidecar never writes, and it only ever spawns git.

Why: full visibility into the project you're working on — and transparency into what your AI agent is actually touching — without handing yet another tool write access to your code.

sidelight running in a Ghostty split beside a PI session: file tree on the left, the agent describing the project on the right

One-minute demo

https://github.com/user-attachments/assets/4ac23c1e-cb85-44ad-87cc-5382e5d32ca3

Install

From npm:

npm install -g sidelight
sidelight [dir]   # dir defaults to the current directory

Or from source, if you prefer to read before you run (encouraged):

git clone https://github.com/annbjer/sidelight && cd sidelight
npm install && npm run build
node dist/src/index.js [dir]

Use in Ghostty

Open a split (cmd+d right / cmd+shift+d down), size it to taste (cmd+ctrl+arrows), and run sidelight in the split next to pi.

PI session awareness (v0.2)

The [4] Sessions tab shows your project's PI sessions live (name, activity, prompts, model, cost). It needs the bundled PI extension, which records sanitized metadata only — never message content. Enable it with:

pi install npm:sidelight

Or try it once without installing: pi -e npm:sidelight. Running from a clone instead? Point ~/.pi/agent/settings.json at it: "extensions": ["<path-to-repo>/extension/index.ts"].

The extension writes one small JSON snapshot per session under ~/.local/state/sidelight/sessions/ (or $XDG_STATE_HOME/sidelight/sessions/) — open one with cat to see exactly what is recorded: timestamps, counts, tool-call counts, deny-list-filtered file paths, token totals, cost, the model id, and the session name you set with /name. Nothing else.

Other agents: Claude Code and Codex (v0.6)

The same Sessions tab works beside Claude Code and Codex through their hooks systems. Each adapter is a tiny program that ships with sidelight, runs for milliseconds per event, and records the same sanitized metadata — never message content, never command strings. Setup is one command:

Claude Code:

sidelight-claude-code-hook --install

Codex:

sidelight-codex-hook --install

Each shows you the exact change to your agent's config, makes a timestamped backup, and asks before writing — nothing happens without your explicit yes. --uninstall reverses it just as cleanly, and --print-config prints the snippet if you prefer to merge by hand.

Codex asks you to trust the hooks on first interactive run (non-interactive codex exec needs --dangerously-bypass-hook-trust).

Honest limitations, by design: tokens/cost stay at 0 for both (their hooks don't expose usage, and sidelight never parses message-bearing transcripts); Codex mostly runs files through shell commands, so its filesTouched stays sparse (command strings are never read); Codex has no session-end event, so its sessions display as active.

Keys

1 / 2 / 3 / 4 — Files / Git / Search / Sessions panel
j / k / arrows — move selection · g / G — jump to top / bottom (works in every list and preview)
Enter — expand/collapse dir, run search, preview file, open diff, session detail
y — yank to clipboard (path from lists; path:line from a preview; resume command from sessions) via OSC 52
In a preview or session detail: j/k move the cursor line · Esc back to where you were (state preserved)
/ — jump to search input · Esc — toggle input/results focus
Search is smart-case: all-lowercase queries match any case; an uppercase letter makes it exact
Search results: files section (filename matches) first, then content matches, query highlighted
r — refresh all panels (git status and sessions also auto-refresh via fs watchers)
q / Ctrl+C — quit

A closer look

Review what your agent changed — diff stats on every file, colored diffs on Enter.

Git panel diff view with green additions, red removals, and dim hunk headers

Search finds files and content — smart-case, every match highlighted.

Search results with a files section and highlighted content matches grouped by file

Preview any file or match at its exact line, then Esc back to where you were.

File preview with cursor line and highlighted search matches

Know what each agent session touched — and what it cost.

Session detail showing prompts, turns, tool calls, tokens, cost, files touched, and a resume command

Guarantees

Respects .gitignore (files/search built on git ls-files / git grep) plus a built-in deny-list (.env*, *.pem, *.key, *_rsa*, node_modules, .git) applied to every surface: file tree, search results, git status, previews.
The sidecar is read-only: never modifies, writes, or indexes anything.
The session recorders (PI extension, Claude Code and Codex hook adapters) write only their own state dir, only allowlisted metadata fields, and never message bodies, prompts, or command strings.
Works degraded outside git repos (deny-listed file browser; search disabled) and without the extension (Sessions tab shows how to enable it).

Philosophy

Sidelight is deliberately restrained: read-only toward your project, no network, no telemetry, no daemon, no index, content only on explicit keypress. The boundaries are a feature — see PHILOSOPHY.md for the guarantees and the list of things we will never add.

Support

Sidelight is free and open source. If it helps your workflow, you can support development at ko-fi.com/annbjer.

The story

How (and why) sidelight was built — one human, three AIs, one hot July weekend: annbjer.com/articles/sidelight-the-visibility-layer-my-terminal-was-missing