Lectern runs coding agents such as Claude Code, Codex and Gemini CLI on your own computer, and lets you follow them, approve what they do and review their changes from your terminal, browser or phone.
You need Git and, for real work, an agent CLI such as Claude Code, Codex or Gemini CLI. Without one you can still try Lectern with its built-in demo agent.
macOS and Linux
curl -fsSL https://raw.githubusercontent.com/JeremiahM37/lectern/main/install.sh | shOr on macOS with Homebrew: brew install JeremiahM37/tap/lectern
Windows (PowerShell, with Git for Windows installed)
irm https://raw.githubusercontent.com/JeremiahM37/lectern/main/install.ps1 | iexOr with Scoop: scoop bucket add jeremiahm37 https://github.com/JeremiahM37/scoop-bucket && scoop install lectern
Then, in a project folder:
cd ~/myapp
lectern claude # start your first agent here (or: lectern codex, lectern gemini)
lectern up # open the web dashboard in your browser
lectern phone # show a QR code to pair a phone on the same Wi-FiThe agent keeps running when you leave the terminal (Ctrl+] then d), and the same session shows up in the browser and on your phone. On a new install the agent asks before risky actions, such as running a command or editing a file, and you can answer from any of them.
New to Lectern? Getting started walks through your first session: install, start an agent, approve from the browser and the phone, then review and commit the change.
lectern doctor checks your setup and prints a fix for anything missing.
lectern update installs a new release. lectern help lists every command.
Watch the one-minute walkthrough · Screenshots
Demo projects with scripted agent responses.
- Watch and talk to agents. Every session has a terminal and a chat view. See which sessions are working, idle or waiting for you.
- Approve or deny. A pending request shows the command or the diff, with Allow once, Allow for this session or Deny, on the desktop and on the phone.
- Review and commit. Review & merge shows what the agent changed. Leave comments for the agent, stage what you want and commit. On your main branch it offers a new branch first.
- Use your phone. The phone layout is installable as an app, with notifications when an agent needs you. On Android there is also a native app (the APK is on each release) that approves from the notification and updates itself.
Terminal client · Phone supervision · Review
Everything above runs on one computer. Lectern can also manage agents across several machines.
A coding task needs somewhere to run, a workspace of its own, and a way to bring you back when it needs a decision. Lectern connects those pieces across the machines you already use.
- Choose the machine and project. Work locally, on a server over SSH, in an existing Proxmox LXC, or in a fresh sandbox for each task attempt.
- Dispatch to your agent of choice. Queue work with per-machine concurrency limits. Task attempts get separate git worktrees; race agents on the same problem or use a lead agent to review delegated work.
- Supervise and review from anywhere. Return to the terminal, inspect changes, answer an approval on your phone, or continue the conversation with another agent.
flowchart LR
U["Terminal · Web · Phone · MCP"] --> L["Lectern<br/>Projects, task queue, sessions & approvals"]
L --> W["Workstation<br/>Local execution"]
L --> S["Servers & VPSes<br/>SSH execution"]
L --> E["Disposable environments<br/>Proxmox · Docker · Script hooks"]
W & S & E --> A["Claude Code · Codex · Gemini CLI · Custom agents"]
A --> R["Changes, checks & requests for approval"]
R --> U
Today, placement is explicit: a project selects its machine and the scheduler runs its queued tasks there. Automatic placement by GPU, RAM or OS requirements is a future direction, not a current feature. Worktrees separate changes; use a sandbox when you also need execution isolation.
| Execution environment | What Lectern does |
|---|---|
| Your workstation | Runs the installed agent CLIs locally, with persistent terminals on Linux, macOS and Windows. |
| SSH server or VPS | Runs agents and manages workspaces remotely. Import SSH aliases, use jump hosts, and reconnect to sessions. |
| Existing Proxmox LXC | Executes through pct from the Proxmox host. |
| Disposable sandbox | Creates a Proxmox template clone, Docker container, or environment supplied by trusted script hooks for each attempt. Saves results before configured cleanup. |
Run a shared server · SSH machines · Sandbox providers and lifecycle · Isolation options and limits
Claude Code, Codex and Gemini CLI are built in. Add OpenCode, Aider, Goose, Cursor and other runners from the catalog, or configure a custom CLI. Agent capabilities vary; Lectern exposes what each runner supports.
Switch a session to another agent with a saved handoff. Adopt Claude and Codex sessions started outside Lectern, search saved conversations, and restore ended sessions when the agent has resumable history.
Agent catalog and capabilities · Delegated builds · Replay evals
Phone pairing on the same Wi-Fi needs nothing extra. Away from home, use Tailscale, a public tunnel with device pairing, or the optional end-to-end encrypted relay.
Start work from a claude.ai or supported ChatGPT connector, too: send a design or attachment into a session on your machine. Chat connectors cannot approve agent actions.
Remote access · Relay · Chat connectors
- Files travel with the work. Open a remote PDF or file path an agent prints; the native client opens it locally, while the web app has a built-in viewer. Drop files into the web workspace or upload them to a session. Files · Paths and links
- Review and follow-through. Inspect diffs, run checks, open PRs, and send failed CI results back to the agent. Review · CI loop
- Continuity. Restore sessions, handle provider rate limits, track usage and budgets, and bring project knowledge through optional Grimoire integration. Rate limits · Budgets · Memory
- A browser beside the work. Watch the agent's browser, take over, or send a page element's context back to the agent. Browser tools
More screenshots and file demonstrations · Full guide
| Docker | docker run -d -p 127.0.0.1:9110:9110 -e LECTERN_INSECURE_LISTEN=1 -v lectern-data:/data ghcr.io/jeremiahm37/lectern:latest |
| Go | go install github.com/JeremiahM37/lectern/v2/cmd/lectern@latest |
| deb / rpm | Packages are attached to each release. |
On the machine that runs Lectern, agents need only git and the agent's own
CLI: Lectern keeps their terminals alive itself, on Linux, macOS and Windows
(how). Other machines reached over SSH need the lectern
binary installed, or tmux and python3. The web terminal is built in.
To try it with fake agents and no setup: LECTERN_MOCK=1 lectern serve (it
listens on 127.0.0.1 only).
| Getting started | Install, first agent, approvals on the web and phone, review and commit |
| Full guide | Everything in depth: sessions, tasks, auth, phone alerts, delegated builds, local models |
| Use from claude.ai / ChatGPT | The chat connector: setup, what a chat can do, troubleshooting |
| Terminal client | Dashboard keys, multi-window, lectern claude, send-file |
| Agents | Catalog, capabilities per agent, custom agents |
| Mobile sessions | Chat cards, approvals, voice mode |
| Browser | Browser pane, Design Mode, agent browser tools, computer use |
| Remote access | Phone pairing and tunnels without Tailscale |
| Local runtime · Shared server · Docker | How the private runtime works, building from source, a server for several machines, containers |
Lectern was called AgentDeck until v2.3. Old AGENTDECK_* settings still work.
MIT © Jeremiah Mackey