### Install and Run Documentation

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/README.md

Use these commands to install dependencies and start the local documentation development server. Open the local site at http://localhost:3000 after starting.

```bash
pnpm install --frozen-lockfile
```

```bash
pnpm docs
```

```bash
pnpm docs:build
```

--------------------------------

### Quick Start: Missions Workflow

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/agent-teams.mdx

A sequence of commands to quickly set up a mission, define its milestones, plan completion, and start the tmux-ide interface. This is useful for getting a new project started rapidly.

```bash
tmux-ide init --template missions
tmux-ide mission create "Build a todo API" -d "Plan, implement, validate, and summarize the result"	mux-ide milestone create "Foundation" --sequence 1
tmux-ide milestone create "Implementation" --sequence 2
tmux-ide milestone create "Validation" --sequence 3	mux-ide mission plan-complete
tmux-ide
```

--------------------------------

### Full ide.yml Configuration Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/configuration.mdx

A comprehensive example demonstrating the various options available in the ide.yml file, including session name, pre-session commands, row and pane definitions, and theme settings.

```yaml
name: my-app

before: pnpm install

rows:
  - size: 70%
    panes:
      - title: Claude 1 — feature
        command: claude
        size: 40%
      - title: Claude 2 — review
        command: claude
      - title: Claude 3 — explore
        command: claude

  - panes:
      - title: Next.js
        command: pnpm dev
        dir: apps/web
        env:
          PORT: 3000
      - title: Convex
        command: npx convex dev
      - title: Shell
        focus: true

theme:
  accent: colour75
  border: colour238
  bg: colour235
  fg: colour248

```

--------------------------------

### Install and Initialize tmux-ide

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/index.mdx

Install tmux-ide globally using npm. Use `tmux-ide init` to scaffold the `ide.yml` configuration file for Classic mode, or use the `--template missions` flag for Missions mode.

```bash
npm i -g tmux-ide

# Classic mode
tmux-ide init           # scaffold ide.yml
tmux-ide                # launch

# Missions mode
tmux-ide init --template missions
tmux-ide mission create "Build auth system" -d "JWT + refresh tokens"
tmux-ide                # → agents, dashboard at localhost:6060, autonomous
```

--------------------------------

### tmux-ide Quick Start Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/README.md

Common commands for initializing, launching, stopping, and managing tmux-ide sessions.

```bash
tmux-ide init         # Scaffold ide.yml (auto-detects your stack)
```

```bash
tmux-ide              # Launch the IDE
```

```bash
tmux-ide stop         # Kill the session
```

```bash
tmux-ide restart      # Stop and relaunch
```

```bash
tmux-ide attach       # Reattach to a running session
```

```bash
tmux-ide inspect      # Inspect effective config + runtime state
```

--------------------------------

### Classic Agent Team Configuration Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/agent-teams.mdx

An example `ide.yml` configuration defining a team with a lead pane and two teammate panes for frontend and backend development. It also includes panes for a development server and a shell.

```yaml
name: my-app

team:
  name: my-app

rows:
  - size: 70%
    panes:
      - title: Lead
        command: claude
        role: lead
        focus: true
      - title: Frontend
        command: claude
        role: teammate
        task: "Work on React components and pages"
      - title: Backend
        command: claude
        role: teammate
        task: "Work on API routes and server logic"

  - panes:
      - title: Next.js
        command: pnpm dev
      - title: Shell
```

--------------------------------

### Recommended Upgrade Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/release-1-2-0.mdx

Provides commands for installing the latest version and performing upgrade checks.

```bash
npm install -g tmux-ide@latest
tmux-ide doctor --json
tmux-ide validate --json
tmux-ide restart          # to pick up the new status bar and indicators
```

--------------------------------

### Architecture Context Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/knowledge-library.mdx

Example content for architecture.md, defining the project's monorepo structure, tech stack, and key patterns. Keep critical information within the first 500 characters for dispatch prompts.

```markdown
# Architecture

Monorepo managed with pnpm workspaces and Turborepo.

- apps/web — Next.js 15 frontend (App Router, RSC)
- apps/api — Hono REST API on Cloudflare Workers
- packages/db — Drizzle ORM + Postgres migrations
- packages/ui — Shared React component library

Key patterns:

- Server components by default, "use client" only when needed
- All API routes return typed responses via shared zod schemas
- Database migrations live in packages/db/migrations/

```

--------------------------------

