> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codewire.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What is Codewire CLI? Installation, operating modes, and quick start.

# Codewire CLI

Codewire CLI (`cw`) is a persistent process server for AI coding agents. Like tmux, but purpose-built for long-running LLM processes — native terminal scrolling, copy/paste, and no weird key chords. Tags, subscriptions, and wait provide LLM orchestration primitives out of the box.

## Operating Modes

The CLI has two modes:

### Standalone mode

Sessions, relay, orchestration, and messaging — no Codewire account required. Everything runs locally or via a self-hosted relay.

```bash theme={null}
cw run worker --tag build -- claude -p "refactor the auth module"
cw attach 1
cw wait --tag worker --condition all
```

### Platform mode

Integrates with codewire.sh for workspace management, org commands, billing, and remote access. Requires a Codewire account.

```bash theme={null}
cw setup                                    # interactive wizard
cw launch github.com/your-org/your-repo     # create workspace from repo
cw workspaces                               # list workspaces
cw run -- claude "fix the tests"            # SSH into workspace + run session
```

See [Platform commands](/cli/platform) for the full reference.

## Key Features

* **Persistent sessions** — Processes run in PTYs that survive disconnects
* **Tags and orchestration** — Label sessions, subscribe to events, wait for completion
* **Agent messaging** — Named agents exchange messages and coordinate with request/reply
* **Remote access** — SSH gateway via relay, access any machine from anywhere
* **MCP integration** — AI agents control sessions programmatically
* **Shared KV store** — Cross-node key-value coordination in relay mode
* **Platform integration** — Manage workspaces, orgs, and resources from the terminal

## Installation

### Homebrew

Supported on macOS (aarch64, x86\_64) and Linux (aarch64, x86\_64).

```bash theme={null}
brew install codewiresh/codewire/codewire
```

### Install Script

Downloads the binary, verifies GPG signature and SHA256 checksum.

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/codewiresh/codewire/main/install.sh | bash
```

Options: `--version VERSION`, `--prefix DIR`, `--verbose`

### Build from Source

```bash theme={null}
go build -o cw ./cmd/cw
sudo mv cw /usr/local/bin/cw
```

## Quick Start

### Standalone

```bash theme={null}
# Run a persistent session
cw run worker --dir ~/project --tag build -- claude -p "refactor the auth module"

# Attach to it (detach with Ctrl+B d)
cw attach 1

# List all sessions
cw list

# Wait for completion
cw wait --tag worker --condition all
```

### Platform

```bash theme={null}
# Set up platform connection
cw setup

# Launch a workspace from a repo
cw launch github.com/your-org/your-repo

# Run an agent in the workspace
cw run -- claude "fix the tests"
```

## Architecture

A single Go binary acts as both node and CLI client. The node manages PTY sessions and keeps processes alive regardless of client connections.

```
                     cw node
                ~/.codewire/codewire.sock

  +----------------------------------------------+
  |              SessionManager                   |
  |                                              |
  |   +----------+  +----------+                 |
  |   | Sess 1   |  | Sess 2   |   ...         |
  |   +----+-----+  +----+-----+                 |
  |        |              |                      |
  |   Per-Session:                               |
  |     PTY master (/dev/ptmx)                   |
  |     Broadcast buffer (4096)                  |
  |     Input channel (256 buffer)               |
  |     output.log + events.jsonl                |
  |                                              |
  |   SubscriptionManager (event pub/sub)        |
  |   sessions.json (debounced 500ms)            |
  +----------------------------------------------+
                       |
            +----------+----------+
            |                     |
       Unix Socket            WebSocket
       local clients           :9100 (opt.)
```