A lazygit-inspired TUI for orchestrating coding agents across git worktrees.

---

Motivation

You have a big feature to ship. You crack open three terminals, cd into three worktrees, and spawn three coding agents. Ten minutes later you're alt-tabbing through a mess of tabs, trying to remember which agent finished, which one is stuck waiting for approval, and which one silently errored out five minutes ago.

lazyagent does for coding agents what lazygit did for git: one TUI, full visibility, zero tab-juggling.

Highlights

• Multi-agent orchestration — spawn, monitor, and stop agents across git worktrees from a single screen
• Real-time provider-aware status — know instantly if an agent is running, waiting for approval, idle, or done
• Multi-provider support — Claude, Codex, and Gemini out of the box, configurable per repo
• Embedded terminal — drop into any worktree's shell without leaving the TUI
• Inline diff view — review working-tree changes (tracked + untracked) right next to agent output
• PR / CI at a glance — pull request state, review status, and CI checks per worktree (via gh)

Installation

Prerequisites: Python 3.10+, git, and at least one agent CLI (claude, codex, or gemini).

uv (recommended)

uv tool install lazyagent

pip

pip install lazyagent

Optional: install the GitHub CLI (gh) to enable PR and CI status features.

Quick Start

cd your-repo
lazyagent

From there:

1. Create worktrees — press c to branch off parallel workstreams
2. Spawn agents — press s to launch a coding agent in the selected worktree
3. Monitor — watch agent output stream in real time; status badges update automatically
4. Interact — press Ctrl+L to drop into the embedded terminal for hands-on work
5. Review — press Ctrl+D to inspect diffs before committing
6. Clean up — press d to remove worktrees when done

By default lazyagent launches claude. Set provider = "codex" or provider = "gemini" in .lazyagent.toml to switch.

Claude Code MCP Integration (optional)

lazyagent ships an MCP server that exposes its worktree and agent tools (list_worktrees, spawn_agent, read_agent_output, …) to a standalone claude session — useful when you want claude running outside lazyagent's TUI to drive a lazyagent instance you have running elsewhere.

Agents that lazyagent itself spawns (worktree agents and the orchestrator) get the MCP server wired up automatically. The setup below is only needed for claude sessions you start by hand in other projects.

Register it once at user scope so claude finds it from any directory:

claude mcp add --scope user lazyagent $(which python3) -m lazyagent.mcp_server

If claude mcp add swallows -m as one of its own flags, separate args with --:

claude mcp add --scope user lazyagent $(which python3) -- -m lazyagent.mcp_server

Verify from a directory outside the lazyagent repo:

cd /tmp && claude mcp list | grep lazyagent

Interpreter caveat: the python you register must be the one that pip-installed lazyagent. If python3 -m lazyagent.mcp_server fails with No module named 'lazyagent', substitute the right interpreter (e.g. /usr/bin/python3.11, your pipx env's python, or uv tool dir lazyagent's python) and re-run claude mcp add. The MCP tools talk to a running lazyagent over a Unix socket under /tmp/lazyagent-<pid>/ and will return No running lazyagent instance found if no lazyagent is running.

Features

Worktree Management

Create, remove, and navigate git worktrees without leaving the TUI. Each worktree gets its own agent, terminal, and diff view — perfect for parallelizing tasks across branches.

Agent Observability

lazyagent doesn't just scrape terminal output. It taps into each provider's native signals for high-confidence state detection:

Provider	Signal Source	What It Catches
Claude	Hooks (JSONL logs)	Permission prompts, idle states, task completion
Codex	App Server Events (JSON-RPC)	Turns, approval requests, failures
Gemini	Telemetry (file export) + screen detection	Activity, session boundaries

Statuses are normalized into a clear lifecycle:

Status	Color	Meaning
running	green	Actively working or calling tools
approving	yellow	Waiting for user approval
waiting	yellow	Idle or waiting for input
completed	cyan	Task finished
failed	red	Error or turn failure

Diff Tab

Press Ctrl+D to see working-tree changes (both tracked and untracked files) rendered inline. Review what your agents have done before committing.

PR / CI Status

When the gh CLI is available, lazyagent shows pull request state, review status, and CI check results per worktree — no browser needed.

Embedded Terminal

Press Ctrl+L to open a full terminal session inside any worktree. Run tests, inspect files, or interact with agents directly — then jump back to the overview.

Configurable Providers

Switch between claude, codex, and gemini globally or per repository via .lazyagent.toml. Custom worktree create/remove commands are also supported.

Keybindings

Key	Action
j / k	Move down / up in sidebar
Ctrl+K	Focus sidebar
Ctrl+J	Focus agent pane
Ctrl+D	Focus diff pane
Ctrl+L	Focus terminal pane
s	Spawn agent in selected worktree
x	Stop agent in selected worktree
c	Create new worktree
d	Remove selected worktree
r	Refresh worktree list
PageUp / PageDown	Scroll terminal history
?	Show help
q	Quit

Configuration

Create a .lazyagent.toml in your repository root:

# Branch to base new worktrees on (default: "master")
default_branch = "main"

[agent]
# Agent CLI to launch: "claude" (default), "codex", or "gemini"
provider = "claude"

[worktree]
# Custom command templates for worktree management
# Available placeholders: {branch}, {name}, {base}, {path}, {repo}
create = "git worktree add -b {branch} ../{name} {base}"
remove = "git worktree remove ../{name}"

Development

git clone https://github.com/gioalcamofly/lazyagent.git
cd lazyagent
uv sync --group dev
uv run pytest

Acknowledgements

• lazygit — the inspiration for the UX and workflow
• Textual — the TUI framework powering the interface
• pyte — terminal emulation for agent output capture

License

AGPL-3.0