lich

English · 简体中文

A terminal-first harness for coding with AI agents.

Open your projects, run agents like Claude Code, Codex and opencode in real terminals, and keep git — worktrees, diffs and pull requests — in view without leaving the window. One static Go binary, no Electron: the UI opens in your system's Chromium-family browser in --app mode.

omartelo.github.io/lich

Why lich

lich lets you:

• Run the agent you already have. Claude Code, Codex, opencode, oh-my-pi and Crush are all first-class. Point lich at each binary once, then pick the default or choose per session.
• Keep a real terminal. PTY-backed shells, several per project, rendered on the GPU — searchable scrollback that survives a full page reload. The footer follows cd and names the branch — and, for a Claude session, the model, the context window in use and, if you ask, what the session has spent.
• Put one session to work for another. Hand a task to another card and its own agent writes the answer back, whatever runs in either end: the agent reaches the other sessions through tools handed at spawn — MCP for Claude Code and Codex — or brought by the plugin. The whole surface doubles as the lich command in any shell, --json included, so a script can drive a session with no agent in the loop (docs/cli.md).
• Branch off a worktree without the setup. Spin one up from any base branch and lich seeds it with your gitignored .env* files, hands it a dev-server port no other checkout and no process on the machine is using, and runs your per-project setup script before the agent starts.
• Review the diff where you read it. A CodeMirror dock shows the working changes beside a live file tree. Right-click a selection to comment against those lines; the batch is pasted into the session as a single prompt, unsent.
• Ship the pull request from here. List the repository's open pull requests, check one out into a worktree of its own, then read the diff, review it inline and merge it — with the methods the base branch actually accepts.

Plus: themes you import as JSON or install from a git repository, a Ctrl/Cmd+K palette that jumps by name or by what was said in the conversation, a desktop notification when a session is waiting on you, and lich rage / lich doctor for when it will not start at all.

Development is active: bugs and feature requests belong in Issues, and what changed in each version is in CHANGELOG.md.

Install

One line — detects your distro, verifies the checksum, and installs the native package and its dependencies through your package manager:

curl -fsSL https://raw.githubusercontent.com/omartelo/lich/main/install.sh | sh

Platform	Get it	Needs at runtime
Linux	install.sh above, or AUR lich-bin (yay -S lich-bin)	chromium / google-chrome / brave on PATH, plus zenity
macOS (experimental)	brew install --cask omartelo/tap/lich	Chrome / Chromium / Edge / Brave in /Applications
Windows (experimental)	installer from Releases	Chrome / Edge / Brave

Manual per-distro packages and the static binary: INSTALL.md. The macOS and Windows binaries are unsigned — Gatekeeper and SmartScreen warn until notarization/signing ship. Homebrew installs sidestep the Gatekeeper prompt; a download from the Releases page needs its quarantine flag cleared by hand. On macOS the cask installs Lich.app, so lich has its own icon in /Applications; the Dock, while it runs, shows the browser that owns the window.

Getting started

1. Install and launch lich.
2. Open a project — the + in the tab strip lists what you closed recently and opens your OS folder picker; point it at a git repository.
3. Point lich at your agent — the first launch lists the agents it found on your machine; in Settings › Providers you can set each binary path and change which one new sessions default to.
4. Start a session — New Session spawns a terminal running your agent in the project.
5. Branch off a worktree (optional) — create one from any base branch; lich seeds it and drops you into a fresh session.

Configuration

• Agents — set each provider's binary path in Settings, and pick which one new sessions default to. Claude Code's section also holds the footer's context ring and its cost readout — the cost one off by default, since the figure only means something when you are billed per token.
• Worktrees — a per-project setup script (Settings › Worktree) runs in a new worktree's terminal ahead of the agent; a .worktreeinclude file tunes which gitignored files get copied over.
• Version control — a project can name the GitHub account gh runs as (Settings › Version Control), for a repository only one of your accounts can see. It governs what lich reads from GitHub, not what git pushes.
• Appearance & hotkeys — themes, fonts and key combos in Settings; the theme you pick persists in the workspace database, the rest of the UI preferences in localStorage under lich.* keys (inside lich's Chromium profile at ~/.config/lich/chromium-profile), and imported themes as JSON under <config-dir>/lich/themes.
• Workspace — projects and sessions persist in SQLite at <config-dir>/lich/lich.db. Closing a session does not delete it.
• Session hooks — with the lich plugin installed from Settings, a session titles its own card and refreshes git the moment it writes a file.

Privacy & updates

Everything runs on your machine. No account, no sign-in, no telemetry — the backend is a token-authenticated loopback listener, and nothing leaves localhost except the update check: a version ping to GitHub Releases at startup and hourly. Updates apply in place on Windows/macOS and through the AUR on Arch. Settings › Help says what the log file carries — paths, project and branch names, your gh login, never a session token — before you attach it to a bug report, and lich rage collects that report into one archive without uploading any of it.

Build from source

Pure-Go backend (Go 1.25, CGO_ENABLED=0) serving an embedded React 18 / TypeScript / Vite frontend over a token-authenticated loopback listener (HTTP RPC

• WebSockets). Terminals are xterm.js with the WebGL addon; the code and diff surfaces are CodeMirror 6. The Chromium shell is a decision record: docs/chromium-shell.md. Prerequisites are Go 1.25+, Node + pnpm and Task — no C toolchain, no system dev libraries.

task dev      # hot-reload dev mode (Vite on :9245)
task build    # production binary -> bin/lich
task run      # build + run
task test     # Go + frontend suites

Package a Linux release locally (needs nfpm):

task package   # .deb + .rpm + Arch .pkg.tar.zst in bin/

Sponsors

lich is written and maintained by one person. Sponsoring pays for the time that goes into it and keeps the project independent: there is no paid tier of the app and there will not be one.

Become a sponsor

Backers

Nobody yet.

License

AGPL-3.0-only © 2026 omartelo

lich is free software: you can use, study, modify and redistribute it under the terms of the GNU Affero General Public License v3. Any distributed or network-served derivative must be released under the same license. Releases up to and including v0.9.0 remain MIT-licensed.