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

# Installation

> Install CCS via npm, verify setup, and configure your first profile

# Installation

## Prerequisites

<CardGroup cols={2}>
  <Card title="macOS / Linux" icon="apple">
    * Node.js 18+
    * npm
    * [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
  </Card>

  <Card title="Windows" icon="windows">
    * PowerShell 5.1+ (pre-installed on Windows 10+)
    * Node.js 18+
    * [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
  </Card>
</CardGroup>

## Install CCS

<Tabs>
  <Tab title="npm (recommended)">
    ```bash theme={null}
    npm install -g @kaitranntt/ccs
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add @kaitranntt/ccs
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add -g @kaitranntt/ccs
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add -g @kaitranntt/ccs
    ```
  </Tab>
</Tabs>

## Verify Installation

```bash theme={null}
ccs --version
# ccs/7.x.x darwin-arm64 node-v22.x.x
```

## First Run

```bash theme={null}
# Opens OAuth for default Claude account
ccs

# Or open the dashboard to configure providers and profiles
ccs config

# Run setup wizard
ccs setup
```

## What Gets Installed

The postinstall script creates `~/.ccs/` with default templates:

```
~/.ccs/
├── config.yaml             # Unified config (schema v12)
├── glm.settings.json       # Z.AI GLM profile template
├── instances/              # Claude account instances
├── cliproxy/               # OAuth provider auth tokens
└── shared/                 # Shared commands/skills/agents
```

<Note>
  If you run `npm install --ignore-scripts`, config files won't be created
  automatically. Re-run without that flag or run `ccs setup` manually.
</Note>

## Upgrade

```bash theme={null}
npm update -g @kaitranntt/ccs

# Or force reinstall
ccs update --force
```

## Uninstall

```bash theme={null}
npm uninstall -g @kaitranntt/ccs
```

This removes the CCS command but preserves your `~/.ccs/` configuration
directory.

## Platform Notes

### macOS / Linux

No special configuration needed. CCS detects Claude CLI from PATH.

```bash theme={null}
# Override Claude CLI location if detection fails
export CCS_CLAUDE_PATH="/custom/path/to/claude"
```

### Windows (PowerShell 5.1+)

CCS auto-detects Claude CLI via these paths in order:

```
%USERPROFILE%\.local\bin\claude.exe
%APPDATA%\npm\claude.cmd
```

If detection fails, override with:

```powershell theme={null}
$env:CCS_CLAUDE_PATH = "C:\custom\path\to\Claude.exe"
```

### Docker

CCS can run in Docker containers. Mount your `~/.ccs` and `~/.claude`
directories:

```bash theme={null}
docker run -v ~/.ccs:/root/.ccs -v ~/.claude:/root/.claude \
  node:22 npx @kaitranntt/ccs codex "your task"
```

## Troubleshooting

### `ccs: command not found`

npm global bin directory is not in PATH. Add it:

```bash theme={null}
# Find npm global bin
npm config get prefix
# e.g. /usr/local

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
```

### Permission Denied (Linux/macOS)

```bash theme={null}
# Fix npm global permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Then reinstall
npm install -g @kaitranntt/ccs
```

## Next Steps

<CardGroup cols={2}>
  <Card title="First Session" icon="rocket" href="/getting-started/first-session">
    Authenticate and run your first query
  </Card>

  <Card title="Configuration" icon="gear" href="/getting-started/configuration">
    Understand config format and options
  </Card>

  <Card title="Provider Overview" icon="grid" href="/providers/concepts/overview">
    Choose your first provider
  </Card>

  <Card title="Product Tour" icon="image" href="/getting-started/product-tour">
    See the dashboard and workflow surfaces before deeper setup
  </Card>
</CardGroup>