lazyagent

A terminal UI, macOS menu bar app, and HTTP API for monitoring all your coding agents — Claude Code, Cursor, Codex, pi, and OpenCode — from a single place. No lock-in, no server, purely observational.

Inspired by lazygit, lazyworktree, and pixel-agents.

Why lazyagent?

Unlike other tools, lazyagent doesn't replace your workflow — it watches it. Launch agents wherever you want (terminal, IDE, desktop app), lazyagent just observes. No lock-in, no server, no account required.

⭐ If lazyagent is useful to you, consider starring the repo — it helps others discover it!

Want to support lazyagent's development? If this project saves you time or you just love it, consider becoming a sponsor. It keeps the project alive and growing — every bit counts!

Terminal UI

macOS Menu Bar App

HTTP API

How it works

lazyagent watches session data from coding agents to determine what each session is doing. No modifications to any agent are needed — it's purely observational.

Supported agents:

• Claude Code CLI — reads JSONL from ~/.claude/projects/*/
• Claude Code Desktop — same JSONL files, enriched with session metadata (title, permissions) from ~/Library/Application Support/Claude/claude-code-sessions/
• Cursor — reads SQLite from ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
• Codex CLI — reads JSONL from ~/.codex/sessions/YYYY/MM/DD/*.jsonl
• pi coding agent — reads JSONL from ~/.pi/agent/sessions/*/
• OpenCode — reads SQLite from ~/.local/share/opencode/opencode.db

Use --agent claude, --agent pi, --agent opencode, --agent cursor, --agent codex, or --agent all (default) to control which agents are monitored. Agents can also be enabled/disabled in the config file. Pi sessions are marked with a π prefix, Cursor with C, Codex with X, OpenCode with O, and Desktop sessions with a D prefix in the session list.

From the JSONL stream it detects activity states with color-coded labels:

• idle — Session file exists but no recent activity
• waiting — Claude responded, waiting for your input (with 10s grace period to avoid false positives)
• thinking — Claude is generating a response
• compacting — Context compaction in progress
• reading / writing / running / searching / browsing / spawning — Tool-specific activities

It also surfaces:

| Info | Source | |------|--------| | Working directory | JSONL | | Git branch | JSONL | | Claude version | JSONL | | Model used | JSONL | | Is git worktree | git rev-parse | | Main repo path (if worktree) | git worktree | | Message count (user/assistant) | JSONL | | Token usage & estimated cost | JSONL | | Activity sparkline (last N minutes) | JSONL | | Last file written | JSONL | | Recent conversation (last 5 messages) | JSONL | | Last 20 tools used | JSONL | | Last activity timestamp | JSONL | | Session source (CLI / Desktop) | Desktop metadata | | Desktop session title | Desktop metadata | | Permission mode (Desktop) | Desktop metadata | | Custom session name | ~/.config/lazyagent/session-names.json |

Three interfaces, one binary

lazyagent ships as a single binary with three interfaces:

| | TUI | macOS Detachable Menu Bar | HTTP API | |---|---|---|---| | Interface | Terminal (bubbletea) | Native menu bar panel (Wails v3 + Svelte 5) | REST + SSE | | Launch | lazyagent | lazyagent --gui | lazyagent --api | | Dock icon | N/A | Hidden (accessory) | N/A | | Sparkline | Unicode braille characters | SVG area chart | JSON data | | Theme | Terminal colors | Catppuccin Mocha (Tailwind 4) | N/A |

All three share internal/core/ — session discovery, file watcher, activity state machine, cost estimation, and config. You can combine them freely: lazyagent --tui --gui --api.

Install

Homebrew

brew tap illegalstudio/tap
brew install lazyagent

Go (TUI only)

go install github.com/illegalstudio/lazyagent@latest

Build from source

git clone https://github.com/illegalstudio/lazyagent
cd lazyagent

# TUI only (no Wails/Node.js needed)
make tui

# Full build with menu bar app (requires Node.js for frontend)
make install   # npm install (first time only)
make build

Usage

