Documentation

How it works

lazyagent watches Claude Code's JSONL transcript files in ~/.claude/projects/*/ to determine what each session is doing. No modifications to Claude Code are needed — it's purely observational.

Activity states

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

Session info

For each session, lazyagent surfaces:

Three interfaces, one binary

lazyagent ships as a single binary with three interfaces that all share the same core engine:

You can combine them freely:

lazyagent --tui --tray --api

Install

Homebrew (TUI)

brew tap illegalstudio/tap
brew install lazyagent

Go (TUI only)

go install github.com/nahime0/lazyagent@latest

Build from source

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

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

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

macOS note

On first launch, macOS may block the binary. Go to System Settings → Privacy & Security, scroll down and click Allow Anyway, then run it again.

Usage

lazyagent                        # Terminal UI (default)
lazyagent --api                  # HTTP API on 127.0.0.1:7421
lazyagent --api --host :8080     # API on custom address
lazyagent --tui --api            # TUI + API server
lazyagent --tray                 # macOS menu bar app (detaches)
lazyagent --tray --api           # Tray + API (foreground)
lazyagent --tui --tray --api     # Everything
lazyagent --help                 # Show help

Terminal UI

The default interface. Full-featured TUI built with bubbletea and lipgloss.

Keybindings

macOS Menu Bar

lazyagent --tray

The tray 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.

Keybindings

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 to 7422–7431 if busy).

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

lazyagent --api --host 0.0.0.0:7421

Editor support

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

# 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:

{
  "windowMinutes": 30,
  "defaultFilter": "",
  "editor": "",
  "launchAtLogin": false,
  "notifications": false,
  "notifyAfterSec": 30
}

Architecture

lazyagent/
├── main.go                     # Entry point: --tui / --tray / --api
├── internal/
│   ├── core/                   # Shared: watcher, activity, session, config
│   ├── claude/                 # JSONL parsing, types, session discovery
│   ├── api/                    # HTTP API server (REST + SSE)
│   ├── ui/                     # TUI rendering (bubbletea + lipgloss)
│   ├── tray/                   # macOS menu bar (Wails v3, build-tagged)
│   └── assets/                 # Embedded frontend dist (go:embed)
├── frontend/                   # Svelte 5 + Tailwind 4 (menu bar UI)
│   ├── src/
│   │   ├── App.svelte
│   │   ├── lib/                # SessionList, SessionDetail, Sparkline
│   │   └── bindings/           # Auto-generated Wails TS bindings
│   └── app.css                 # Tailwind 4 @theme (Catppuccin Mocha)
├── docs/
│   └── API.md                  # Full HTTP API reference
└── Makefile

Development

# Install frontend deps (first time)
make install

# Full build (TUI + tray)
make build

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

# Quick dev cycle (rebuild + run tray)
make dev

# Clean all artifacts
make clean

Requirements

• Go 1.25+
• Node.js 18+ (for frontend build)
• macOS (for the menu bar app — TUI works on any platform)

Roadmap

v0.1 — Core TUI

• Discover all Claude Code sessions from ~/.claude/projects/
• Parse JSONL to determine session status
• Detect worktrees
• Show tool history
• FSEvents-based file watcher with debouncing
• Fallback 30s polling

v0.2 — Richer session info

• Conversation preview (last 5 messages)
• Last file written with age
• Filter by activity type
• Search by project path
• Time window control
• Color-coded activity states
• Memory-efficient single-pass JSONL parsing
• Activity sparkline graph
• Token usage and cost estimation
• Animated braille spinner
• Open CWD in editor (o key)
• Rename sessions (r key)
• Display file diff for last written file

v0.3 — macOS menu bar app

• Core library extraction
• Shared config system
• Wails v3 + Svelte 5 + Tailwind 4 frontend
• System tray with attached panel
• Real-time session updates
• SVG sparkline, activity badges
• Keyboard shortcuts
• Open in editor
• Dynamic tray icon (active count)
• macOS notifications
• Launch at Login
• Code signing & notarization
• DMG distribution
• Homebrew cask

v0.4 — HTTP API

• REST API server
• Session list, detail, stats, config endpoints
• Server-Sent Events (SSE)
• Interactive API playground
• Default port with fallback (7421–7431)
• Custom bind address
• Combinable with TUI and tray
• Session rename endpoints

Future ideas

• Outbound webhooks on status changes
• Multi-machine support
• TUI actions: kill session, attach terminal
• Session history browser