### Install tmux-ide Globally

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Install the tmux-ide command-line tool globally using npm. This makes the `tmux-ide` command available system-wide.

```bash
npm i -g tmux-ide
```

--------------------------------

### Example ide.yml Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/README.md

A sample ide.yml file demonstrating session naming, pre-launch hooks, row and pane definitions with commands, directories, environment variables, and theme overrides.

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

before: pnpm install # optional pre-launch hook

rows:
  - size: 70% # row height percentage
    panes:
      - title: Editor # pane border label
        command: vim # command to run (optional)
        size: 60% # pane width percentage (optional)
        dir: apps/web # per-pane working directory (optional)
        focus: true # initial focus (optional)
        env: # environment variables (optional)
          PORT: 3000
      - title: Shell

  - panes:
      - title: Dev Server
        command: pnpm dev
      - title: Tests
        command: pnpm test

theme: # optional color overrides
  accent: colour75
  border: colour238
  bg: colour235
  fg: colour248

```

--------------------------------

### Tmux-IDE Configuration File Example (YAML)

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

A sample ide.yml file demonstrating the structure for configuring session name, pre-launch hooks, agent teams, rows, panes, and theme.

```yaml
name: project-name
before: pnpm install # optional pre-launch hook
team: # optional agent team config
  name: my-team
rows:
  - size: 70%
    panes:
      - title: Lead
        command: claude
        role: lead # optional layout metadata: "lead" or "teammate"
        focus: true
      - title: Teammate 1
        command: claude
        role: teammate
        task: "Work on frontend" # suggested task text for your prompts
      - title: Teammate 2
        command: claude
        role: teammate
        task: "Work on backend"
  - panes:
      - title: Dev Server
        command: pnpm dev
        dir: apps/web # per-pane working directory
        env:
          PORT: 3000
      - title: Shell
theme:
  accent: colour75
  border: colour238
```

--------------------------------

### Skill File Structure

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/configuration.mdx

Example of a skill definition file using YAML frontmatter for metadata and a body for instructions.

```markdown
---
name: frontend
specialties: [react, css, typescript]
role: teammate
description: Frontend component specialist
---

You are a frontend developer. Focus on React components and CSS.
```

--------------------------------

### Skill Definition Example (Frontend)

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/knowledge-library.mdx

Example of a skill file defining agent persona, specialties, role, and system prompt. This markdown file uses YAML frontmatter for metadata.

```yaml
---
name: frontend
specialties: [react, css, typescript]
role: teammate
description: Frontend component specialist
---

You are a frontend developer. Focus on React components, styling,
and client-side state management. Run `pnpm dev` in apps/web to
preview changes. Always check responsive behavior.

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/wavyrai/tmux-ide/blob/main/CONTRIBUTING.md

Installs project dependencies using pnpm. Ensure Node.js 18+ and pnpm 10+ are installed.

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### Start Command Center Server

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Launch the Command Center server, which includes REST API, SSE, and WebSocket capabilities. An optional port can be specified.

```bash
tmux-ide command-center [--port 4000]   # Start REST API + SSE + WebSocket server
```

--------------------------------

### Daemon Entry Point

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Shows the command to start the unified background process (daemon) for tmux-ide, which includes pane monitoring, orchestration, and an HTTP server.

```bash
node dist/lib/daemon.js <session> [port]
```

--------------------------------

### Status Bar Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/release-1-2-0.mdx

Illustrates the two-line status bar format with clickable pane tabs and active pane highlighting.

```tmux
Line 0:  MY-PROJECT IDE            ●            14:30 │ Mar 17
Line 1:  Claude 1 │ Claude 2 │ Dev Server │ Shell
         ^^^^^^^^ highlighted = active pane
```

--------------------------------

### Contributor workflow commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Common commands for contributors to install dependencies, lint, format, and test the project.

```bash
pnpm install --frozen-lockfile
```

```bash
pnpm lint
```

```bash
pnpm format:check
```

```bash
pnpm test
```

```bash
pnpm pack:check
```

--------------------------------

### Initialize agent team template

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Scaffolds a new project with an agent team template. This is the starting point for setting up coordinated agent workflows.

```bash
tmux-ide init --template agent-team
```

--------------------------------

### Launch or Re-launch IDE

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Start the tmux-ide application. If a session is already running, it will re-launch it.

```bash
tmux-ide              # Launch (or re-launch) IDE
```

--------------------------------

### Minimal Recommended Tmux Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/tips.mdx

