AGENTS.md · wavyrai/tmux-ide

Sections

1. Quick Start
2. .tmux-ide/workspace.yml Format
3. Architecture
4. Programmatic CLI Reference
5. Claude Skill
6. Contributor Workflow

First lines (shown under the repo's MIT license)

# tmux-ide

A visual, agent-aware IDE for ordinary tmux sessions. `.tmux-ide/workspace.yml`
is an optional declarative layout preset.

## Quick Start

```bash
tmux-ide              # Visual tmux app; configless by default
tmux-ide app [session] # Explicit app entry; optionally open a live session
tmux-ide init         # Scaffold .tmux-ide/workspace.yml (auto-detects stack)
tmux-ide inspect      # Show resolved config + live tmux state
tmux-ide stop         # Kill session
tmux-ide attach       # Reattach to running session
```

## .tmux-ide/workspace.yml Format

```yaml
version: 1
name: project-name # tmux session name

before: pnpm install # optional pre-launch hook

terminal:
  theme: # optional color overrides
    accent: colour75
    border: colour238
    bg: colour235
    fg: colour248
  rows:
    - size: 70% # row height percentage
      panes:
        - title: Claude 1 # pane border label
          command: claude # command to run (optional)
          size: 50% # pane width percentage (optional)
          dir: apps/web # per-pane working directory (optional)
          focus: true # initial focus (optional)
          env: # environment variables (optional)
            PORT: 3000

    - panes:
        - title: Dev Server
          command: pnpm dev
        - title: Shell
```

The project file is optional: the app discovers and manages ordinary live tmux
sessions without one. Legacy `ide.yml` files are still supported through a compatibility adapter. Use
`tmux-ide migrate --dry-run` to preview conversion and `tmux-ide migrate --write`
to create `.tmux-ide/workspace.yml`.

WorkspaceConfigV1 can declare `harnesses`, `agents`, and `missions` data, but
mission runtime wiring is future work. Do not add legacy `team`, pane
`role`/`task`, `sidebar`, or `orchestrator` fields to `.tmux-ide/workspace.yml`.

### Widget Pane Types

```yaml
panes:
  - title: Explorer
    type: explorer # explorer | changes | preview | config | sidebar
    target: src/ # optional target path
```

## Architecture

This TypeScript monorepo uses pnpm and Turbo. The terminal CLI/daemon is the
current npm release surface. GPUI is a separately distributed native macOS alpha;
the former web and Electron applications are retired. See `ARCHITECTURE.md` for import direction and
`eslint.config.js` for enforced package boundaries.

### CLI and daemon

- `bin/cli.ts` — CLI source; `scripts/build-cli.mjs` bundles it into `bin/cli.js`.
  Edit source rather than generated output.
- `packages/daemon/src/` — CLI operations (`launch.ts`, `init.ts`, `stop.ts`,
  `attach.ts`, `send.ts`, `config.ts`, `inspect.ts`) and daemon implementation.
- `packages/daemon/src/lib/canonical-daemon.ts` and
  `packages/daemon/src/lib/canonical-daemon-bootstrap.ts` — canonical ownership,
  discovery and bootstrap. Use the supported CLI rather than launching internal
  daemon modules directly.
- `packages/daemon/src/command-center/` — HTTP/WebSocket APIs and resource/action
  handlers; `server.ts` composes the server.
- `packages/daemon/src/terminal/` — tmux mirroring, canonical session runtime,
  terminal delivery and native-grid integration.
- `packages/daemon/src/schemas/` — daemon-local schemas and legacy config support.
- `packages/daemon/dist/` — compiled daemon output shipped with the root package.

### Contracts and shared packages

- `packages/contracts/` — shared wire schemas, resource vocabulary and visual tokens.
- `packages/core/` — renderer-neutral application models.
- `packages/daemon-client/` — client connections, resource replication and workspace clients.
- `packages/presentation/` — shared renderer-neutral presentation models.
- `packages/sdk/` — typed host-neutral SDK built from shared contracts.
- `packages/tmux-bridge/` — tmux bridge package.

### User interfaces

- `packages/daemon/src/tui/mirror/` — production OpenTUI/Solid Home and Terminals
  UI; `runtime/` owns application integration, `ui/` shared primitives,
  `workspace/` workspace presentation, and `features/` optional feature modules.
- `packages/daemon/src/widgets/` — explorer, changes, preview, config, setup and
  sidebar widgets; `resolve.ts` resolves entries and `lib/` holds shared helpers.
- `apps/tmux-gpui/` — native macOS alpha using the shared daemon contract and
  pinned Herdr GPUI source. Follow its README, upstream instructions and separate
  Rust/bridge/package gates; keep native assets out of the universal npm package.
- The former Solid/Electron and experimental React workspace clients are retired;
  shared qualification fixtures live in `scripts/lib/product-fixtures`.
- Do not add an external or closed-source canvas SDK to the core, TUI or web GUI.

### Development, native inputs and documentation

- `docs/guides/development-worktrees.md` — isolated `pnpm dev:instance` workflow;
  keep development daemons/tmux servers separate from production sessions.
- `patches/README.md` — dependency/native maintenance inventory and upgrade proofs.
- `native/tmux/provenance.json` — bundled tmux source and patch identity.
- `scripts/` — build, installed-package, live testdrive and qualification tools.
- `templates/` — workspace presets; `docs/content/docs/` — user-facing docs.
- `.github/workflows/ci.yml` — contributor CI; `release-binaries.yml` and
  `release.yml` in the same directory own runtime and npm publication.

Tests use package-specific Vitest, Bun and Node runners. Use the scripts in
`package.json` and the affected package instead of assuming one universal runner.

## Programmatic CLI Reference

All commands support `--json` for structured output.

### Read Commands

```bash
# Session status
tmux-ide status --json
# → { "session": "...", "running": true, "configExists": true, "panes": [...] }

# Validate config
tmux-ide validate --json
# → { "valid": true, "errors": [] }

# Detect project stack
tmux-ide detect --json
# → { "detected": { "packageManager": "pnpm", "frameworks": ["next", "convex"], ... }, "suggestedConfig": {...} }

# Dump config as JSON
tmux-ide config --json
# → { "name": "...", "rows": [...] }

# List sessions
tmux-ide ls --json
# → { "sessions": [{ "name": "...", "created": "...", "attached": true }] }

# System check
tmux-ide doctor --json
# → { "ok": true, "checks": [...] }

# Inspect resolved config + live tmux data
tmux-ide inspect --json
# → { "valid": true, "session": "...", "resolved": {...}, "tmux": {...} }