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

# Quick Start

> Install CliDeck and launch your first agent session in under a minute

## Install

CliDeck works on **macOS** and **Windows**. You need [Node.js](https://nodejs.org/) installed.

```bash theme={null}
npm install -g clideck
```

Then run it with:

```bash theme={null}
clideck
```

Or run directly without installing:

```bash theme={null}
npx clideck
```

Open [http://localhost:4000](http://localhost:4000) in your browser. That's it — you're in.

### Access from other devices on your network

By default, CliDeck binds to `127.0.0.1` (localhost only). To access it from another device on your LAN or over a VPN like Wireguard:

```bash theme={null}
clideck --host 0.0.0.0
```

You can also bind to a specific interface:

```bash theme={null}
clideck --host 192.168.1.50
```

<Warning>
  Binding to `0.0.0.0` exposes CliDeck to your entire network. Only use this on trusted networks.
</Warning>

## Your First Session

<Steps>
  <Step title="Click the + button">
    In the sidebar, click the **+** button to open the session launcher.
  </Step>

  <Step title="Pick an agent">
    You'll see buttons for each installed agent (Claude Code, Codex, Gemini CLI, OpenCode) plus a Shell option. You can also select a **project** and a **role** before launching. Click an agent button to start.
  </Step>

  <Step title="Start working">
    A new terminal session opens. Use the agent exactly as you normally would — type prompts, run commands, everything works the same.
  </Step>
</Steps>

The sidebar now shows your session with a live status indicator and message preview. Launch a few more sessions — you'll see all of them updating at once.

<Tip>
  New installs ship with three example roles (Programmer, Reviewer, Product Manager) and three example prompts. These are just starting points — edit or delete them as you see fit.
</Tip>

## Set Up Telemetry

Telemetry is how CliDeck knows when agents are working, idle, or finished. Without it, you get a terminal multiplexer but no status detection.

<Tabs>
  <Tab title="Claude Code">
    The first time you launch a Claude Code session, CliDeck shows a setup toast. Click **Patch Claude** and CliDeck adds lifecycle hooks to `~/.claude/settings.json`. Claude will ask for one-time approval on next launch. After that, status detection works automatically.
  </Tab>

  <Tab title="Codex">
    The first time you launch a Codex session, CliDeck shows a setup toast at the top of the terminal. Click **Configure automatically** and CliDeck writes the necessary config to `~/.codex/config.toml`. Restart the session when prompted.
  </Tab>

  <Tab title="Gemini CLI">
    Same as Codex — click **Configure automatically** on the setup toast. CliDeck writes the config to `~/.gemini/settings.json`. Restart the session when prompted.
  </Tab>

  <Tab title="OpenCode">
    OpenCode uses a plugin bridge instead of OTLP telemetry. The first time you launch an OpenCode session, CliDeck shows a setup toast. Click **Install plugin** and CliDeck copies the bridge plugin to `~/.config/opencode/plugins/` automatically. Restart the session when prompted.
  </Tab>
</Tabs>

## What You'll See

Once telemetry is connected, the sidebar shows:

* **Green bouncing dot** — The agent is actively working (generating code, running tools)
* **"zzZ" indicator** — The agent is idle, waiting for your input
* **Preview text** — The last meaningful line the agent output, right in the sidebar
* **Unread dot** — New output you haven't looked at yet

## Next Steps

<CardGroup cols={2}>
  <Card title="Mobile Remote" icon="mobile" href="/mobile">
    Check on your agents from your phone with a QR scan.
  </Card>

  <Card title="Agent guides" icon="robot" href="/agents/overview">
    Detailed setup for each supported agent.
  </Card>

  <Card title="Sessions" icon="rectangle-history" href="/features/sessions">
    Resume, restart, rename, and organize your sessions.
  </Card>

  <Card title="Notifications" icon="bell" href="/features/notifications">
    Get notified when agents finish working.
  </Card>

  <Card title="Ask" icon="comments" href="/features/ask">
    Let agents ask each other questions and get answers back.
  </Card>

  <Card title="Autopilot" icon="rotate" href="/features/autopilot">
    Automatic multi-agent workflow routing.
  </Card>
</CardGroup>