A basic ~/.tmux.conf setup including mouse support, prefix-free pane switching, window/pane indexing, and increased scrollback buffer.

```bash
# Mouse support
set -g mouse on

# Option+arrow pane switching (no prefix needed)
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Start window numbering at 1
set -g base-index 1
setw -g pane-base-index 1

# Increase scrollback
set -g history-limit 10000
```

--------------------------------

### Launch tmux-ide Session

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Start a tmux session based on your `ide.yml` configuration. This command launches tmux with the defined panes and commands.

```bash
tmux-ide
```

--------------------------------

### Assertion Design Examples Across Domains

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/validation-contracts.mdx

Illustrates how to design specific and testable assertions for different domains like Auth, API, UI, and Data.

```markdown
## Auth

**VAL-AUTH-001**: POST /auth/login with valid credentials returns 200 and a JWT
**VAL-AUTH-002**: POST /auth/login with invalid credentials returns 401

## API

**VAL-API-001**: GET /api/users requires Authorization header; omitting it returns 401
**VAL-API-002**: GET /api/users?limit=5 returns at most 5 records

## UI

**VAL-UI-001**: Login form shows inline error on invalid credentials without page reload
**VAL-UI-002**: Dashboard renders within 2 seconds on a cold load

## Data

**VAL-DATA-001**: Creating a user with duplicate email returns 409 Conflict
**VAL-DATA-002**: Soft-deleted users are excluded from list queries by default
```

--------------------------------

### Tmux IDE CLI Usage

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Examples of common Tmux IDE command-line interface commands for managing missions, goals, and tasks.

```APIDOC
## Tmux IDE CLI Usage

### Description
Examples of common Tmux IDE command-line interface commands for managing missions, goals, and tasks.

### Usage Flow
```bash
tmux-ide mission set "Ship v2" -d "description"
tmux-ide goal create "Auth system" -p 1 --acceptance "JWT + refresh tokens"
tmux-ide task create "Implement JWT" -g 01 -p 1 -d "detailed description"
tmux-ide task create "Add tests" -g 01 -p 2 --depends "001"
tmux-ide   # Launch — orchestrator auto-dispatches tasks to agents
tmux-ide orch   # Monitor progress
```
```

--------------------------------

### Tmux-IDE Status Bar Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Illustrates the two-line status bar format in tmux-ide, showing session information, pane status indicators, and time.

```text
Line 0:  MY-PROJECT IDE            ●            14:30 │ Mar 17
Line 1:  ⏺ Claude 1 │ ● Claude 2 │ ⏺ Dev Server │ Shell
```

--------------------------------

### Command Center

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Starts the Command Center server, which provides a REST API, SSE event streaming, and WebSocket terminal mirroring.

```APIDOC
## Command Center

### `tmux-ide command-center [--port <port_number>]`

**Description**: Starts the Command Center server, exposing a REST API, SSE event streaming, and WebSocket terminal mirroring. The default port is 6060.

**Example**: `tmux-ide command-center --port 6060`
```

--------------------------------

### Write Detected Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Write the detected project configuration to a file. This is typically used after running `tmux-ide detect` to initialize a project's tmux-ide setup.

```bash
tmux-ide detect --write
```

--------------------------------

### Architecture Context Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/missions-workflow.mdx

The `architecture.md` file provides essential context about the project's stack, key paths, and conventions. This information is injected into agent dispatches to ensure they understand the codebase.

```markdown
# Architecture

## Stack

- Next.js 14 (App Router)
- Drizzle ORM + PostgreSQL
- JWT via jose library

## Key Paths

- `src/app/api/auth/` — auth route handlers
- `src/lib/auth/` — token creation, validation, refresh logic
- `src/middleware.ts` — route protection

## Conventions

- All API routes return `{ data }` or `{ error }` JSON envelopes
- Tests live next to source files as `*.test.ts`
```

--------------------------------

### Tmux-IDE Read Commands with JSON Output

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Demonstrates how to use various tmux-ide commands with the --json flag to get structured output for programmatic access.

```bash
tmux-ide status --json      # Session status
```

```bash
tmux-ide validate --json    # Validate config
```

```bash
tmux-ide detect --json      # Detect project stack
```

```bash
tmux-ide config --json      # Dump config as JSON
```

```bash
tmux-ide ls --json          # List sessions
```

```bash
tmux-ide doctor --json      # System health check
```

--------------------------------

### Basic tmux-ide Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

