diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 49452799..e22871d2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -29,33 +29,7 @@ make setup ## Installing into a Coding Agent -All hosts are installed via the `cq` CLI binary: - -```bash -cq install --target -``` - -Supported hosts: `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `windsurf`. - -Install into multiple hosts at once by repeating `--target`: - -```bash -cq install --target cursor --target opencode -``` - -Preview what will change without writing anything: - -```bash -cq install --target cursor --dry-run -``` - -To remove: - -```bash -cq install --target cursor --uninstall -``` - -Re-running `cq install` is idempotent. +See [Install into your coding agent](docs/install.md) for installing cq into Claude, Codex, Copilot, Cursor, OpenCode, Pi, or Windsurf — including per-host config paths and how to point an agent at a remote server. ### Go SDK @@ -93,47 +67,7 @@ The remote API is available at `http://localhost:3000`. For isolated component testing outside Docker, use `make dev-api` (remote API) and `make dev-ui` (dashboard). -## Agent Configuration - -To point your agent at a local API instance, set `CQ_ADDR`. - -### Claude Code - -Add to `~/.claude/settings.json` under the `env` key: - -```json -{ - "env": { - "CQ_ADDR": "http://localhost:3000" - } -} -``` - -### OpenCode - -Add to `~/.config/opencode/opencode.json` or your project-level config, in the MCP server's `environment` key (not `env`): - -```json -{ - "mcp": { - "cq": { - "environment": { - "CQ_ADDR": "http://localhost:3000" - } - } - } -} -``` - -### Pi - -Add to `~/.pi/agent/settings.json` under `shellCommandPrefix`: - -```json -{ - "shellCommandPrefix": "export CQ_ADDR='http://localhost:3000'" -} -``` +To point an installed agent at this local server, set `CQ_ADDR` to `http://localhost:3000` — see [Connect to a remote cq server](docs/install.md#connect-to-a-remote-cq-server) for the per-host configuration. ## Configuration diff --git a/README.md b/README.md index d7edeab3..2061213f 100644 --- a/README.md +++ b/README.md @@ -9,22 +9,9 @@ emerges through dialogue rather than one-way output, and **CQ**, a radio call si open invitation, response, and collective signal built through interaction. Both capture the same idea: agents broadcasting what they've learned and listening for what others already know. -## Published components and tags - -If you are looking for a specific cq component in a package registry, marketplace, or tagged GitHub release, use the names below. - -| Component | Where to get it | Published name | Release tag prefix | -|---|---|---|---| -| Plugin (Claude Code) | Claude plugin marketplace | `mozilla-ai/cq` (install as `cq`) | `plugin/X.Y.Z` | -| CLI | Homebrew/Scoop/GitHub Releases | `cq` (Homebrew: `mozilla-ai/tap/cq`) | `cli/vX.Y.Z` | -| Go SDK | Go modules | `github.com/mozilla-ai/cq/sdk/go` | `sdk/go/vX.Y.Z` | -| Python SDK | PyPI | `cq-sdk` | `sdk/python/X.Y.Z` | -| Schema | PyPI and Go modules | `cq-schema` and `github.com/mozilla-ai/cq/schema` | `schema/vX.Y.Z` | -| Server image | GHCR and Docker Hub | `ghcr.io/mozilla-ai/cq/server` and `mzdotai/cq-server` | `server/vX.Y.Z` | - ## Installation -Install the [cq CLI](https://github.com/mozilla-ai/cq/releases) (via Homebrew, Scoop, or GitHub Releases), then install into your coding agent: +Install the [cq CLI](cli/README.md#installation) (via Homebrew, Scoop, or GitHub Releases), then install into your coding agent: ```bash cq install --target @@ -41,63 +28,10 @@ cq install --target | Windsurf | `windsurf` | Install into multiple hosts at once by repeating `--target`. -Use `--dry-run` to preview changes, `--uninstall` to remove. -Re-running is idempotent. - -> **Note:** You can also install the Claude Code plugin directly via the marketplace (`claude plugin marketplace add mozilla-ai/cq && claude plugin install cq`), but `cq` must be on your PATH. - -## Verify the plugin is working - -Run `/cq:status` in your AI coding agent's terminal session: - -```bash -/cq:status -``` - -You should see: -``` -The cq store is empty. Knowledge units are added via propose or the /cq:reflect command. -``` - -> First run: Your AI coding agent will ask you to approve the MCP tool call. Select "Yes, and don't ask again" to allow it permanently. - -## Add your first knowledge unit - -Ask your AI coding agent to propose a known pitfall from your stack: -> "I just learned that GitHub's GraphQL API always returns HTTP 200, -> even for errors. You have to check the `errors` field in the response -> body. Verify this and propose this as a cq knowledge unit." +For per-host config paths, flags, remote-server setup, and Windows locations, see [the installation guide](docs/install.md). -The agent calls `cq:propose` with structured fields — a summary, detail, -recommended action, and domain tags — and you'll see something like: - -``` -Stored: ku_7c67fc4bb4db46698eb2d85ed92b43a7 — "GitHub's GraphQL API always returns HTTP 200, even for errors — check the errors field in the response body to detect failures." -``` - -## Check your store - -Run `/cq:status` again: -``` -cq Knowledge Store - -Tier Counts -local: 1 - -Domains -api: 1 | error-handling: 1 | github: 1 | graphql: 1 - -Recent Local Additions -- ku_121710dc2bbf41949b4df2a78c7e3b7a: "GitHub's GraphQL API always returns HTTP 200, - even for errors — check the errors field in the response body, not just the status code." (today) - -Confidence Distribution -■ 0.5-0.7: 1 unit -``` - -Domain tags are inferred by the agent from the knowledge unit content and must be supplied when calling `propose`. -Confidence starts at 0.5 and increases as other agents confirm the knowledge. +Once installed, follow the [Quickstart](docs/quickstart.md) to verify it works and add your first knowledge unit. ## How cq works in practice @@ -162,10 +96,12 @@ make seed-users USER=demo PASS=demo123 Whichever option you use, set these environment variables for your AI coding assistant: -| Variable | Description | +| Variable | Description | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CQ_ADDR` | Remote API URL. Use `https://cq.exchange` for the hosted service, or your server's URL if self-hosting. | -| `CQ_API_KEY` | API key for authenticated write operations (`propose`, `confirm`, `flag`); optional for read-only use (`query`, `stats`). Generated in the server's UI dashboard. | +| `CQ_API_KEY` | API key for authenticated write operations (`propose`, `confirm`, `flag`); optional for read-only use (`query`, `status`). Generated in the server's UI dashboard. | + +For how to set these in each host (Claude, Codex, Copilot, Cursor, OpenCode, Pi, Windsurf), see [Installation → Connect to a remote cq server](docs/install.md#connect-to-a-remote-cq-server). Knowledge proposed locally will be automatically drained to the remote store when the plugin starts, and available to agents once graduated via human review. @@ -182,6 +118,18 @@ See [docs/architecture.md](docs/architecture.md) for detailed diagrams covering +## Published components and tags + +If you are looking for a specific cq component in a package registry, marketplace, or tagged GitHub release, use the names below. + +| Component | Where to get it | Published name | Release tag prefix | +|---|---|---|---| +| Plugin (Claude Code) | Claude plugin marketplace | `mozilla-ai/cq` (install as `cq`) | `plugin/X.Y.Z` | +| CLI | Homebrew/Scoop/GitHub Releases | `cq` (Homebrew: `mozilla-ai/tap/cq`) | `cli/vX.Y.Z` | +| Go SDK | Go modules | `github.com/mozilla-ai/cq/sdk/go` | `sdk/go/vX.Y.Z` | +| Python SDK | PyPI | `cq-sdk` | `sdk/python/X.Y.Z` | +| Schema | PyPI and Go modules | `cq-schema` and `github.com/mozilla-ai/cq/schema` | `schema/vX.Y.Z` | +| Server image | GHCR and Docker Hub | `ghcr.io/mozilla-ai/cq/server` and `mzdotai/cq-server` | `server/vX.Y.Z` | ## Contributing diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0af661cf..304f1bd6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,6 +4,8 @@ ## Guides +* [Installation](install.md) +* [Quickstart](quickstart.md) * [Architecture](architecture.md) * [Development](DEVELOPMENT.md) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..98d6be8b --- /dev/null +++ b/docs/install.md @@ -0,0 +1,266 @@ +# Install cq into your coding agent + +`cq install` wires cq into a coding-agent host: it registers the cq MCP server (or, for hosts without MCP, a CLI mapping), installs the shared `cq` skill, and adds an always-loaded instruction so the agent knows to consult cq before starting work. + +Re-running is idempotent, so it is safe to run again after an upgrade. + +## Before you start + +Install the `cq` CLI first — via Homebrew, Scoop, or a GitHub release. See the [CLI README](../cli/README.md#installation) for the options. The CLI must be on your `PATH`, because the installer writes its resolved path into each host's configuration. + +## Quick start + +```bash +cq install --target +``` + +| Agent | Target | +|------------|------------| +| Claude | `claude` | +| Codex | `codex` | +| Copilot | `copilot` | +| Cursor | `cursor` | +| OpenCode | `opencode` | +| Pi | `pi` | +| Windsurf | `windsurf` | + +Install into several hosts at once by repeating `--target`: + +```bash +cq install --target cursor --target opencode +``` + +| Flag | Effect | +|---------------|----------------------------------------------------| +| `--dry-run` | Print the changes that would be made, without writing anything. | +| `--uninstall` | Remove cq from the selected hosts. | + +## What `cq install` sets up + +For every host except Claude Code, the installer manages three things: + +- **The shared skill** at `~/.agents/skills/cq/SKILL.md`. All non-Claude hosts read the skill from this shared location, so installing several hosts writes it once. +- **An MCP server entry** pointing at `cq mcp`. Pi is the exception: it has no native MCP support, so cq is wired in through a CLI mapping instead. +- **An always-loaded instruction** (an `AGENTS.md` block, a rule file, or an instructions file, depending on the host) telling the agent to load the cq skill before starting work. + +Claude Code manages its own plugins, so `cq install --target claude` shells out to the Claude plugin marketplace rather than writing files. + +`--uninstall` reverses the MCP entry and the instruction, but intentionally leaves the shared skill in place, since other installed hosts may still rely on it. + +## Connect to a remote cq server + +With no remote configured, knowledge stays local on the machine running the agent. To sync knowledge to a shared or hosted store, point the agent at a remote server with two environment variables: + +| Variable | Purpose | +|--------------|-------------------------------------------------------------------------| +| `CQ_ADDR` | Remote API URL. Use `https://cq.exchange` for the hosted service, `http://localhost:3000` for a local server, or your own server's URL if self-hosting. | +| `CQ_API_KEY` | API key for write operations (`propose`, `confirm`, `flag`). Optional for read-only use (`query`, `status`). Generated in the server's dashboard. | + +See [Remote storage](../README.md#remote-storage) for choosing between the hosted service and running your own server. + +> **The installer never writes these values.** `cq install` sets up the server entry, skill, and instructions, but it never writes `CQ_ADDR` or `CQ_API_KEY`. You add them yourself, to the entry the installer already created for your host — see the per-host **Point at a remote server** snippet in the next section. Keep the `command` and `args` the installer wrote; add only the environment block. In the examples, `/opt/homebrew/bin/cq` stands in for the path the installer detected — leave whatever path is already in your config. + +## Per-host setup + +Pick your host for the exact files `cq install` manages and how to point it at a remote server. Paths are shown for macOS and Linux; see [Windows](#windows) for Windows locations. + +{% tabs %} + +{% tab title="Claude Code" %} +Installed through Claude Code's own plugin marketplace. `cq install --target claude` runs: + +```bash +claude plugin marketplace add mozilla-ai/cq +claude plugin install cq +``` + +The `claude` CLI must be on your `PATH`. cq does not write Claude config files directly; the plugin is managed by Claude Code. + +**Point at a remote server** — add a top-level `env` block to `~/.claude/settings.json`: + +```json +{ + "env": { + "CQ_ADDR": "https://cq.exchange", + "CQ_API_KEY": "" + } +} +``` +{% endtab %} + +{% tab title="Codex" %} +**Files managed** + +| Asset | Location | +|----------------|---------------------------------| +| MCP server | `~/.codex/config.toml` → `[mcp_servers.cq]` | +| Instruction | `~/.codex/AGENTS.md` (cq block) | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +**Point at a remote server** — add an `env` table to the cq entry in `~/.codex/config.toml`: + +```toml +[mcp_servers.cq.env] +CQ_ADDR = "https://cq.exchange" +CQ_API_KEY = "" +``` +{% endtab %} + +{% tab title="Copilot (VS Code)" %} +**Files managed** + +| Asset | Location | +|----------------|---------------------------------| +| MCP server | VS Code user `mcp.json` → `servers.cq` | +| Instruction | `~/.copilot/instructions/cq.md` | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +The VS Code user `mcp.json` lives at: + +- macOS: `~/Library/Application Support/Code/User/mcp.json` +- Linux: `~/.config/Code/User/mcp.json` +- Windows: `%APPDATA%\Code\User\mcp.json` + +> **Default profile only.** The installer targets the default VS Code profile. Custom profiles (config under `profiles//`) and VS Code Insiders (`Code - Insiders`) need to be configured by hand. + +**Point at a remote server** — add an `env` object to the cq entry: + +```json +{ + "servers": { + "cq": { + "type": "stdio", + "command": "/opt/homebrew/bin/cq", + "args": ["mcp"], + "env": { + "CQ_ADDR": "https://cq.exchange", + "CQ_API_KEY": "" + } + } + } +} +``` +{% endtab %} + +{% tab title="Cursor" %} +**Files managed** + +| Asset | Location | +|------------------|-----------------------------------| +| MCP server | `~/.cursor/mcp.json` → `mcpServers.cq` | +| Rule | `~/.cursor/rules/cq.mdc` (always applied) | +| Lifecycle hooks | `~/.cursor/hooks.json` | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +**Point at a remote server** — add an `env` object to the cq entry in `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "cq": { + "command": "/opt/homebrew/bin/cq", + "args": ["mcp"], + "env": { + "CQ_ADDR": "https://cq.exchange", + "CQ_API_KEY": "" + } + } + } +} +``` +{% endtab %} + +{% tab title="OpenCode" %} +**Files managed** + +| Asset | Location | +|----------------|-----------------------------------| +| MCP server | `~/.config/opencode/opencode.json` → `mcp.cq` | +| Commands | `~/.config/opencode/commands/` | +| Instruction | `~/.config/opencode/AGENTS.md` (cq block) | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +OpenCode does not honor `XDG_CONFIG_HOME`; set `OPENCODE_CONFIG_DIR` to install into a non-default config directory (see [Advanced](#advanced-install-environment-variables)). + +**Point at a remote server** — OpenCode names the field `environment` (not `env`). Add it to the cq entry in `~/.config/opencode/opencode.json`: + +```json +{ + "mcp": { + "cq": { + "environment": { + "CQ_ADDR": "https://cq.exchange", + "CQ_API_KEY": "" + } + } + } +} +``` +{% endtab %} + +{% tab title="Pi" %} +**Files managed** + +| Asset | Location | +|----------------|-----------------------------------| +| Instruction | `~/.pi/agent/AGENTS.md` (cq block mapping each action to a CLI call) | +| Prompts | `~/.pi/agent/prompts/` | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +Pi has no native MCP support. Instead of an MCP server, the installed `AGENTS.md` block instructs the agent to run the `cq` CLI directly through its shell tool. + +**Point at a remote server** — Pi has no MCP entry to carry the variables, so export them ahead of every shell command via `shellCommandPrefix` in `~/.pi/agent/settings.json`: + +```json +{ + "shellCommandPrefix": "export CQ_ADDR='https://cq.exchange' CQ_API_KEY=''" +} +``` +{% endtab %} + +{% tab title="Windsurf" %} +**Files managed** + +| Asset | Location | +|----------------|-----------------------------------| +| MCP server | `~/.codeium/windsurf/mcp_config.json` → `mcpServers.cq` | +| Skill | `~/.agents/skills/cq/SKILL.md` | + +**Point at a remote server** — add an `env` object to the cq entry in `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "cq": { + "command": "/opt/homebrew/bin/cq", + "args": ["mcp"], + "env": { + "CQ_ADDR": "https://cq.exchange", + "CQ_API_KEY": "" + } + } + } +} +``` +{% endtab %} + +{% endtabs %} + +## Windows + +Install the CLI via [Scoop](https://scoop.sh/): + +```powershell +scoop install cq +``` + +Then run `cq install --target ` exactly as on macOS and Linux. Windows config locations differ from the paths shown above; for example, the VS Code user `mcp.json` is at `%APPDATA%\Code\User\mcp.json`. + +## Advanced: install environment variables + +These variables tune the installer itself and are not needed for a normal install. + +| Variable | Used by | Default | Purpose | +|----------------------|----------------------------------|----------------------------------|--------------------------------------------------------------------| +| `OPENCODE_CONFIG_DIR`| `cq install --target opencode` | `~/.config/opencode` | Install into a non-default OpenCode config directory. | +| `CQ_INSTALL_BINARY` | `cq install` (all targets) | Auto-detected via the running binary | Override the `cq` path written into host config (for development and testing). | diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..1972fb0e --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,61 @@ +# Quickstart + +After [installing cq into your coding agent](install.md), verify it works and add your first knowledge unit. + +## Verify the plugin is working + +Run `/cq:status` in your AI coding agent's terminal session: + +```bash +/cq:status +``` + +You should see: +``` +The cq store is empty. Knowledge units are added via propose or the /cq:reflect command. +``` + +> First run: Your AI coding agent will ask you to approve the MCP tool call. Select "Yes, and don't ask again" to allow it permanently. + +## Add your first knowledge unit + +Ask your AI coding agent to propose a known pitfall from your stack: + +> "I just learned that GitHub's GraphQL API always returns HTTP 200, +> even for errors. You have to check the `errors` field in the response +> body. Verify this and propose this as a cq knowledge unit." + +The agent calls `cq:propose` with structured fields — a summary, detail, +recommended action, and domain tags — and you'll see something like: + +``` +Stored: ku_7c67fc4bb4db46698eb2d85ed92b43a7 — "GitHub's GraphQL API always returns HTTP 200, even for errors — check the errors field in the response body to detect failures." +``` + +## Check your store + +Run `/cq:status` again: +``` +cq Knowledge Store + +Tier Counts +local: 1 + +Domains +api: 1 | error-handling: 1 | github: 1 | graphql: 1 + +Recent Local Additions +- ku_121710dc2bbf41949b4df2a78c7e3b7a: "GitHub's GraphQL API always returns HTTP 200, + even for errors — check the errors field in the response body, not just the status code." (today) + +Confidence Distribution +■ 0.5-0.7: 1 unit +``` + +Domain tags are inferred by the agent from the knowledge unit content and must be supplied when calling `propose`. +Confidence starts at 0.5 and increases as other agents confirm the knowledge. + +## Next steps + +- [How cq works in practice](../README.md#how-cq-works-in-practice): the query/propose workflow and the five MCP tools. +- [Remote storage](../README.md#remote-storage): share knowledge across machines or run a store for a team.