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.

Quick Start

Prerequisites

• Node.js 24+ (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)

Install & Run

pnpm install
pnpm dev

Open http://localhost:5173

Why?

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.

Features

🖥️ Multi-Terminal Management

• 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

📋 Thread Organization

• Table view — sortable, filterable thread listing with bulk operations
• Card view — detailed cards grouped by date
• Kanban view — organize threads across 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

🔍 Discovery & Context

• 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

🛠️ Built-in Tools

• 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

🎨 Customization

• 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

Architecture

┌─────────────────────────────────────────────────────────┐
│                    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/

Data Storage

Location	Purpose
~/.local/share/amp/threads/	Amp's thread JSON files (read by the server)
~/.amp-thread-manager/threads.db	Local SQLite for status, blockers, linked issues
~/.amp-thread-manager/artifacts/	Saved images and notes per thread

Keyboard Shortcuts

Shortcut	Action
Ctrl/⌘+O	Command palette
Alt+N	New thread
Ctrl/⌘+R	Refresh threads / prompt history
Ctrl/⌘+W	Close current thread
Ctrl/⌘+B	Toggle sidebar
Ctrl/⌘+H	Handoff current thread
Ctrl+T	Open shell terminal
Ctrl+M	Thread map
Alt+D	Toggle deep mode
Alt+L	Toggle layout
Alt+[ / Alt+]	Switch tabs
j/k or ↓/↑	Navigate thread list
Enter	Open focused thread
x	Toggle selection
Esc	Close modal / clear focus

Scripts

Command	Description
pnpm dev	Start dev server (Vite frontend + Node backend)
pnpm build	Build for production
pnpm start	Build and serve production
pnpm check	Format check + lint + typecheck + build
pnpm lint	ESLint
pnpm typecheck	TypeScript type check
pnpm test	Run tests (Vitest)
pnpm test:watch	Run tests in watch mode

Configuration

Environment Variable	Default	Description
PORT	3001	Backend server port
AMP_HOME	$HOME	Base directory for Amp data
AMP_BIN	auto-detected	Path to the amp CLI binary

Security

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

Troubleshooting

Native module build errors (better-sqlite3, node-pty)

These packages require compilation. Make sure you have:

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

If builds fail, try: pnpm rebuild

"Amp CLI not found"

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

Port already in use

Set a different port: PORT=3002 pnpm dev

Tech Stack

• 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)

License

Apache License 2.0