An example `ide.yml` file defining a tmux workspace with two rows. The first row has two panes titled 'Claude 1' and 'Claude 2', each running the 'claude' command. The second row has two panes for a 'Dev Server' and a 'Shell'.

```yaml
name: my-project

rows:
  - size: 70%
    panes:
      - title: Claude 1
        command: claude
      - title: Claude 2
        command: claude

  - panes:
      - title: Dev Server
      - title: Shell
```

--------------------------------

### Validation Contract Format Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/validation-contracts.mdx

Assertions are defined in Markdown, with each assertion starting with a bold ID followed by a colon and the claim. Assertions can be organized under headings.

```markdown
# Validation Contract

## Authentication

**VAL-AUTH-001**: Login endpoint returns a signed JWT on valid credentials
**VAL-AUTH-002**: Invalid credentials return 401 with a structured error body
**VAL-AUTH-003**: Expired tokens are rejected with 401 and a `token_expired` code
**VAL-AUTH-004**: Refresh token endpoint issues a new access token

## API

**VAL-API-001**: All endpoints require a valid Bearer token except /health
**VAL-API-002**: Rate limiter returns 429 after 100 requests per minute per key

## Data

**VAL-DATA-001**: User creation persists to the database and is retrievable by ID
**VAL-DATA-002**: Deleting a user cascades to dependent records
```

--------------------------------

### Before Command Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/configuration.mdx

An optional shell command to execute before the tmux session is created. Useful for tasks like installing dependencies or running setup scripts.

```yaml
before: pnpm install

```

--------------------------------

### Smoke Test Global Install

Source: https://github.com/wavyrai/tmux-ide/blob/main/RELEASE.md

Verify the installation and basic functionality of the globally installed package on a clean machine. This ensures the package can be installed and used by end-users.

```bash
npm install -g tmux-ide
```

--------------------------------

### Scaffold Initial Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Generate a basic configuration file for a new project, automatically detecting the stack.

```bash
tmux-ide init         # Scaffold config (auto-detects stack)
```

--------------------------------

### Install Globally for Hook Verification

Source: https://github.com/wavyrai/tmux-ide/blob/main/RELEASE.md

Install the package globally to test the global install hook on a machine with Claude Code configured. This verifies the integration with the Claude Code environment.

```bash
npm install -g .
```

--------------------------------

### Initialize ide.yml

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Scaffolds a new 'ide.yml' file in the current directory, auto-detecting the project stack to select an appropriate template. It will refuse to overwrite an existing 'ide.yml'.

```bash
cd ~/Developer/my-project
tmux-ide init
# → Detected next + convex. Created ide.yml for "my-project".
```

```bash
tmux-ide init --template nextjs
```

--------------------------------

### Main Development Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/CONTRIBUTING.md

Common commands for running tests, building documentation, and checking the project.

```bash
pnpm test
```

```bash
pnpm docs:build
```

```bash
pnpm check
```

--------------------------------

### Validation Contract Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/agent-teams.mdx

An example of a validation contract stored in a markdown file, defining specific assertions with IDs that tasks can claim to fulfill.

```md
**VAL-AUTH-001**: Login endpoint returns JWT on valid credentials
**VAL-AUTH-002**: Invalid credentials return 401
```

--------------------------------

### Learnings Accumulation Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/knowledge-library.mdx

Example of accumulated content in learnings.md, showing discoveries and solutions from completed tasks with timestamps. This file is auto-appended by the orchestrator.

```markdown
## Task 003 — Implement JWT auth (2025-01-15)

- jose library requires Node 18+ — use jsonwebtoken for broader compat
- Refresh tokens stored in httpOnly cookies, not localStorage
- CORS config in wrangler.toml must include credentials: true

## Task 007 — Add rate limiting (2025-01-16)

- Cloudflare Workers have no native rate limiting — use Durable Objects
- Rate limit state persists via DO storage, not KV (too slow for counters)

```

--------------------------------

### Scaffold ide.yml with tmux-ide init

Source: https://context7.com/wavyrai/tmux-ide/llms.txt

Initialize a new project with a basic `ide.yml` configuration file. The tool auto-detects the project stack and suggests a suitable layout. You can also specify a template.

```bash
# Auto-detect and scaffold
cd ~/Developer/my-project
tmux-ide init
# → Detected next + convex. Created ide.yml for "my-project".

# Use a specific template
tmux-ide init --template nextjs
tmux-ide init --template agent-team
tmux-ide init --template missions   # full autonomous orchestration scaffold
```

