Installation Guide

Get CQ — the GPU orchestration platform — running in under 2 minutes.

One-Line Install

curl -fsSL https://raw.githubusercontent.com/PlayIdea-Lab/cq/main/install.sh | sh

This installs the cq binary, sets up .mcp.json, and initializes .c4/. Restart Claude Code after install — 275+ MCP tools register automatically.

Custom install directory

C4_INSTALL_DIR=/opt/cq curl -fsSL https://raw.githubusercontent.com/PlayIdea-Lab/cq/main/install.sh | sh

Non-interactive (CI / headless)

C4_GLOBAL_INSTALL=y curl -fsSL https://raw.githubusercontent.com/PlayIdea-Lab/cq/main/install.sh | sh

What the Installer Does

1. Checks Go 1.22+, Python 3.11+, uv
2. Clones the repo (or git pull if already present)
3. Builds the Go binary (c4-core/bin/cq)
4. Installs Python dependencies (uv sync)
5. Merges .mcp.json (preserves existing entries)
6. Initializes .c4/ directory
7. Optionally installs ~/.local/bin/cq globally

Prerequisites

Item	Required	Notes
Go 1.22+	Yes	For building the MCP server
Python 3.11+	Yes	For LSP / document parsing sidecar
uv	Yes	Python package manager — install
Claude Code	Yes	The AI tool CQ connects to
jq	Optional	Faster .mcp.json merging

Platform Notes

macOS (ARM64)

Never cp the binary — use make install to preserve code signing and embed the correct version:

# Wrong — breaks code signing and embeds version=dev
cp c4-core/bin/cq ~/.local/bin/cq

# Correct
cd c4-core && make install

Linux (systemd)

Register CQ as a user service for auto-start on boot:

cq serve start      # Start the service
cq serve enable     # Enable auto-start on boot
cq serve status     # Check status

Windows (WSL2)

CQ is WSL2-aware. The relay component automatically applies TCP keepalive to survive NAT timeouts common in WSL2 networking.

Verify Installation

cq doctor

Expected output:

[✓] cq binary: v1.58
[✓] Claude Code: installed
[✓] MCP server: .mcp.json connected
[✓] .c4/ directory: initialized

Fix any [✗] items before proceeding.

Login

Cloud sync, the Knowledge Loop, and the Research Loop all require authentication:

cq init            # Unified init: GitHub OAuth + workspace setup
cq auth status     # Verify login

No API keys needed — credentials are embedded in the binary at build time.

MCP Configuration

The installer writes .mcp.json automatically. For reference, the structure is:

{
  "mcpServers": {
    "cq": {
      "command": "/path/to/cq/c4-core/bin/cq",
      "args": ["mcp", "--dir", "/path/to/cq"],
      "env": {
        "C4_PROJECT_ROOT": "/path/to/cq"
      }
    }
  }
}

For global use across all projects, add to ~/.claude.json:

{
  "mcpServers": {
    "cq": {
      "command": "~/.local/bin/cq",
      "args": ["mcp"]
    }
  }
}

Restart Claude Code after any .mcp.json change.

Global Options

--global-mcp

Install CQ as a global MCP server available in all projects (writes to ~/.claude.json):

cd ~/c4 && ./install.sh --global-mcp

Without this flag, CQ is registered per-project in .mcp.json.

--global-skills

Install CQ skills globally so they are available in all Claude Code sessions:

cd ~/c4 && ./install.sh --global-skills

---

Update

cq update    # Pull latest binary and rebuild

Uninstall

# 1. Remove "cq" entry from .mcp.json or ~/.claude.json
# 2. Optionally remove the binary
rm -f ~/.local/bin/cq
# 3. Optionally remove the source
rm -rf /path/to/cq

Troubleshooting

Symptom	Fix
"MCP server not found"	Check binary path in .mcp.json; rebuild with cd c4-core && make install
macOS code signing error	Use cd c4-core && make install, never cp the binary
Python sidecar error	Run uv sync; verify Python 3.11+ with python3 --version
Go build fails	Run go version (need 1.22+); then cd c4-core && go mod download
cq_llm_call tool missing	Set ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment

Next Steps

• Quick Start — run your first plan in 5 minutes
• Tiers — Free vs Pro vs Team