Thread Manager for Amp

A local web UI for managing Amp AI coding agent threads — monitor, interact with, and organize multiple concurrent agent sessions from your browser.

• Node.js 25+ (needed to compile native modules like better-sqlite3 and node-pty)
• pnpm 10+ — install with npm install -g pnpm
• Amp CLI installed and authenticated (amp command available)

pnpm install
pnpm dev

Open http://localhost:5173

When working with multiple Amp threads simultaneously — across repos, features, and tasks — it's hard to keep track of what's running, what's blocked, and what each thread has done. This tool gives you a single dashboard to manage it all.

• Run multiple Amp threads side-by-side with tabs, split views, and grid layouts
• Real-time streaming of agent output via WebSocket
• Rich message rendering with syntax highlighting for code and tool outputs
• Conversation minimap for navigating long threads
• Auto-reconnect on connection drops with output resumption

• Table view — sortable, filterable thread listing with bulk operations
• Card view — detailed cards grouped by date
• Kanban view — drag threads between status columns (Active, Blocked, Paused, Done)
• Thread status tracking with blocker relationships between threads
• Labels and linked issue URLs for organization
• Handoff support to create continuation threads

• Thread chains — visualize parent/child handoff relationships
• Related threads — find threads that touched the same files
• Git activity — see commits, branches, and PRs correlated to each thread
• Source control — view uncommitted changes per workspace with inline diffs
• Content search — full-text search across all thread messages

• Shell terminal — integrated xterm.js terminal sessions
• Command palette (⌘O) — quick access to all actions
• Skills management — list, add, and remove Amp skills
• MCP status — view connected MCP servers
• Image viewer — view images attached to or generated by threads

• 30+ theme presets — Cyberpunk 2077, Dracula, Tokyo Night, Nord, Catppuccin, Gruvbox, and more
• Adaptive theme system that derives a full UI from just 3 colors (bg, fg, accent)
• Light and dark themes supported
• Configurable layouts and view preferences
• Notification sounds for completed tasks

┌─────────────────────────────────────────────────────────┐
│                    Frontend (React 19)                   │
│  src/                                                    │
│  ├── components/     # UI components                     │
│  │   ├── terminal/   # WebSocket terminal + messages     │
│  │   ├── ThreadList/ # Table view with bulk selection    │
│  │   ├── sidebar/    # Workspace tree navigation         │
│  │   └── Toolbar/    # Search, filters, view switching   │
│  ├── hooks/          # Data fetching + state hooks       │
│  ├── commands/       # Command palette registry          │
│  └── lib/            # Theme system, utilities           │
└─────────────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────────────┐
│               Shared (shared/)                           │
│  types.ts, websocket.ts, validation.ts, cost.ts,         │
│  utils.ts, constants.ts                                  │
└─────────────────────────────────────────────────────────┘
                           │
                    HTTP + WebSocket
                           │
┌─────────────────────────────────────────────────────────┐
│                 Backend (Node.js)                        │
│  server/                                                 │
│  ├── websocket.ts    # Per-thread session management     │
│  ├── shell-websocket.ts  # Shell terminal PTY sessions   │
│  ├── routes/         # REST API handlers                 │
│  │   ├── threads.ts  # Thread CRUD + search + discovery  │
│  │   ├── metadata.ts # Status, labels, blockers          │
│  │   ├── git.ts      # Git status + diffs                │
│  │   ├── skills.ts   # Amp skills + MCP management       │
│  │   └── artifacts.ts # Notes + image storage            │
│  └── lib/            # Core logic                        │
│      ├── threadCrud.ts    # Thread CRUD operations        │
│      ├── threadSearch.ts  # Search + related threads      │
��      ├── threadExport.ts  # Markdown + image export       │
│      ├── threadChain.ts   # Handoff chains                │
│      ├── database.ts # SQLite for local metadata         │
│      ├── amp-api.ts  # Amp internal API client           │
│      ├── git.ts      # Git operations                    │
│      └── git-activity.ts  # Commit/branch correlation    │
└─────────────────────────────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     ~/.local/share/amp/        ~/.amp-thread-manager/
     └── threads/*.json         ├── threads.db (SQLite)
         (Amp thread data)      └── artifacts/

This is a local development tool. The server binds to localhost only and is not accessible from other devices. See SECURITY.md for details.

These packages require compilation. Make sure you have:

• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: build-essential, python3
• Node.js 25+ (check with node -v)

If builds fail, try: pnpm rebuild

Make sure amp is in your PATH, or set AMP_BIN to the full path of the binary.

Set a different port: PORT=3002 pnpm dev

• Frontend: React 19, TypeScript, Vite
• Backend: Node.js with raw http module (no Express)
• Database: SQLite via better-sqlite3
• WebSocket: ws for real-time agent streaming
• Terminal: xterm.js + node-pty for shell sessions
• Testing: Vitest, Testing Library
• Styling: CSS custom properties (no UI framework)

Apache License 2.0