--------------------------------

### Run tmux-ide with npx

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Execute tmux-ide directly using npx without a global installation. This is useful for trying out the tool or for environments where global installations are restricted.

```bash
npx tmux-ide
```

--------------------------------

### Tmux-IDE Best Practices for Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Highlights best practices for using tmux-ide, including programmatic access with JSON, validation, pane layout, and debugging.

```bash
--json
```

```bash
validate --json
```

```bash
detect --json
```

```bash
--verbose
```

```bash
TMUX_IDE_DEBUG=1
```

--------------------------------

### Initialize tmux-ide Workspace

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Navigate to your project directory and run `tmux-ide init` to scaffold a basic `ide.yml` configuration file. This command sets up the initial configuration for your tmux session.

```bash
cd ~/Developer/my-project
tmux-ide init
```

--------------------------------

### Create a project goal

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Creates a new goal for the project with a title, priority, and acceptance criteria.

```bash
tmux-ide goal create "title" --priority N --acceptance "criteria"
```

--------------------------------

### Project Directory Structure

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/knowledge-library.mdx

Illustrates the directory structure for the knowledge library and agent skills within a project.

```bash
.tmux-ide/
  library/
    architecture.md        # project design context
    learnings.md           # auto-appended after each task
  skills/
    frontend.md            # skill definitions (per-role)
    backend.md
    reviewer.md
    researcher.md
    general-worker.md
AGENTS.md                  # project boundaries

```

--------------------------------

### Validator Configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/validation-contracts.mdx

Example configuration for the validator agent pane within the missions template.

```yaml
panes:
  - title: Validator
    command: claude
    role: validator
    skill: reviewer
```

--------------------------------

### List project goals

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Lists all project goals. Use --json for programmatic access.

```bash
tmux-ide goal list [--json]
```

--------------------------------

### Attach to Tmux IDE Session

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Reattaches to a running tmux-ide session. If the session is not running, it suggests starting it with 'tmux-ide'.

```bash
tmux-ide attach
```

--------------------------------

### tmux-ide init with Template

Source: https://github.com/wavyrai/tmux-ide/blob/main/README.md

Initialize a new ide.yml configuration using a predefined template. Available templates include default, nextjs, convex, vite, python, go, and various agent team configurations.

```bash
tmux-ide init --template <name>
```

--------------------------------

### Verbose Debugging Output

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/release-1-2-0.mdx

Shows example output when running tmux-ide with the --verbose flag, tracing tmux commands.

```bash
$ tmux-ide --verbose
  [tmux] has-session -t my-project
  [tmux] new-session -d -P -F #{pane_id} -s my-project ...
  [tmux] set-option -t my-project mouse on
  ...
```

--------------------------------

### Initialize Missions Layout

Source: https://context7.com/wavyrai/tmux-ide/llms.txt

Scaffolds the necessary directory structure and configuration files for a new mission, including `ide.yml`, task validation contracts, skill definitions, and knowledge library placeholders.

```bash
# 1. Scaffold missions layout	mux-ide init --template missions
# Creates: ide.yml, .tasks/validation-contract.md, .tmux-ide/skills/, 
#          .tmux-ide/library/, AGENTS.md
```

--------------------------------

### Launch or Restart tmux-ide

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Launch tmux-ide for the first time or restart it to apply configuration changes. This command applies the validated configuration.

```bash
tmux-ide
```

```bash
tmux-ide restart
```

--------------------------------

### Scaffold Configuration with Template

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Generate a configuration file using a specific predefined template, such as 'nextjs'.

```bash
tmux-ide init --template nextjs  # Use specific template
```

--------------------------------

### Run Main Project Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/contributing.mdx

Executes common project commands for testing, type checking, building, and documentation generation. Run these from the repository root.

```bash
pnpm test
pnpm typecheck
pnpm build
pnpm docs:build
pnpm pack:check
pnpm check
```

--------------------------------

### Command Center

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Starts the Command Center server, which provides REST API, SSE, and WebSocket interfaces for interacting with Tmux IDE.

```APIDOC
## Command Center

### Start server

Starts the Command Center server, which includes a REST API, Server-Sent Events (SSE) for event streaming, and a WebSocket server for terminal mirroring. You can specify the port.

```bash
tmux-ide command-center [--port 4000]
```
```

--------------------------------

