AGENTS.md

Commands

• Dev: pnpm dev - runs Vite frontend + Node server concurrently
• Typecheck: pnpm typecheck - checks frontend and server
• Lint: pnpm lint - ESLint
• Check: pnpm check - format check + lint + typecheck + build
• Build: pnpm build - builds frontend (Vite) and compiles TypeScript
• Test: pnpm test - runs Vitest test suite (frontend + server)

How It Works

This app is a local web UI for managing Amp threads. It is NOT part of Amp itself — it reads Amp's local data and calls its CLI/API to provide a dashboard experience.

Amp Integration (3 mechanisms)

1. Filesystem (read-only): The primary data source. Thread JSON files live at ~/.local/share/amp/threads/T-*.json. The server reads these directly to list threads, extract messages, calculate costs, and determine workspace/repo info. The ThreadFile shape is defined in server/lib/threadTypes.ts. There is no official Amp API documentation — these file formats were reverse-engineered.

2. Amp CLI (amp binary): Used for mutations — creating, renaming, archiving, and sharing threads. Located via AMP_BIN env var or ~/.local/bin/amp. Also spawned with --stream for live thread execution over WebSocket. See server/lib/utils.ts (runAmp) and server/websocket.ts.

3. Amp Internal API (ampcode.com/api/internal): Used for features not available via CLI — fetching/setting labels, remote thread deletion. Auth token read from ~/.local/share/amp/secrets.json, config from ~/.config/amp/settings.json. See server/lib/amp-api.ts. This is an undocumented internal API — methods were discovered by inspecting Amp's behavior.

Data Model & Where Logic Lives

Server is the authority for thread data. The client is a thin presentation layer.

• Server (server/lib/):

  • threadCrud.ts — reads thread JSON files, transforms raw data into the shared Thread type (title extraction, cost calculation, workspace/repo parsing, handoff relationships)
  • database.ts — SQLite DB at ~/.amp-thread-manager/threads.db for app-specific metadata not in Amp's files: thread status (active/parked/done/blocked), blockers, goals, linked issues, artifacts
  • amp-api.ts — client for Amp's internal API (labels)
  • workspaces.ts — discovers workspaces from thread files + ~/Development git repos
  • Route handlers in server/routes/ expose REST endpoints

• Client (src/):

  • hooks/useThreads.ts — fetches thread list from server API with polling (30s) and pagination
  • hooks/useThreadMetadata.ts — fetches app-specific metadata (statuses, blockers) from server
  • hooks/useThreadActions.ts — calls server endpoints for mutations (archive, delete, rename, etc.)
  • contexts/ThreadContext.tsx — combines threads + metadata + actions into a single React context
  • contexts/RunningThreadsContext.tsx — tracks live thread execution state via WebSocket
  • The client does no direct file/CLI access — all data flows through the server's REST API and WebSocket

Real-time Execution

When a user runs a thread from the UI, the server spawns amp --stream as a child process, pipes stdout/stderr through a WebSocket to the client, and parses the streaming JSON to track costs, tool usage, and images in real-time. Sessions survive brief WebSocket disconnects (30s grace period).

Directory Structure

• src/: React 19 frontend with Vite, context providers in contexts/, custom hooks in hooks/
• server/: Node.js backend using raw http module, route handlers in routes/, WebSocket handlers
  • server/lib/ thread logic is split: threadCrud.ts, threadSearch.ts, threadExport.ts, threadChain.ts
• shared/: Cross-boundary types, WebSocket protocol, validation (validation.ts), utilities (utils.ts, cost.ts, constants.ts)
• WebSocket for real-time updates; xterm.js + node-pty for shell terminals

Code Style

• ES modules, TypeScript strict mode
• React: functional components, lazy() for modals, useCallback for handlers passed as props
• Imports: external packages first, then local (hooks, components, utils)
• Server routes return true if handled, false to continue chain
• Modals: use BaseModal wrapper (provides role="dialog", focus trap, ESC-to-close)
• All inputs must have aria-label or associated <label>
• State: context providers in src/contexts/ (Settings, Modal, Thread, ThreadStatus, Unread)
• Shared code: stripAnsi(), generateId(), calculateCost(), constants live in shared/
• Tests: co-located *.test.ts files, Vitest workspace (frontend=jsdom, server=node)

.agents/knowledge/ Directory

Plans and temporary files can be stored in .agents/knowledge/ directories. Review them for context about ongoing work.