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.

omartelo.github.io/lich

About

lich is a harness for AI coding agents — a desktop app that wraps a
terminal-first workspace around them. Open several projects, run a session (or
many) per project, drive an agent in each, and watch git state — branches,
diffs, worktrees, pull requests — without ever leaving the window. It ships as a
single static Go binary that opens its UI in your system's Chromium-family
browser in --app mode — no Electron, no bundled webview (decision record:
docs/chromium-shell.md).

It is built to get out of the way of the work — the terminal stays a real
terminal, and git stays where you can see it. Development is active: bugs and
feature requests belong in
Issues, and what changed in each
version is in CHANGELOG.md.

Features

• Bring your own agent. Claude Code
  (Anthropic), Codex (OpenAI),
  opencode (SST) and
  Crush (Charm) are all first-class:
  point lich at each binary in Settings, pick the default, or choose per session.
• Terminal-first sessions. Real PTY-backed shells, several per project,
  rendered by xterm.js on the GPU (WebGL). Search the scrollback (Ctrl+F); the
  buffer survives a full page reload. A Warp-style footer follows cd and
  surfaces git status, and for a Claude session it names the model, fills a ring
  with the context window in use, and — if you ask it to — prices what the
  session has spent.
• Projects and sessions. Projects sit on a top tab bar; the + reopens one
  you recently closed or opens the OS folder picker for the rest. Session cards
  carry the working directory, branch, a diff badge, an untracked-line count and
  the number of the branch's pull request.
• Git worktrees, built in. Spin one up from any base branch — search it,
  local or remote, even across dozens of branches — and lich seeds the new
  checkout with your gitignored .env* files, hands it a stable dev-server port
  derived from its path (LICH_WORKTREE_PORT) and runs a per-project setup
  script before the agent starts. The sidebar groups sessions by the worktree they belong to, and a kept
  worktree's session resumes its conversation later.
• Review, and hand the review back. A CodeMirror diff dock shows the working
  changes beside a live file tree — collapse or expand every file at once, open
  one in your editor, attach one to the session. Right-click a selection to write
  a comment against those lines; the batch is handed over as a single prompt,
  pasted into the session unsent.

Comments written on the diff, handed to the session as one prompt.

• Pull requests, end to end. A button in the tab bar lists the repository's
  open pull requests — quick filters plus GitHub's own qualifiers (is:draft,
  review:approved, is:merged) — and Open in Session checks one out into
  its own worktree. A pull request opens full-screen: overview, checks, commits
  and the whole diff beside a file tree. Review it where you read it — a thread
  opens inline under the line it is about, and your own comments wait as pending
  until Submit review sends them together — approve it, and merge it (squash,
  merge commit or rebase) with the methods the base branch actually accepts.
• Themes, yours or someone else's. Bundled light and dark, plus imported JSON
  that recolors the interface and the terminal palette independently. Install a
  pack from a git repository and update it in place when it ships a new version;
  Save template writes a starter naming every supported color. Format and
  repository layout: docs/themes.md.
• The rest of the window. Ctrl/Cmd+K jumps between sessions and
  projects. A session waiting on your input raises a toast and a dot on the bell,
  collected in a titled dropdown; with the
  lich plugin installed, a Claude
  session also titles its own card and refreshes git the moment it writes a file.
  Settings › Help opens the log folder and a pre-filled bug report.

The repository's pull requests, filtered by GitHub's own qualifiers.

Read, approved and merged in place.

A review written on the diff itself — each comment pending until you submit them together.

A theme pack installed from a git repository, updated in place.

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

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 binary downloaded from the Releases page needs its quarantine flag cleared by
hand.

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 — in Settings › Providers, set the binary path
   for Claude Code, Codex, opencode or Crush, and choose a default.
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; UI
  preferences persist in localStorage under lich.* keys (inside lich's
  Chromium profile at ~/.config/lich/chromium-profile), 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.

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.

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

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.