### Create a Mission

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Programmatically create a new mission with a title and description. The mission will be initialized in the 'planning' state.

```bash
tmux-ide mission create "Ship auth v2" -d "JWT login, refresh, validation, and metrics"
```

--------------------------------

### Initialize Missions Mode

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/agent-teams.mdx

Use this command to initialize tmux-ide with the missions template, setting up specialized agents for frontend, backend, validation, and research. It also creates a new mission with a description.

```bash
tmux-ide init --template missions
tmux-ide mission create "Ship auth v2" -d "JWT login, refresh, and validation coverage"
tmux-ide
```

--------------------------------

### Researcher Trigger Examples

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

The researcher can be triggered manually for various events like `mission_start`, `milestone_complete`, `periodic`, `retry_cluster`, or other configured trigger names.

```text
The researcher can be triggered manually for `mission_start`, `milestone_complete`, `periodic`, `retry_cluster`, or other configured trigger names.
```

--------------------------------

### Create, List, Show, and Update Milestones

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Use these commands for programmatic management of project milestones. Always include `--json` for machine-readable output.

```bash
tmux-ide milestone create "Foundation" --sequence 1 --json
```

```bash
tmux-ide milestone list --json
```

```bash
tmux-ide milestone show M1 --json
```

```bash
tmux-ide milestone update M1 --status done --json
```

--------------------------------

### tmux-ide CLI Usage Flow

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Demonstrates the typical command-line workflow for setting up a mission, creating goals and tasks, and initiating the orchestrator for auto-dispatch.

```bash
tmux-ide mission set "Ship v2" -d "description"
tmux-ide goal create "Auth system" -p 1 --acceptance "JWT + refresh tokens"
tmux-ide task create "Implement JWT" -g 01 -p 1 -d "detailed description"
tmux-ide task create "Add tests" -g 01 -p 2 --depends "001"
tmux-ide   # Launch — orchestrator auto-dispatches tasks to agents
tmux-ide orch   # Monitor progress
```

--------------------------------

### Get Mission Status

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Retrieve the status of the current mission, including validation summaries, in JSON format. This is useful for monitoring mission progress.

```bash
tmux-ide mission status --json
```

--------------------------------

### Get Structured Output with --json

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Add the --json flag to any command to receive structured output, useful for scripting and automation.

```bash
tmux-ide status --json
```

```bash
tmux-ide inspect --json
```

```bash
tmux-ide validate --json
```

```bash
tmux-ide detect --json
```

```bash
tmux-ide config --json
```

```bash
tmux-ide ls --json
```

```bash
tmux-ide doctor --json
```

--------------------------------

### Launch tmux-ide CLI Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Provides essential commands for interacting with the tmux-ide CLI. Use `tmux-ide` to launch, `init` to scaffold configuration, `inspect` to view state, `stop` to terminate, and `attach` to re-enter a session.

```bash
tmux-ide              # Launch IDE from ide.yml
tmux-ide init         # Scaffold ide.yml (auto-detects stack)
tmux-ide inspect      # Show resolved config + live tmux state
tmux-ide stop         # Kill session	mux-ide attach       # Reattach to running session
```

--------------------------------

### Tmux IDE Initialization Command

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/knowledge-library.mdx

Initializes the Tmux IDE project structure, creating the `.tmux-ide/` directory and its subdirectories for skills and libraries.

```bash
tmux-ide init
```

--------------------------------

### Dump Configuration (JSON)

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Output the entire current configuration as a JSON object. Use --json for structured output.

```bash
tmux-ide config --json
# → { "name": "...", "rows": [...] }
```

--------------------------------

### Validation Contract Example

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/missions-workflow.mdx

The validation contract defines concrete, testable assertions for a mission. Each assertion has a unique ID that tasks can reference to indicate fulfillment.

```markdown
# Validation Contract — Auth v2

## Authentication

- **VAL-AUTH-001**: POST /api/auth/login returns a JWT on valid credentials
- **VAL-AUTH-002**: POST /api/auth/login returns 401 on invalid credentials
- **VAL-AUTH-003**: POST /api/auth/refresh returns a new access token given a valid refresh token
- **VAL-AUTH-004**: Protected routes return 403 when the JWT is expired

## Test Coverage

- **VAL-TEST-001**: Unit tests cover all auth service functions with >90% line coverage
- **VAL-TEST-002**: Integration tests exercise the full login-refresh-logout flow
```

--------------------------------

