{"id":51307662,"url":"https://github.com/block/thread-manager-for-amp","last_synced_at":"2026-07-01T01:03:10.755Z","repository":{"id":338663991,"uuid":"1157369786","full_name":"block/thread-manager-for-amp","owner":"block","description":"A local web UI for managing Amp AI coding agent threads.","archived":false,"fork":false,"pushed_at":"2026-04-10T17:40:33.000Z","size":1175,"stargazers_count":6,"open_issues_count":5,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T01:30:05.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/block.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-13T18:34:09.000Z","updated_at":"2026-04-09T14:00:55.000Z","dependencies_parsed_at":"2026-03-02T19:02:35.983Z","dependency_job_id":null,"html_url":"https://github.com/block/thread-manager-for-amp","commit_stats":null,"previous_names":["block/thread-manager-for-amp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/block/thread-manager-for-amp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fthread-manager-for-amp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fthread-manager-for-amp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fthread-manager-for-amp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fthread-manager-for-amp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block","download_url":"https://codeload.github.com/block/thread-manager-for-amp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fthread-manager-for-amp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T01:03:10.068Z","updated_at":"2026-07-01T01:03:10.746Z","avatar_url":"https://github.com/block.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Thread Manager for Amp\n\nA local web UI for managing [Amp](https://ampcode.com) AI coding agent threads — monitor, interact with, and organize multiple concurrent agent sessions from your browser.\n\n## Screenshots\n\n### Thread List\n\nSortable, filterable table view with bulk operations, labels, and status tracking.\n\n![Thread list view](public/screenshots/thread-list.png)\n\n### Thread Detail\n\nConversation view with rich message rendering, syntax highlighting, and a minimap for navigation.\n\n![Thread detail view](public/screenshots/thread-detail.png)\n\n### Kanban Board\n\nOrganize threads across status columns — Active, Blocked, Paused, and Done.\n\n![Kanban board view](public/screenshots/kanban-board.png)\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** 24+ (needed to compile native modules like `better-sqlite3` and `node-pty`)\n- **pnpm** 10+ — install with `npm install -g pnpm`\n- **[Amp CLI](https://ampcode.com)** installed and authenticated (`amp` command available)\n\n### Install \u0026 Run\n\n```bash\npnpm install\npnpm dev\n```\n\nOpen http://localhost:5173\n\n## Why?\n\nWhen 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.\n\n## Features\n\n### 🖥️ Multi-Terminal Management\n\n- Run multiple Amp threads side-by-side with tabs, split views, and grid layouts\n- Real-time streaming of agent output via WebSocket\n- Rich message rendering with syntax highlighting for code and tool outputs\n- Conversation minimap for navigating long threads\n- Auto-reconnect on connection drops with output resumption\n\n### 📋 Thread Organization\n\n- **Table view** — sortable, filterable thread listing with bulk operations\n- **Card view** — detailed cards grouped by date\n- **Kanban view** — organize threads across status columns (Active, Blocked, Paused, Done)\n- Thread status tracking with blocker relationships between threads\n- Labels and linked issue URLs for organization\n- Handoff support to create continuation threads\n\n### 🔍 Discovery \u0026 Context\n\n- **Thread chains** — visualize parent/child handoff relationships\n- **Related threads** — find threads that touched the same files\n- **Git activity** — see commits, branches, and PRs correlated to each thread\n- **Source control** — view uncommitted changes per workspace with inline diffs\n- **Content search** — full-text search across all thread messages\n\n### 🛠️ Built-in Tools\n\n- **Shell terminal** — integrated xterm.js terminal sessions\n- **Command palette** (`⌘O`) — quick access to all actions\n- **Skills management** — list, add, and remove Amp skills\n- **MCP status** — view connected MCP servers\n- **Image viewer** — view images attached to or generated by threads\n\n### 🎨 Customization\n\n- **30+ theme presets** — Cyberpunk 2077, Dracula, Tokyo Night, Nord, Catppuccin, Gruvbox, and more\n- Adaptive theme system that derives a full UI from just 3 colors (bg, fg, accent)\n- Light and dark themes supported\n- Configurable layouts and view preferences\n- Notification sounds for completed tasks\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Frontend (React 19)                   │\n│  src/                                                    │\n│  ├── components/     # UI components                     │\n│  │   ├── terminal/   # WebSocket terminal + messages     │\n│  │   ├── ThreadList/ # Table view with bulk selection    │\n│  │   ├── sidebar/    # Workspace tree navigation         │\n│  │   └── Toolbar/    # Search, filters, view switching   │\n│  ├── hooks/          # Data fetching + state hooks       │\n│  ├── commands/       # Command palette registry          │\n│  └── lib/            # Theme system, utilities           │\n└─────────────────────────────────────────────────────────┘\n                           │\n┌─────────────────────────────────────────────────────────┐\n│               Shared (shared/)                           │\n│  types.ts, websocket.ts, validation.ts, cost.ts,         │\n│  utils.ts, constants.ts                                  │\n└─────────────────────────────────────────────────────────┘\n                           │\n                    HTTP + WebSocket\n                           │\n┌─────────────────────────────────────────────────────────┐\n│                 Backend (Node.js)                        │\n│  server/                                                 │\n│  ├── websocket.ts    # Per-thread session management     │\n│  ├── shell-websocket.ts  # Shell terminal PTY sessions   │\n│  ├── routes/         # REST API handlers                 │\n│  │   ├── threads.ts  # Thread CRUD + search + discovery  │\n│  │   ├── metadata.ts # Status, labels, blockers          │\n│  │   ├── git.ts      # Git status + diffs                │\n│  │   ├── skills.ts   # Amp skills + MCP management       │\n│  │   └── artifacts.ts # Notes + image storage            │\n│  └── lib/            # Core logic                        │\n│      ├── threadCrud.ts    # Thread CRUD operations        │\n│      ├── threadSearch.ts  # Search + related threads      │\n│      ├── threadExport.ts  # Markdown + image export       │\n│      ├── threadChain.ts   # Handoff chains                │\n│      ├── database.ts # SQLite for local metadata         │\n│      ├── amp-api.ts  # Amp internal API client           │\n│      ├── git.ts      # Git operations                    │\n│      └── git-activity.ts  # Commit/branch correlation    │\n└─────────────────────────────────────────────────────────┘\n                           │\n              ┌────────────┴────────────┐\n              │                         │\n     ~/.local/share/amp/        ~/.amp-thread-manager/\n     └── threads/*.json         ├── threads.db (SQLite)\n         (Amp thread data)      └── artifacts/\n```\n\n## Data Storage\n\n| Location                           | Purpose                                          |\n| ---------------------------------- | ------------------------------------------------ |\n| `~/.local/share/amp/threads/`      | Amp's thread JSON files (read by the server)     |\n| `~/.amp-thread-manager/threads.db` | Local SQLite for status, blockers, linked issues |\n| `~/.amp-thread-manager/artifacts/` | Saved images and notes per thread                |\n\n## Keyboard Shortcuts\n\n| Shortcut          | Action                           |\n| ----------------- | -------------------------------- |\n| `Ctrl/⌘+O`        | Command palette                  |\n| `Alt+N`           | New thread                       |\n| `Ctrl/⌘+R`        | Refresh threads / prompt history |\n| `Ctrl/⌘+W`        | Close current thread             |\n| `Ctrl/⌘+B`        | Toggle sidebar                   |\n| `Ctrl/⌘+H`        | Handoff current thread           |\n| `Ctrl+T`          | Open shell terminal              |\n| `Ctrl+M`          | Thread map                       |\n| `Alt+D`           | Toggle deep mode                 |\n| `Alt+L`           | Toggle layout                    |\n| `Alt+[` / `Alt+]` | Switch tabs                      |\n| `j/k` or `↓/↑`    | Navigate thread list             |\n| `Enter`           | Open focused thread              |\n| `x`               | Toggle selection                 |\n| `Esc`             | Close modal / clear focus        |\n\n## Scripts\n\n| Command           | Description                                     |\n| ----------------- | ----------------------------------------------- |\n| `pnpm dev`        | Start dev server (Vite frontend + Node backend) |\n| `pnpm build`      | Build for production                            |\n| `pnpm start`      | Build and serve production                      |\n| `pnpm check`      | Format check + lint + typecheck + build         |\n| `pnpm lint`       | ESLint                                          |\n| `pnpm typecheck`  | TypeScript type check                           |\n| `pnpm test`       | Run tests (Vitest)                              |\n| `pnpm test:watch` | Run tests in watch mode                         |\n\n## Configuration\n\n| Environment Variable | Default       | Description                  |\n| -------------------- | ------------- | ---------------------------- |\n| `PORT`               | `3001`        | Backend server port          |\n| `AMP_HOME`           | `$HOME`       | Base directory for Amp data  |\n| `AMP_BIN`            | auto-detected | Path to the `amp` CLI binary |\n\n## Security\n\nThis is a **local development tool**. The server binds to `localhost` only and is not accessible from other devices. See [SECURITY.md](SECURITY.md) for details.\n\n## Troubleshooting\n\n### Native module build errors (`better-sqlite3`, `node-pty`)\n\nThese packages require compilation. Make sure you have:\n\n- **macOS**: Xcode Command Line Tools (`xcode-select --install`)\n- **Linux**: `build-essential`, `python3`\n- Node.js 24+ (check with `node -v`)\n\nIf builds fail, try: `pnpm rebuild`\n\n### \"Amp CLI not found\"\n\nMake sure `amp` is in your PATH, or set `AMP_BIN` to the full path of the binary.\n\n### Port already in use\n\nSet a different port: `PORT=3002 pnpm dev`\n\n## Tech Stack\n\n- **Frontend**: React 19, TypeScript, Vite\n- **Backend**: Node.js with raw `http` module (no Express)\n- **Database**: SQLite via better-sqlite3\n- **WebSocket**: `ws` for real-time agent streaming\n- **Terminal**: xterm.js + node-pty for shell sessions\n- **Testing**: Vitest, Testing Library\n- **Styling**: CSS custom properties (no UI framework)\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fthread-manager-for-amp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock%2Fthread-manager-for-amp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fthread-manager-for-amp/lists"}