cue-ai 0.9.3 → 0.9.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -370
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,510 +1,292 @@
|
|
|
1
|
-
|
|
1
|
+
# cuecards
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
<img src="./docs/assets/hero.svg" alt="cuecards — Agent Profile Manager for AI coding agents" width="820">
|
|
5
|
-
</p>
|
|
6
|
-
|
|
7
|
-
<br>
|
|
3
|
+
**Give your AI coding agent the right context for every project — and nothing else.**
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
cue is a profile manager for AI coding agents like [Claude Code](https://github.com/anthropics/claude-code) and [Codex](https://github.com/openai/codex). You pick (or auto-detect) a *cuecard* for each project directory, and when you launch your agent, cue loads only the skills, MCP servers, persona, and quality gates that project actually needs — instead of your entire library.
|
|
10
6
|
|
|
11
7
|
<p align="center">
|
|
12
|
-
<
|
|
8
|
+
<img src="https://raw.githubusercontent.com/opencue/cuecards/main/docs/assets/hero.svg" alt="cuecards — Agent Profile Manager for AI coding agents" width="820">
|
|
13
9
|
</p>
|
|
14
10
|
|
|
15
|
-
<p align="center">
|
|
16
|
-
<sub>Your agent walks into a directory. The cuecard tells it who to be — and loads only what the job needs.</sub>
|
|
17
|
-
</p>
|
|
18
|
-
|
|
19
|
-
<br>
|
|
20
|
-
|
|
21
11
|
<p align="center">
|
|
22
12
|
<a href="https://www.npmjs.com/package/cue-ai"><img src="https://img.shields.io/npm/v/cue-ai?style=flat-square&label=npm&color=1d1d1f&labelColor=f5f5f7" alt="npm"></a>
|
|
23
13
|
<a href="https://www.npmjs.com/package/cue-ai"><img src="https://img.shields.io/npm/dw/cue-ai?style=flat-square&label=downloads&color=1d1d1f&labelColor=f5f5f7" alt="downloads"></a>
|
|
24
14
|
<a href="https://github.com/opencue/cuecards/stargazers"><img src="https://img.shields.io/github/stars/opencue/cuecards?style=flat-square&label=stars&color=1d1d1f&labelColor=f5f5f7" alt="stars"></a>
|
|
25
|
-
<a href="
|
|
15
|
+
<a href="https://github.com/opencue/cuecards/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencue/cuecards?style=flat-square&label=license&color=1d1d1f&labelColor=f5f5f7" alt="MIT"></a>
|
|
26
16
|
<img src="https://img.shields.io/badge/telemetry-none-1d1d1f?style=flat-square&labelColor=f5f5f7" alt="zero telemetry">
|
|
27
17
|
</p>
|
|
28
18
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
<code>npm install -g cue-ai</code>
|
|
33
|
-
</p>
|
|
34
|
-
|
|
35
|
-
<p align="center">
|
|
36
|
-
<sub>Requires Node ≥20 and an existing <a href="https://github.com/anthropics/claude-code">Claude Code</a> or <a href="https://github.com/openai/codex">Codex</a> install — cue is a thin shim that exec's your agent, not a replacement.</sub>
|
|
37
|
-
<br>
|
|
38
|
-
<sub>package <code>cue-ai</code> · command <code>cue</code> · repo <a href="https://github.com/opencue/cuecards"><code>opencue/cuecards</code></a></sub>
|
|
39
|
-
</p>
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g cue-ai
|
|
21
|
+
```
|
|
40
22
|
|
|
41
|
-
|
|
42
|
-
|
|
23
|
+
> Requires Node ≥ 20 and an existing [Claude Code](https://github.com/anthropics/claude-code) or [Codex](https://github.com/openai/codex) install. cue is a thin shim that hands off to your real agent — not a replacement for it.
|
|
24
|
+
>
|
|
25
|
+
> package `cue-ai` · command `cue` · repo [opencue/cuecards](https://github.com/opencue/cuecards)
|
|
43
26
|
|
|
44
27
|
---
|
|
45
28
|
|
|
46
|
-
##
|
|
47
|
-
|
|
48
|
-
You installed 330 skills and 15 MCP servers. Your agent re-reads **every one of them, on every message** — including the 320 it doesn't need for the task in front of it.
|
|
29
|
+
## Why does this exist?
|
|
49
30
|
|
|
50
|
-
|
|
31
|
+
If you've been using AI coding agents for a while, you've probably collected a pile of skills, MCP servers, and custom instructions. Maybe hundreds. Here's the problem:
|
|
51
32
|
|
|
52
|
-
**
|
|
33
|
+
**your agent re-reads all of them, on every single message** — including the 95% that have nothing to do with the task in front of it.
|
|
53
34
|
|
|
54
|
-
|
|
35
|
+
That hurts twice:
|
|
55
36
|
|
|
56
|
-
|
|
37
|
+
1. **You pay for it.** Every always-loaded skill description and MCP schema is input tokens, billed on every turn of every session.
|
|
38
|
+
2. **Your agent gets dumber.** Picking the right tool out of 330 irrelevant ones is harder than picking it out of 12 relevant ones.
|
|
57
39
|
|
|
58
|
-
|
|
40
|
+
cue fixes this by scoping everything per directory. Your Medusa shop loads the Medusa cuecard. Your Rust CLI loads the Rust cuecard. Nothing else comes along for the ride.
|
|
59
41
|
|
|
60
|
-
|
|
42
|
+
### What that saves, in numbers
|
|
61
43
|
|
|
62
44
|
| Loadout | Always-on context | Cost / 100 msgs (Sonnet input) |
|
|
63
45
|
|---|---|---|
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
46
|
+
| Everything loaded (`full` profile) | ~81k tokens | ~$24 |
|
|
47
|
+
| `backend` cuecard | ~9k tokens | ~$2.70 |
|
|
48
|
+
| `caveman-quick` cuecard | ~6.8k tokens | ~$2.00 |
|
|
67
49
|
|
|
68
|
-
That's
|
|
50
|
+
That's **9–16× less always-on context**, compounding on every message. You can reproduce these numbers yourself:
|
|
69
51
|
|
|
70
52
|
```bash
|
|
71
|
-
cue cost
|
|
72
|
-
cue cost --compare
|
|
53
|
+
cue cost # token budget for your active profile
|
|
54
|
+
cue cost --compare # every profile ranked against the `full` baseline
|
|
73
55
|
```
|
|
74
56
|
|
|
75
|
-
<p align="center">
|
|
76
|
-
<sub><strong>< 5 ms</strong> warm launch · <strong>69</strong> pre-built cuecards · <strong>330+</strong> local skills · <strong>10</strong> AI agents · <strong>MIT</strong> · zero telemetry · no daemon</sub>
|
|
77
|
-
</p>
|
|
78
|
-
|
|
79
|
-
<br>
|
|
80
|
-
|
|
81
57
|
---
|
|
82
58
|
|
|
83
|
-
##
|
|
59
|
+
## What is a cuecard?
|
|
84
60
|
|
|
85
|
-
A
|
|
61
|
+
A cuecard (also called a *profile*) is everything your agent needs to be useful in one project, bundled into a single `profile.yaml`:
|
|
86
62
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
| layer | what's on the cuecard |
|
|
63
|
+
| Layer | What it controls |
|
|
90
64
|
|---|---|
|
|
91
|
-
| **
|
|
92
|
-
| **
|
|
93
|
-
| **
|
|
94
|
-
| **
|
|
95
|
-
| **
|
|
96
|
-
| **
|
|
97
|
-
|
|
98
|
-
This is what separates cuecards from a skills list: a cuecard is *composable expertise* — persona + playbooks + gates + evals + a failure loop — not just "more tools loaded."
|
|
65
|
+
| **Skills** | Only the ones this project actually needs |
|
|
66
|
+
| **MCP servers** | Scoped per directory — no global sprawl |
|
|
67
|
+
| **Plugins** | The Claude Code plugins this project wants, no more |
|
|
68
|
+
| **Persona** | How the agent thinks, writes, and self-edits |
|
|
69
|
+
| **Playbooks** | Step-by-step procedures for known tasks |
|
|
70
|
+
| **Gates** | What must pass before the agent can claim "done" |
|
|
99
71
|
|
|
100
|
-
|
|
72
|
+
One cuecard per project. Your agent reads the right one the moment you launch it. That's what makes a cuecard more than a skills list — it's composable expertise, not just "more tools loaded."
|
|
101
73
|
|
|
102
74
|
---
|
|
103
75
|
|
|
104
|
-
##
|
|
76
|
+
## Quickstart
|
|
77
|
+
|
|
78
|
+
Five commands from zero to a profile-aware agent:
|
|
105
79
|
|
|
106
80
|
```bash
|
|
107
|
-
npm install -g cue-ai
|
|
108
|
-
cue shell install
|
|
109
|
-
cue discover search "code review"
|
|
110
|
-
cue discover install review/code-review
|
|
111
|
-
claude
|
|
81
|
+
npm install -g cue-ai # 1. install
|
|
82
|
+
cue shell install # 2. activate the claude shim (one-time; add --codex for codex)
|
|
83
|
+
cue discover search "code review" # 3. find a skill you want
|
|
84
|
+
cue discover install review/code-review # 4. add it to your cuecard
|
|
85
|
+
claude # 5. launch — your cuecard is loaded
|
|
112
86
|
```
|
|
113
87
|
|
|
114
|
-
|
|
115
|
-
> shim that hands off to `cue launch`. Skip it and `claude` just runs vanilla Claude Code.
|
|
116
|
-
|
|
117
|
-
Search. Install. Use. No config files to edit. Works the same with `codex`, `cursor`, `cline`, `gemini`, and five other agents.
|
|
88
|
+
Step 2 is the magic: it installs a tiny `~/.local/bin/claude` shim that hands off to `cue launch`. From then on, typing `claude` in any directory loads that directory's cuecard first, then starts the real Claude Code. Skip step 2 and `claude` just runs vanilla.
|
|
118
89
|
|
|
119
|
-
|
|
120
|
-
<img src="./docs/assets/demo.gif" alt="cuecards demo — discover, install, and launch a skill on a cuecard in 30 seconds" width="820" onerror="this.style.display='none'">
|
|
121
|
-
</p>
|
|
122
|
-
|
|
123
|
-
<p align="center">
|
|
124
|
-
<img src="./docs/assets/interactive-tui.svg" alt="cuecards interactive TUI — browse profiles, skills, and skill detail side by side" width="820">
|
|
125
|
-
</p>
|
|
126
|
-
|
|
127
|
-
<br>
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
## why cuecards — and how it compares.
|
|
132
|
-
|
|
133
|
-
- **Cut always-on context up to ~16×.** Skills, MCPs, and plugins scoped per directory, not globally loaded into every session — reproduce it with `cue cost --compare`.
|
|
134
|
-
- **Five-dimensional agents.** Persona + playbooks + quality gates + evals + failure loop. Composable expertise, not just a longer tool list.
|
|
135
|
-
- **One cuecard, ten agents.** The same `profile.yaml` materializes into Claude Code, Codex, Cursor, Cline, Gemini, Copilot, Windsurf, Roo, Amp, and Aider native formats.
|
|
136
|
-
|
|
137
|
-
| | cuecards | skillport / agent-skills-cli | Kiro Powers |
|
|
138
|
-
|---|---|---|---|
|
|
139
|
-
| Skills | ✅ | ✅ | ✅ |
|
|
140
|
-
| MCPs | ✅ | — | ✅ |
|
|
141
|
-
| Plugins | ✅ | — | — |
|
|
142
|
-
| Per-directory profiles | ✅ | — | ◐ (IDE-only) |
|
|
143
|
-
| Inheritance | ✅ | — | — |
|
|
144
|
-
| Persona / playbooks / gates / evals | ✅ | — | — |
|
|
145
|
-
| Multi-agent (Cursor/Cline/Copilot/etc.) | ✅ (10) | Claude only | IDE-only |
|
|
146
|
-
| CLI installer | ✅ | — | — |
|
|
147
|
-
| Failure-feedback loop | ✅ | — | — |
|
|
148
|
-
| Daemon required | None | None | IDE process |
|
|
149
|
-
|
|
150
|
-
cuecards is the only one that treats agent expertise as a composable, per-directory system.
|
|
151
|
-
|
|
152
|
-
<details>
|
|
153
|
-
<summary><b>More wins</b></summary>
|
|
154
|
-
|
|
155
|
-
<br>
|
|
156
|
-
|
|
157
|
-
- **Discover real skills, not awesome-lists.** `cue discover search` queries GitHub Code Search for `filename:SKILL.md`, scores results, maps each repo to a cuecard.
|
|
158
|
-
- **Install every CLI the cuecard needs in one command.** `cue cli install --all <cuecard>` auto-detects apt / brew / snap / pipx / npm per OS.
|
|
159
|
-
- **Block "done" claims with quality gates.** Stop-hook validators auto-run tests, lint, and build before the agent can declare a task complete.
|
|
160
|
-
- **Open safe, meaningful PRs on skill repos.** Built-in 90-day per-repo cooldown, 25-PRs/day cap, and `<!-- cue: ignore -->` opt-out marker.
|
|
161
|
-
- **Failure-feedback loop.** `cue failures --propose` reads recent session failures and asks Claude to draft profile improvements.
|
|
162
|
-
|
|
163
|
-
</details>
|
|
164
|
-
|
|
165
|
-
<br>
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## the catalog.
|
|
170
|
-
|
|
171
|
-
> One repo. 69 pre-built expert agents. Pin one with `cue use <name>` and `claude` launches with that cuecard's skills, MCPs, hooks, and commands materialized.
|
|
90
|
+
To pin a project to a profile:
|
|
172
91
|
|
|
173
92
|
```bash
|
|
174
|
-
|
|
175
|
-
cue
|
|
176
|
-
|
|
177
|
-
claude # launches with that cuecard's loadout
|
|
93
|
+
cd ~/projects/my-shop
|
|
94
|
+
cue use medusa-dev # writes .cue.profile in this directory
|
|
95
|
+
claude # launches with the medusa-dev loadout
|
|
178
96
|
```
|
|
179
97
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
| Profile | What it's for |
|
|
183
|
-
|---|---|
|
|
184
|
-
| 🐢 **core** | Baseline shared by every cue profile — essentials only |
|
|
185
|
-
| 🦄 **full** | Diagnostic fallback that loads every local skill and MCP |
|
|
186
|
-
|
|
187
|
-
### Backend & Languages
|
|
188
|
-
|
|
189
|
-
| Profile | What it's for |
|
|
190
|
-
|---|---|
|
|
191
|
-
| 🐻 **backend** | APIs, webhooks, security review, CI, packaging, database, deploy |
|
|
192
|
-
| 🐹 **go-api** | Go API development — net/http, gin/echo/chi, GORM, testing |
|
|
193
|
-
| 🐍 **python** | FastAPI/Django/Flask APIs, SQLAlchemy/Alembic, pytest |
|
|
194
|
-
| 🦀 **rust** | All-in-one Rust — async, web, CLI/TUI, embedded, FFI, WASM, perf |
|
|
98
|
+
Not sure which profile fits? `cue auto-detect` reads your project (package.json, pyproject.toml, Cargo.toml, …) and suggests one.
|
|
195
99
|
|
|
196
|
-
|
|
100
|
+
---
|
|
197
101
|
|
|
198
|
-
|
|
199
|
-
|---|---|
|
|
200
|
-
| 🦋 **frontend** | Frontend UI implementation, redesign, screenshots, testing |
|
|
201
|
-
| ▲ **nextjs** | Next.js full-stack — App Router, Server Components, Vercel |
|
|
202
|
-
| ⚡ **vite** | Vite + React + TanStack ecosystem |
|
|
203
|
-
| 🎲 **threejs** | Three.js 3D — geometry, materials, shaders, animation |
|
|
102
|
+
## 69 ready-made cuecards
|
|
204
103
|
|
|
205
|
-
|
|
104
|
+
cue ships with pre-built profiles for common stacks and workflows. A taste:
|
|
206
105
|
|
|
207
106
|
| Profile | What it's for |
|
|
208
107
|
|---|---|
|
|
209
|
-
|
|
|
210
|
-
|
|
|
211
|
-
|
|
|
212
|
-
|
|
|
213
|
-
|
|
|
214
|
-
|
|
|
215
|
-
|
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
|
|
|
108
|
+
| 🐢 **core** | Minimal baseline shared by every profile |
|
|
109
|
+
| 🐻 **backend** | APIs, webhooks, security review, CI, databases, deploys |
|
|
110
|
+
| 🦋 **frontend** | UI implementation, redesigns, screenshots, browser testing |
|
|
111
|
+
| ▲ **nextjs** | Next.js App Router, Server Components, Vercel |
|
|
112
|
+
| 🐍 **python** | FastAPI/Django/Flask, SQLAlchemy, pytest |
|
|
113
|
+
| 🦀 **rust** | Async, web, CLI/TUI, embedded, FFI, WASM |
|
|
114
|
+
| 🦊 **medusa-dev** | Medusa v2 backend, storefront, admin |
|
|
115
|
+
| 🔒 **cybersecurity** | 754 red/blue-team skills + audit tooling |
|
|
116
|
+
| 🦜 **marketing** | Copywriting, SEO, CRO, growth |
|
|
117
|
+
| 🐝 **docs-writer** | Documentation, Markdown, PDF, structured writing |
|
|
118
|
+
| 🏢 **agency** | 63 delegatable subagents — design, sales, product, PM, QA |
|
|
219
119
|
|
|
220
|
-
|
|
120
|
+
```bash
|
|
121
|
+
cue list # see all 69
|
|
122
|
+
cue auto-detect # suggest the right one for the current directory
|
|
123
|
+
cue use <name> # pin it
|
|
124
|
+
```
|
|
221
125
|
|
|
222
|
-
|
|
126
|
+
Full machine-readable catalog: [docs/data/profiles.md](https://github.com/opencue/cuecards/blob/main/docs/data/profiles.md). Nothing fits? `cue ai "describe your stack"` scaffolds a new one.
|
|
223
127
|
|
|
224
128
|
---
|
|
225
129
|
|
|
226
|
-
##
|
|
130
|
+
## One cuecard, ten agents
|
|
227
131
|
|
|
228
|
-
The same `profile.yaml` materializes into each agent's native format —
|
|
132
|
+
The same `profile.yaml` materializes into each agent's native config format — write your setup once, use it everywhere:
|
|
229
133
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
</p>
|
|
134
|
+
| Agent | Output |
|
|
135
|
+
|---|---|
|
|
136
|
+
| Claude Code / Codex | runtime dirs under `~/.config/cue/runtime/` (via the shim) |
|
|
137
|
+
| Cursor | `.cursorrules` + `.cursor/mcp.json` |
|
|
138
|
+
| Cline | `.clinerules` + `cline_mcp_settings.json` |
|
|
139
|
+
| Gemini CLI | `~/.gemini/skills/*.md` |
|
|
140
|
+
| GitHub Copilot | `.github/copilot-instructions.md` |
|
|
141
|
+
| Windsurf | `.windsurfrules` + `.windsurf/mcp.json` |
|
|
142
|
+
| Roo Code | `.roo/rules/*.md` + `.roo/mcp.json` |
|
|
143
|
+
| Sourcegraph Amp | `AGENTS.md` + `.amp/mcp.json` |
|
|
144
|
+
| Aider | `.aider.conventions.md` |
|
|
242
145
|
|
|
243
146
|
```bash
|
|
244
|
-
cue materialize cursor --profile backend
|
|
245
|
-
cue materialize --all --profile backend
|
|
147
|
+
cue materialize cursor --profile backend # one agent
|
|
148
|
+
cue materialize --all --profile backend # all ten at once
|
|
246
149
|
```
|
|
247
150
|
|
|
248
|
-
<details>
|
|
249
|
-
<summary><b>Full materialization matrix</b></summary>
|
|
250
|
-
|
|
251
|
-
| Agent | `cue materialize` command | Output |
|
|
252
|
-
|---|---|---|
|
|
253
|
-
| Claude Code | (default — shim) | `~/.config/cue/runtime/<profile>/claude/` |
|
|
254
|
-
| OpenAI Codex | (default — shim) | `~/.config/cue/runtime/<profile>/codex/` |
|
|
255
|
-
| Cursor | `cue materialize cursor` | `.cursorrules` · `.cursor/mcp.json` |
|
|
256
|
-
| Cline | `cue materialize cline` | `.clinerules` · `cline_mcp_settings.json` |
|
|
257
|
-
| Gemini CLI | `cue materialize gemini` | `~/.gemini/skills/*.md` |
|
|
258
|
-
| GitHub Copilot | `cue materialize copilot` | `.github/copilot-instructions.md` |
|
|
259
|
-
| Windsurf | `cue materialize windsurf` | `.windsurfrules` · `.windsurf/mcp.json` |
|
|
260
|
-
| Roo Code | `cue materialize roo` | `.roo/rules/*.md` · `.roo/mcp.json` |
|
|
261
|
-
| Sourcegraph Amp | `cue materialize amp` | `AGENTS.md` · `.amp/mcp.json` |
|
|
262
|
-
| Aider | `cue materialize aider` | `.aider.conventions.md` |
|
|
263
|
-
|
|
264
|
-
</details>
|
|
265
|
-
|
|
266
|
-
<br>
|
|
267
|
-
|
|
268
151
|
---
|
|
269
152
|
|
|
270
|
-
##
|
|
153
|
+
## Built-in rigor
|
|
271
154
|
|
|
272
155
|
cuecards don't just load tools — they hold your agent to a standard.
|
|
273
156
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
cuecards can ship an **independent review gate**. When the agent finishes a
|
|
277
|
-
code-producing turn in a cuecard that enables it, cue spawns a *fresh, separate*
|
|
278
|
-
reviewer agent over the working-tree diff **before the turn is allowed to finish**.
|
|
157
|
+
**The reviewer gate.** Profiles can enable an independent review gate: when the agent finishes a code-producing turn, cue spawns a *fresh, separate* reviewer agent over the diff before the turn is allowed to finish. A real catch from a live session: the reviewer flagged a unit bug where a product's `weight` was kilograms in one place and grams in two others — left in, carts would have displayed `20000 kg`. The gate held the merge until it was fixed.
|
|
279
158
|
|
|
280
|
-
|
|
281
|
-
a product's `weight` was treated as kilograms in one place but grams in two others
|
|
282
|
-
(`weight >= 1000 ? kg : g`). Left in, the per-kg price renders as `€0.00` and a cart
|
|
283
|
-
reads `20000 kg`. The gate held the merge until it was fixed.
|
|
159
|
+
Enable it with `touch ~/.config/cue/auto-review-enabled`, watch reviews live with `cue-review-watch`, and skip one turn with `[skip-auto-review]`. Details: [docs/review-visibility.md](https://github.com/opencue/cuecards/blob/main/docs/review-visibility.md).
|
|
284
160
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
- **A red "Stop hook error" is the gate working, not a failure.** Claude Code renders
|
|
288
|
-
any *blocking* hook that way. It means the reviewer found a CRITICAL/HIGH issue and is
|
|
289
|
-
holding the turn until you address it. It caps at 2 rounds, then releases. Suppress it
|
|
290
|
-
for one turn with `[skip-auto-review]` in your message; turn it off entirely with
|
|
291
|
-
`rm ~/.config/cue/auto-review-enabled`.
|
|
292
|
-
- **You can watch the review live.** Run `cue-review-watch` in a second pane to see it
|
|
293
|
-
move file-by-file with findings as they land:
|
|
294
|
-
|
|
295
|
-
```
|
|
296
|
-
16:42:03 📄 setup-plate-variants.ts
|
|
297
|
-
16:42:03 → unit convention
|
|
298
|
-
16:42:09 🔴 CRITICAL weight kg/g ambiguity → per-kg price shows €0.00
|
|
299
|
-
16:45:30 ✅ review complete 1 CRITICAL
|
|
300
|
-
```
|
|
161
|
+
**Confidence tags.** cue-managed agents tag research- and decision-relevant claims with colored confidence markers so you can scan trust at a glance:
|
|
301
162
|
|
|
302
|
-
|
|
303
|
-
[`docs/review-visibility.md`](./docs/review-visibility.md).
|
|
304
|
-
|
|
305
|
-
### Confidence tags
|
|
306
|
-
|
|
307
|
-
cuecards-managed agents tag every research- or decision-relevant claim with a colored confidence marker so you can scan trust at a glance:
|
|
308
|
-
|
|
309
|
-
| Tier | Tag | Meaning |
|
|
163
|
+
| Tier | Tags | Meaning |
|
|
310
164
|
|---|---|---|
|
|
311
|
-
| 🟢
|
|
312
|
-
| 🟡
|
|
313
|
-
| 🟠
|
|
314
|
-
| 🔴
|
|
315
|
-
|
|
316
|
-
Optional decile calibration on yellow/orange: `🟡 [INFERRED ~80%]`, `🟠 [GUESSED ~30%]`. The `~` signals it's a rough self-estimate, not a true probability. Full system: **[`integrity-tags/SKILL.md`](./resources/skills/skills/meta/integrity-tags/SKILL.md)** · canonical protocol auto-injected into every profile via `persona_includes`.
|
|
317
|
-
|
|
318
|
-
<br>
|
|
165
|
+
| 🟢 | `[VERIFIED]` `[KNOWN]` | Checked firsthand / well-documented fact |
|
|
166
|
+
| 🟡 | `[INFERRED]` `[ASSUMED]` | Deduced or assumed — verify if stakes matter |
|
|
167
|
+
| 🟠 | `[GUESSED]` `[STALE]` | Pattern-match or possibly outdated — verify first |
|
|
168
|
+
| 🔴 | `[UNKNOWN]` | The agent said "I don't know" instead of making it up |
|
|
319
169
|
|
|
320
170
|
---
|
|
321
171
|
|
|
322
|
-
##
|
|
172
|
+
## Everyday commands
|
|
323
173
|
|
|
324
174
|
```bash
|
|
325
|
-
#
|
|
326
|
-
cue use <profile>
|
|
327
|
-
cue list
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
cue cost
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
cue
|
|
336
|
-
cue install <
|
|
337
|
-
cue
|
|
338
|
-
|
|
339
|
-
#
|
|
340
|
-
cue
|
|
341
|
-
cue
|
|
342
|
-
cue
|
|
343
|
-
cue failures --propose [profile] # Claude drafts profile improvements
|
|
344
|
-
|
|
345
|
-
# Audit
|
|
346
|
-
cue optimizer # dashboard: skills, MCPs, CLIs, usage per profile
|
|
347
|
-
cue doctor --fix # diff declared vs actual state, auto-repair
|
|
175
|
+
# Profiles
|
|
176
|
+
cue use <profile> # pin a profile to this directory
|
|
177
|
+
cue list # all available profiles
|
|
178
|
+
cue auto-detect # suggest one for the current project
|
|
179
|
+
|
|
180
|
+
# Cost
|
|
181
|
+
cue cost # token budget for the active profile
|
|
182
|
+
cue cost --compare # all profiles ranked vs `full`
|
|
183
|
+
|
|
184
|
+
# Skills & discovery
|
|
185
|
+
cue discover search <query> # find skills on GitHub
|
|
186
|
+
cue discover install <skill> # install one
|
|
187
|
+
cue lint-skill <path> --fix # validate a SKILL.md
|
|
188
|
+
|
|
189
|
+
# Health
|
|
190
|
+
cue doctor --fix # diff declared vs actual state, auto-repair
|
|
191
|
+
cue optimizer # dashboard: skills, MCPs, CLIs, usage per profile
|
|
192
|
+
cue failures --propose # let Claude draft profile improvements from failures
|
|
348
193
|
```
|
|
349
194
|
|
|
350
|
-
`cue --help` shows the full ~50-subcommand surface
|
|
351
|
-
|
|
352
|
-
<br>
|
|
195
|
+
`cue --help` shows the full ~50-subcommand surface; the set above covers a typical week.
|
|
353
196
|
|
|
354
197
|
---
|
|
355
198
|
|
|
356
|
-
##
|
|
357
|
-
|
|
358
|
-
```bash
|
|
359
|
-
npm install -g cue-ai
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
Then activate the shim once, and pin a profile in any project:
|
|
363
|
-
|
|
364
|
-
```bash
|
|
365
|
-
cue shell install # one-time: installs the claude shim (--codex for codex)
|
|
366
|
-
cd ~/projects/q4-launch
|
|
367
|
-
echo marketing > .cue-profile
|
|
368
|
-
claude # launches with the marketing cuecard
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
<details>
|
|
372
|
-
<summary><b>Other install paths</b></summary>
|
|
199
|
+
## Install options
|
|
373
200
|
|
|
374
201
|
| Path | Command |
|
|
375
202
|
|---|---|
|
|
203
|
+
| npm (recommended) | `npm install -g cue-ai` |
|
|
376
204
|
| One-line script | `curl -fsSL https://raw.githubusercontent.com/opencue/cuecards/main/get.sh \| bash` |
|
|
377
|
-
| Manual clone | `git clone https://github.com/opencue/cuecards.git
|
|
378
|
-
|
|
|
379
|
-
| Per-OS bootstrap (full stack) | paste [`setup/macos.md`](./setup/macos.md) · [`setup/linux.md`](./setup/linux.md) · [`setup/windows.md`](./setup/windows.md) into Claude Code |
|
|
205
|
+
| Manual clone | `git clone https://github.com/opencue/cuecards.git && ./cuecards/install.sh` |
|
|
206
|
+
| Guided (paste into Claude Code) | [setup/macos.md](https://github.com/opencue/cuecards/blob/main/setup/macos.md) · [setup/linux.md](https://github.com/opencue/cuecards/blob/main/setup/linux.md) · [setup/windows.md](https://github.com/opencue/cuecards/blob/main/setup/windows.md) |
|
|
380
207
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
`install.sh --help` lists `--yes`, `--codex`, `--uninstall`. Idempotent — safe to re-run.
|
|
384
|
-
|
|
385
|
-
<br>
|
|
208
|
+
All paths are idempotent — safe to re-run. `install.sh --help` lists `--yes`, `--codex`, `--uninstall`.
|
|
386
209
|
|
|
387
210
|
---
|
|
388
211
|
|
|
389
|
-
## FAQ
|
|
212
|
+
## FAQ
|
|
390
213
|
|
|
391
214
|
<details>
|
|
392
215
|
<summary><b>Does this break Claude Code's auto-update?</b></summary>
|
|
393
216
|
|
|
394
|
-
No. cue
|
|
217
|
+
No. cue never touches the `claude` binary — it intercepts the *call* via a one-line bash shim in `~/.local/bin/claude`, sets `CLAUDE_CONFIG_DIR`, and `exec`s the real binary. Updates work exactly as before.
|
|
395
218
|
</details>
|
|
396
219
|
|
|
397
220
|
<details>
|
|
398
221
|
<summary><b>Is this a daemon?</b></summary>
|
|
399
222
|
|
|
400
|
-
No. Pure CLI. When you type `claude`, the shim runs `cue launch`,
|
|
223
|
+
No. Pure CLI. When you type `claude`, the shim runs `cue launch`, compares a sha256, materializes only if something changed, then `exec`s. Nothing stays resident.
|
|
401
224
|
</details>
|
|
402
225
|
|
|
403
226
|
<details>
|
|
404
|
-
<summary><b>How
|
|
227
|
+
<summary><b>How much overhead does it add?</b></summary>
|
|
405
228
|
|
|
406
|
-
Cold start
|
|
229
|
+
Cold start 50–200 ms; warm start under 5 ms. Imperceptible next to your agent's own startup.
|
|
407
230
|
</details>
|
|
408
231
|
|
|
409
232
|
<details>
|
|
410
233
|
<summary><b>Does cue send telemetry?</b></summary>
|
|
411
234
|
|
|
412
|
-
No. Everything cue computes
|
|
235
|
+
No. Everything cue computes — including the per-skill usage bars in `cue optimizer` — reads from your local transcript files. Nothing leaves your machine.
|
|
413
236
|
</details>
|
|
414
237
|
|
|
415
238
|
<details>
|
|
416
239
|
<summary><b>What does cue NOT do?</b></summary>
|
|
417
240
|
|
|
418
|
-
- It
|
|
419
|
-
- It
|
|
420
|
-
- It
|
|
421
|
-
|
|
241
|
+
- It doesn't modify or repackage the Claude Code / Codex binaries.
|
|
242
|
+
- It doesn't host a remote marketplace — skills live in your repo or come from open source.
|
|
243
|
+
- It doesn't coordinate multi-agent runs (that's [colony](https://github.com/recodeee/colony) + [gitguardex](https://github.com/recodeee/gitguardex), layered on top via the parallel-agents tier).
|
|
422
244
|
</details>
|
|
423
245
|
|
|
424
|
-
<br>
|
|
425
|
-
|
|
426
246
|
---
|
|
427
247
|
|
|
428
|
-
##
|
|
429
|
-
|
|
430
|
-
cuecards.cc has free public accounts and per-user API tokens. Register in the
|
|
431
|
-
**API tokens** view, mint a token (shown once), and call the API with a Bearer
|
|
432
|
-
header:
|
|
433
|
-
|
|
434
|
-
```bash
|
|
435
|
-
curl https://cuecards.cc/api/v1/me \
|
|
436
|
-
-H "Authorization: Bearer <your-token>"
|
|
437
|
-
# -> { "ok": true, "data": { "id": "...", "email": "...", "name": "..." } }
|
|
438
|
-
```
|
|
248
|
+
## How it compares
|
|
439
249
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
250
|
+
| | cuecards | skillport / agent-skills-cli | Kiro Powers |
|
|
251
|
+
|---|---|---|---|
|
|
252
|
+
| Skills | ✅ | ✅ | ✅ |
|
|
253
|
+
| MCPs | ✅ | — | ✅ |
|
|
254
|
+
| Plugins | ✅ | — | — |
|
|
255
|
+
| Per-directory profiles | ✅ | — | ◐ (IDE-only) |
|
|
256
|
+
| Inheritance | ✅ | — | — |
|
|
257
|
+
| Persona / playbooks / gates | ✅ | — | — |
|
|
258
|
+
| Multi-agent (Cursor/Cline/Copilot/…) | ✅ (10) | Claude only | IDE-only |
|
|
259
|
+
| Failure-feedback loop | ✅ | — | — |
|
|
260
|
+
| Daemon required | none | none | IDE process |
|
|
445
261
|
|
|
446
262
|
---
|
|
447
263
|
|
|
448
|
-
##
|
|
449
|
-
|
|
450
|
-
The bits that didn't fit on the landing page:
|
|
264
|
+
## Deep dives
|
|
451
265
|
|
|
452
266
|
| Topic | Read |
|
|
453
267
|
|---|---|
|
|
454
|
-
| Launch flow (resolve → materialize → exec) | [
|
|
455
|
-
|
|
|
456
|
-
| Bootstrap contract for AI agents installing cue | [
|
|
457
|
-
| Parallel agents tier (Colony + gitguardex) | [
|
|
458
|
-
| Confidence-tag system
|
|
459
|
-
|
|
460
|
-
<sub>Topics like the 5-dimensional expert agent model, system CLI installer mechanics, marketplace discovery, SKILL.md linter rules, and the `cue optimizer` dashboard are tracked in git history at the old README until they get their own pages — `git log --diff-filter=D -- README.md` finds them.</sub>
|
|
461
|
-
|
|
462
|
-
<br>
|
|
463
|
-
|
|
464
|
-
---
|
|
465
|
-
|
|
466
|
-
## who uses cue.
|
|
467
|
-
|
|
468
|
-
| Project | Profile | What they do |
|
|
469
|
-
|---|---|---|
|
|
470
|
-
| [opencue/cuecards](https://github.com/opencue/cuecards) | `full`, `skill-writer` | Dogfooding cue on itself |
|
|
471
|
-
| [recodeee/colony](https://github.com/recodeee/colony) | `fleet-control` | Multi-agent coordination MCP |
|
|
472
|
-
| [recodeee/gitguardex](https://github.com/recodeee/gitguardex) | `backend` | Branch + worktree isolation for parallel agents |
|
|
473
|
-
|
|
474
|
-
> **Using cue?** Open a PR or drop a link in [Discussions](https://github.com/opencue/cuecards/discussions).
|
|
475
|
-
|
|
476
|
-
<br>
|
|
477
|
-
|
|
478
|
-
---
|
|
479
|
-
|
|
480
|
-
## star history.
|
|
481
|
-
|
|
482
|
-
<a href="https://star-history.com/#opencue/cuecards&Date">
|
|
483
|
-
<picture>
|
|
484
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date&theme=dark" />
|
|
485
|
-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date" />
|
|
486
|
-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date" width="720" />
|
|
487
|
-
</picture>
|
|
488
|
-
</a>
|
|
489
|
-
|
|
490
|
-
<br>
|
|
268
|
+
| Launch flow (resolve → materialize → exec) | [docs/launch.md](https://github.com/opencue/cuecards/blob/main/docs/launch.md) |
|
|
269
|
+
| Full profile catalog | [docs/data/profiles.md](https://github.com/opencue/cuecards/blob/main/docs/data/profiles.md) |
|
|
270
|
+
| Bootstrap contract for AI agents installing cue | [AGENTS.md](https://github.com/opencue/cuecards/blob/main/AGENTS.md) |
|
|
271
|
+
| Parallel agents tier (Colony + gitguardex) | [setup/parallel-agents.md](https://github.com/opencue/cuecards/blob/main/setup/parallel-agents.md) |
|
|
272
|
+
| Confidence-tag system | [integrity-tags/SKILL.md](https://github.com/opencue/cuecards/blob/main/resources/skills/skills/meta/integrity-tags/SKILL.md) |
|
|
491
273
|
|
|
492
274
|
---
|
|
493
275
|
|
|
494
|
-
##
|
|
276
|
+
## Contributing
|
|
495
277
|
|
|
496
278
|
```bash
|
|
497
279
|
git clone https://github.com/opencue/cuecards.git
|
|
498
|
-
cd
|
|
499
|
-
bun test
|
|
500
|
-
bun run src/index.ts --help
|
|
280
|
+
cd cuecards && bun install
|
|
281
|
+
bun test # tests (lib + commands)
|
|
282
|
+
bun run src/index.ts --help # run locally
|
|
501
283
|
```
|
|
502
284
|
|
|
503
285
|
| Want to | Run |
|
|
504
286
|
|---|---|
|
|
505
|
-
| Add a skill | `cue skills-new <name
|
|
506
|
-
| Add a profile | `cue new <name
|
|
287
|
+
| Add a skill | `cue skills-new <name>`, then edit `resources/skills/skills/<category>/<name>/SKILL.md` |
|
|
288
|
+
| Add a profile | `cue new <name>`, then `cue validate <name>` |
|
|
507
289
|
| Share your profile | `cue share publish --profile <name>` |
|
|
508
290
|
| Report a bug | [Open an issue](https://github.com/opencue/cuecards/issues) |
|
|
509
291
|
|
|
510
|
-
License: [MIT](
|
|
292
|
+
License: [MIT](https://github.com/opencue/cuecards/blob/main/LICENSE) · zero telemetry · no daemon
|