### Create a Mission

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Define a new mission with a title and description. This command is part of the missions mode setup, allowing you to specify the goals for your autonomous agents.

```bash
tmux-ide mission create "Build auth system" -d "JWT + refresh tokens"
```

--------------------------------

### Contributor Workflow Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/README.md

Commands for developers working on the tmux-ide project, including installation, testing, documentation building, and pre-push checks within a pnpm workspace.

```bash
pnpm install
```

```bash
pnpm test
```

```bash
pnpm docs:build
```

```bash
pnpm check
```

```bash
pnpm pack:check
```

--------------------------------

### View Session and Performance Metrics

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Access telemetry for session, task, agent, and mission performance. Includes summary, agent utilization, activity timeline, bottleneck analysis, and historical comparisons.

```bash
tmux-ide metrics [--json]              # session summary
```

```bash
tmux-ide metrics agents [--json]       # per-agent utilization table
```

```bash
tmux-ide metrics timeline [--json]     # activity timeline (5-min samples)
```

```bash
tmux-ide metrics eval [--json]         # bottleneck milestones, high-retry agents
```

```bash
tmux-ide metrics history [--json]      # cross-mission comparison
```

--------------------------------

### Launch tmux-ide CLI Commands

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Provides essential commands for launching, initializing, inspecting, stopping, and reattaching to tmux-ide sessions.

```bash
tmux-ide              # Launch IDE from ide.yml
tmux-ide init         # Scaffold ide.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
```

--------------------------------

### Configure Skill-Based Dispatch

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/agent-teams.mdx

Example YAML configuration for a teammate pane, specifying its role, specialty, and skill. This allows the orchestrator to dispatch tasks to the most appropriate agent.

```yaml
panes:
  - title: Frontend Agent
    command: claude
    role: teammate
    specialty: frontend
    skill: frontend
```

--------------------------------

### Manage Tasks with tmux-ide

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Use these commands to create, list, show, update, claim, complete, and delete tasks. Dependencies and priorities can be specified during task creation.

```bash
tmux-ide task create "title" --goal NN --priority N --assign "Agent" --tags "a,b" --depends "001,002"
```

```bash
tmux-ide task list [--status todo --goal NN] [--json]
```

```bash
tmux-ide task show <id> [--json]                    # Full mission→goal→task context
```

```bash
tmux-ide task update <id> --status review --proof '{"tests":{"passed":10,"total":10}}'
```

```bash
tmux-ide task claim <id> --assign "Agent Name"      # Claim and start a task
```

```bash
tmux-ide task done <id> --proof "description"       # Mark task complete with proof
```

```bash
tmux-ide task delete <id>
```

--------------------------------

### Auto-detect project and configuration

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Automatically detects the project structure and suggests a configuration. Use --write to automatically create the ide.yml file.

```bash
tmux-ide detect --json
```

```bash
tmux-ide detect --write
```

--------------------------------

### Create and Manage Missions with tmux-ide

Source: https://context7.com/wavyrai/tmux-ide/llms.txt

Use these commands to create, set, and manage the lifecycle of missions. Missions progress through planning, active, validating, and complete states. Monitor mission status and details using the status and show commands.

```bash
# Create mission in planning state	mux-ide mission create "Build auth system" -d "JWT + refresh tokens"
```

```bash
# Alternatively, set a mission directly to active	mux-ide mission set "Auth v2" --description "JWT login, token refresh, route protection"
```

```bash
# Transition from planning → active (activates first milestone, starts dispatch)	mux-ide mission plan-complete
```

```bash
# Monitor	mux-ide mission status --json    # milestones, tasks, validation progress
```

```bash
tmux-ide mission show --json      # full mission detail
```

```bash
# Clear	mux-ide mission clear
```

--------------------------------

### Check System Requirements

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Verifies that your system meets all the necessary requirements for Tmux IDE, including tmux installation and version, Node.js version, and terminal color support.

```bash
tmux-ide doctor
```

--------------------------------

### Present Layout Options with ASCII Diagrams

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Visualize different tmux pane arrangements using ASCII diagrams to help users choose a layout. These options can be adapted based on the detected project stack.

```bash
```
┌─────────────────┬─────────────────┐
│                 │                 │
│    Claude 1     │    Claude 2     │  70%
│                 │                 │
├────────┬────────┴────────┬────────┤
│Dev Srv │  Tests  │ Shell │        │  30%
└────────┴─────────┴───────┘────────┘
```
```

