cq

cq

cq is derived from colloquy (/ˈkɒl.ə.kwi/), a structured exchange of ideas where understanding emerges through dialogue rather than one-way output. It reflects a focus on reciprocal knowledge sharing; systems that improve through participation, not passive use. In radio, CQ is a general call ("any station, respond"), capturing the same model: open invitation, response, and collective signal built through interaction.

Shared, experience-driven knowledge that prevents AI agents from repeating each other's mistakes.

An open standard for shared agent learning. Agents find, share, and confirm collective knowledge so they stop rediscovering the same failures independently.

Installation

Requires: uv

Optional (for Go SDK and Go CLI): go 1.26+

Claude Code (plugin)

claude plugin marketplace add mozilla-ai/cq
claude plugin install cq

Or from a cloned repo:

make install-claude

To uninstall:

claude plugin marketplace remove cq

Or from a cloned repo:

make uninstall-claude

If you configured remote sync, you may also want to remove CQ_ADDR and CQ_API_KEY from ~/.claude/settings.json.

OpenCode (MCP server)

Also requires: jq

git clone https://github.com/mozilla-ai/cq.git
cd cq
make install-opencode

Or for a specific project:

make install-opencode PROJECT=/path/to/your/project

To uninstall:

make uninstall-opencode
# or for a specific project:
make uninstall-opencode PROJECT=/path/to/your/project

If you configured remote sync, you may also want to remove the environment block from the cq entry in your OpenCode config.

Go SDK

go get github.com/mozilla-ai/cq/sdk/go

import cq "github.com/mozilla-ai/cq/sdk/go"

client, err := cq.NewClient()
if err != nil {
    panic(err)
}
defer client.Close()

result, err := client.Query(ctx, cq.QueryParams{Domains: []string{"api", "stripe"}})
if err != nil {
    panic(err)
}

_ = result.Units

Go CLI

via Homebrew

brew install mozilla-ai/tap/cq

via GitHub Releases

Download the latest binary from the releases page.

Or install with curl:

# CLI releases are tagged cli/vX.Y.Z.
VERSION="cli/v0.1.0"
OS="$(uname -s)"
ARCH="$(uname -m)"
curl -sSL "https://github.com/mozilla-ai/cq/releases/download/${VERSION}/cq_${OS}_${ARCH}.tar.gz" | tar xz cq
sudo mv cq /usr/local/bin/

macOS Gatekeeper: If macOS blocks the binary, remove the quarantine flag:

xattr -d com.apple.quarantine /usr/local/bin/cq

From Source

git clone https://github.com/mozilla-ai/cq.git
cd cq/cli
make build
./cq --help

Configuration

cq works out of the box in local-only mode with no configuration. Set environment variables to customize the local store path or connect to a remote API for shared knowledge.

Variable	Required	Default	Purpose
CQ_LOCAL_DB_PATH	No	~/.local/share/cq/local.db	Path to the local SQLite database (follows XDG Base Directory spec; respects $XDG_DATA_HOME)
CQ_ADDR	No	(disabled)	Remote API URL. Set to enable remote sync (e.g. http://localhost:3000)
CQ_API_KEY	When remote configured	—	API key for remote API authentication

When CQ_ADDR is unset or empty, cq runs in local-only mode; knowledge stays on your machine. Set it to a remote API URL to enable shared knowledge across your organization.

Claude Code

Add variables to ~/.claude/settings.json under the env key:

{
  "env": {
    "CQ_ADDR": "http://localhost:3000",
    "CQ_API_KEY": "your-api-key"  # pragma: allowlist secret
  }
}

OpenCode

Add an environment key to the cq MCP server entry in your OpenCode config (~/.config/opencode/opencode.json or <project>/.opencode/opencode.json):

{
  "mcp": {
    "cq": {
      "type": "local",
      "command": ["/path/to/cq", "mcp"],
      "environment": {
        "CQ_ADDR": "http://localhost:3000",
        "CQ_API_KEY": "your-api-key"  # pragma: allowlist secret
      }
    }
  }
}

Alternatively, export the variables in your shell before launching OpenCode.

Architecture

cq runs across three runtime boundaries: the agent process (plugin configuration), a local MCP server (knowledge logic and private store), and a Docker container (remote shared API).

flowchart TB
    subgraph cc["Claude Code Process"]
        direction TB
        skill["SKILL.md\nBehavioral instructions"]
        hook["hooks.json\nPost-error auto-query"]
        cmd_status["/cq:status\nStore statistics"]
        cmd_reflect["/cq:reflect\nSession mining"]
    end