lazyagent                        Launch the terminal UI (monitors all agents)
lazyagent --agent claude         Monitor only Claude Code sessions
lazyagent --agent pi             Monitor only pi coding agent sessions
lazyagent --agent opencode       Monitor only OpenCode sessions
lazyagent --agent cursor         Monitor only Cursor sessions
lazyagent --agent codex          Monitor only Codex CLI sessions
lazyagent --agent all            Monitor all agents (default)
lazyagent --api                  Start the HTTP API (http://127.0.0.1:7421)
lazyagent --api --host :8080     Start the HTTP API on a custom address
lazyagent --tui --api            Launch TUI + API server
lazyagent --gui                  Launch as macOS menu bar app (detaches)
lazyagent --gui --api            Launch GUI + API server (foreground)
lazyagent --tui --gui --api      Launch everything
lazyagent --help                 Show help

TUI

Keybindings

| Key | Action | |-----|--------| | ↑ / k | Move up / scroll up (detail) | | ↓ / j | Move down / scroll down (detail) | | tab | Switch focus between panels | | + / - | Adjust time window (±10 minutes) | | f | Cycle activity filter | | / | Search sessions by project path | | o | Open session CWD in editor (see below) | | r | Rename session (empty name resets) | | q / ctrl+c | Quit |

macOS Detachable Menu Bar App

lazyagent --gui

The GUI process detaches automatically — your terminal returns immediately. The app lives in your menu bar with no Dock icon. Click the tray icon to toggle the panel.

The panel is detachable: press d or click the detach button to pop it out into a standalone resizable window. Once detached, you can pin it always-on-top. Press d again or close the window to snap it back to the menu bar.

Keybindings

| Key | Action | |-----|--------| | ↑ / k | Move up | | ↓ / j | Move down | | + / - | Adjust time window (±10 minutes) | | f | Cycle activity filter | | / | Search sessions | | r | Rename session (empty name resets) | | d | Detach/attach window | | esc | Close detail / dismiss search |

Right-click menu

• Show Panel — open the session panel
• Refresh Now — force reload all sessions
• Quit — exit the app

HTTP API

lazyagent --api

Starts a read-only HTTP API server on http://127.0.0.1:7421 (default port, with automatic fallback if busy).

| Endpoint | Description | |----------|-------------| | GET /api | Interactive playground (open in browser) | | GET /api/sessions | List visible sessions (?search=, ?filter=) | | GET /api/sessions/{id} | Full session detail | | PUT /api/sessions/{id}/name | Rename session ({"name": "..."}, empty resets) | | DELETE /api/sessions/{id}/name | Remove custom name | | GET /api/stats | Summary stats (total, active, window) | | GET /api/config | Current configuration | | GET /api/events | SSE stream for real-time updates |

To expose on the network (e.g. for a mobile app):

lazyagent --api --host 0.0.0.0:7421

Full API documentation: docs/API.md

Editor support

Pressing o (TUI) or the Open button (app) opens the selected session's working directory in your editor.

Cursor sessions automatically open in Cursor IDE (if the cursor CLI is installed). If not installed, the standard editor flow below is used.

| Configuration | Behavior | |---------------|----------| | Both $VISUAL and $EDITOR set | A picker popup asks which one to use (TUI only) | | Only $VISUAL set | Opens directly as GUI editor | | Only $EDITOR set | Opens directly as TUI editor (suspends the TUI) | | Neither set | Shows a hint to configure them |

# Example: add to ~/.zshrc or ~/.bashrc
export VISUAL="code"   # GUI editor (VS Code, Cursor, Zed, …)
export EDITOR="nvim"   # TUI editor (vim, nvim, nano, …)

Configuration

lazyagent reads ~/.config/lazyagent/config.json (created automatically with defaults on first run):

{
  "window_minutes": 30,
  "default_filter": "",
  "editor": "",
  "launch_at_login": false,
  "notifications": false,
  "notify_after_sec": 30,
  "agents": {
    "claude": true,
    "codex": true,
    "cursor": true,
    "opencode": true,
    "pi": true
  },
  "claude_dirs": []
}

| Field | Default | Description | |-------|---------|-------------| | window_minutes | 30 | Time window for session visibility (minutes) | | default_filter | "" | Default activity filter (empty = show all) | | editor | "" | Override for $VISUAL/$EDITOR | | launch_at_login | false | Auto-start the menu bar app at login | | notifications | false | macOS notifications when a session needs input | | notify_after_sec | 30 | Seconds before triggering a "waiting" notification | | agents | all true | Enable/disable individual agent providers | | `c