```bash
```
┌───────────┬───────────┬───────────┐
│           │           │           │
│ Claude 1  │ Claude 2  │ Claude 3  │  70%
│           │           │           │
├───────────┴─────┬─────┴───────────┤
│    Dev Server    │     Shell       │  30%
└─────────────────┴─────────────────┘
```
```

```bash
```
┌─────────────────────────────────────┐
│             Claude                  │  60%
├──────────┬──────────┬──────────────┤
│ Dev Srv  │  Tests   │    Shell     │  40%
└──────────┴──────────┴──────────────┘
```
```

--------------------------------

### Mark project goal as complete

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Marks a project goal as complete.

```bash
tmux-ide goal done <id>
```

--------------------------------

### Detect Project Stack (JSON)

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Automatically detect the project's package manager and frameworks. Provides suggested configuration based on detection. Use --json for structured output.

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

--------------------------------

### Set Configuration Values by Dot Path

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/programmatic.mdx

Modify configuration settings using dot notation to specify the exact path to a value. This is useful for precise adjustments to your tmux-ide setup.

```bash
tmux-ide config set name "my-app"
```

```bash
tmux-ide config set rows.0.size "70%"
```

```bash
tmux-ide config set rows.1.panes.0.command "npm run dev"
```

```bash
tmux-ide config set rows.0.panes.1.title "Claude 2 — review"
```

--------------------------------

### Assign task hints to teammate panes

Source: https://github.com/wavyrai/tmux-ide/blob/main/skill/SKILL.md

Sets specific task descriptions for individual teammate panes within an agent team configuration. This helps guide the agents' focus.

```bash
tmux-ide config set rows.0.panes.1.task "Work on frontend components"
```

```bash
tmux-ide config set rows.0.panes.2.task "Work on API routes"
```

--------------------------------

### Documentation Build Command

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Command to build the project's documentation. This is typically used before deploying or publishing documentation updates.

```bash
pnpm docs:build
```

--------------------------------

### Set Configuration Value

Source: https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md

Modify a specific configuration value using dot notation for nested properties. Examples show setting the session name, row size, and pane command.

```bash
tmux-ide config set name "my-app"	mux-ide config set rows.0.size "70%"	mux-ide config set rows.1.panes.0.command "npm run dev"
```

--------------------------------

### Provide Task Completion Proof

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

The `--proof` flag for task completion accepts either plain text descriptions or structured JSON objects.

```bash
tmux-ide task done 003 --proof "All tests passing"
```

```bash
tmux-ide task done 003 --proof '{"tests":{"passed":10,"total":10},"notes":"CI green"}'
```

--------------------------------

### Get IDE Session Status

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Displays the status of the current IDE session, including session name, running state, config existence, and pane details. Can output in JSON format for programmatic use.

```bash
tmux-ide status
```

```bash
tmux-ide status --json
```

--------------------------------

### Manually Register Claude Code Skill

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/getting-started.mdx

Manually register the tmux-ide skill with Claude Code if you installed tmux-ide via `npx` or if automatic registration failed. This involves copying the `SKILL.md` file to the appropriate directory.

```bash
mkdir -p ~/.claude/skills/tmux-ide
cp "$(npm root -g)/tmux-ide/skill/SKILL.md" ~/.claude/skills/tmux-ide/
```

--------------------------------

### Inspect Project Configuration and State

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/commands.mdx

Shows the effective project configuration and current runtime state, including resolved config path, session name, validation status, focus target, and live tmux pane state. Can output in JSON format.

```bash
tmux-ide inspect
```

```bash
tmux-ide inspect --json
```

--------------------------------

### Tmux IDE Command Center Server

Source: https://github.com/wavyrai/tmux-ide/blob/main/CLAUDE.md

Start the Tmux IDE Command Center, which provides a REST API, Server-Sent Events (SSE) for event streaming, and WebSocket support for terminal mirroring. The port can be specified using the `--port` flag.

```bash
tmux-ide command-center [--port 6060]   # Start REST API + SSE + WebSocket server
```

--------------------------------

### Manage Agent Skills

Source: https://github.com/wavyrai/tmux-ide/blob/main/docs/content/docs/release-2-0-0.mdx

Use these commands to list available skills, scaffold new skill definitions from a template, and validate references between agent panes and their defined skills.

```bash
tmux-ide skill list          # show available skills	mux-ide skill create myskill # scaffold from template	mux-ide skill validate       # check pane→skill references
```