You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: add coding-agent installation and quickstart guides (#486)
Add a customer-facing installation guide (docs/install.md) covering the
seven supported hosts: the files each 'cq install --target' manages,
per-host tabs for setup, and how to point an agent at a remote server via
CQ_ADDR and CQ_API_KEY. This restores the Copilot/VS Code and Codex
coverage that was dropped when the Python installer was retired.
Move the hands-on walkthrough (verify, add first knowledge unit, check
store) out of the README into a dedicated quickstart guide, and relocate
the agent-install and per-host configuration content out of DEVELOPMENT.md
so those pages point at the guide instead.
Restructure the introduction to lead with installation and move the
components-and-tags reference table down. Wire both new pages into
docs/SUMMARY.md under Guides.
Install into multiple hosts at once by repeating `--target`:
41
-
42
-
```bash
43
-
cq install --target cursor --target opencode
44
-
```
45
-
46
-
Preview what will change without writing anything:
47
-
48
-
```bash
49
-
cq install --target cursor --dry-run
50
-
```
51
-
52
-
To remove:
53
-
54
-
```bash
55
-
cq install --target cursor --uninstall
56
-
```
57
-
58
-
Re-running `cq install` is idempotent.
32
+
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.
59
33
60
34
### Go SDK
61
35
@@ -93,47 +67,7 @@ The remote API is available at `http://localhost:3000`.
93
67
94
68
For isolated component testing outside Docker, use `make dev-api` (remote API) and `make dev-ui` (dashboard).
95
69
96
-
## Agent Configuration
97
-
98
-
To point your agent at a local API instance, set `CQ_ADDR`.
99
-
100
-
### Claude Code
101
-
102
-
Add to `~/.claude/settings.json` under the `env` key:
103
-
104
-
```json
105
-
{
106
-
"env": {
107
-
"CQ_ADDR": "http://localhost:3000"
108
-
}
109
-
}
110
-
```
111
-
112
-
### OpenCode
113
-
114
-
Add to `~/.config/opencode/opencode.json` or your project-level config, in the MCP server's `environment` key (not `env`):
115
-
116
-
```json
117
-
{
118
-
"mcp": {
119
-
"cq": {
120
-
"environment": {
121
-
"CQ_ADDR": "http://localhost:3000"
122
-
}
123
-
}
124
-
}
125
-
}
126
-
```
127
-
128
-
### Pi
129
-
130
-
Add to `~/.pi/agent/settings.json` under `shellCommandPrefix`:
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.
| Go SDK | Go modules |`github.com/mozilla-ai/cq/sdk/go`|`sdk/go/vX.Y.Z`|
21
-
| Python SDK | PyPI |`cq-sdk`|`sdk/python/X.Y.Z`|
22
-
| Schema | PyPI and Go modules |`cq-schema` and `github.com/mozilla-ai/cq/schema`|`schema/vX.Y.Z`|
23
-
| Server image | GHCR and Docker Hub |`ghcr.io/mozilla-ai/cq/server` and `mzdotai/cq-server`|`server/vX.Y.Z`|
24
-
25
12
## Installation
26
13
27
-
Install the [cq CLI](https://github.com/mozilla-ai/cq/releases) (via Homebrew, Scoop, or GitHub Releases), then install into your coding agent:
14
+
Install the [cq CLI](cli/README.md#installation) (via Homebrew, Scoop, or GitHub Releases), then install into your coding agent:
28
15
29
16
```bash
30
17
cq install --target <host>
@@ -41,63 +28,10 @@ cq install --target <host>
41
28
| Windsurf |`windsurf`|
42
29
43
30
Install into multiple hosts at once by repeating `--target`.
44
-
Use `--dry-run` to preview changes, `--uninstall` to remove.
45
-
Re-running is idempotent.
46
-
47
-
> **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.
48
-
49
-
## Verify the plugin is working
50
-
51
-
Run `/cq:status` in your AI coding agent's terminal session:
52
-
53
-
```bash
54
-
/cq:status
55
-
```
56
-
57
-
You should see:
58
-
```
59
-
The cq store is empty. Knowledge units are added via propose or the /cq:reflect command.
60
-
```
61
-
62
-
> 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.
63
-
64
-
## Add your first knowledge unit
65
-
66
-
Ask your AI coding agent to propose a known pitfall from your stack:
67
31
68
-
> "I just learned that GitHub's GraphQL API always returns HTTP 200,
69
-
> even for errors. You have to check the `errors` field in the response
70
-
> body. Verify this and propose this as a cq knowledge unit."
32
+
For per-host config paths, flags, remote-server setup, and Windows locations, see [the installation guide](docs/install.md).
71
33
72
-
The agent calls `cq:propose` with structured fields — a summary, detail,
73
-
recommended action, and domain tags — and you'll see something like:
74
-
75
-
```
76
-
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."
|`CQ_ADDR`| Remote API URL. Use `https://cq.exchange` for the hosted service, or your server's URL if self-hosting. |
168
-
|`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. |
102
+
|`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. |
103
+
104
+
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).
169
105
170
106
Knowledge proposed locally will be automatically drained to the remote store when the plugin starts, and available to agents once graduated via human review.
171
107
@@ -182,6 +118,18 @@ See [docs/architecture.md](docs/architecture.md) for detailed diagrams covering
182
118
183
119
</details>
184
120
121
+
## Published components and tags
122
+
123
+
If you are looking for a specific cq component in a package registry, marketplace, or tagged GitHub release, use the names below.
124
+
125
+
| Component | Where to get it | Published name | Release tag prefix |
126
+
|---|---|---|---|
127
+
| Plugin (Claude Code) | Claude plugin marketplace |`mozilla-ai/cq` (install as `cq`) |`plugin/X.Y.Z`|
0 commit comments