convez.ai
MCP ServerAutomaçãoIntermediário
opencue

cuecards — Gerenciador de Perfis de Agentes IA

opencue/cuecards

Configure agentes IA por projeto com cuecards — skills, MCPs e personas automáticos

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que funciona como um gerenciador de perfis por diretório para agentes de IA (Claude Code, Cursor, Cline, GitHub Copilot e similares). Define automaticamente quais skills, servidores MCP, plugins e personas carregam antes do lançamento, reduzindo custos de token em até 25×.

Instalação

$npx convez-ai opencue/cuecards

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
1
Acompanhando
0
Saúde
50%
Último commit
há 1 dia
Versão
v0.9.4
Issues abertas
0
Contribuidores
3

Casos de uso

  • Configurar diferentes ambientes de desenvolvimento com agentes especializados
  • Reduzir custo de processamento de tokens em projetos com contexto pesado
  • Automatizar setup de skills e extensões ao entrar em um diretório

Veredito

Solução técnica sólida para quem usa múltiplos agentes IA e precisa de contexto dinâmico por projeto. Reduz friction operacional e custos reais — recomendado para times de desenvolvimento que trabalham com Claude Code ou similares.

README

A tradução para o português deste README ainda está na fila.


what is a cuecard.

A cuecard is everything your AI coding agent needs to be useful in one directory — the skills it loads, the MCP servers it connects to, the plugins it boots with, the persona it adopts, the playbooks it follows, the quality gates that block its "done" claim.

One cuecard per project. Your agent reads the right one the moment you launch.

layerwhat's on the cuecard
skillsonly the ones this project actually needs
MCPsscoped per directory, no global sprawl
pluginsthe Claude Code plugins this project wants — no more
personahow the agent thinks, writes, and self-edits
playbooksthe steps the agent follows for known tasks
gateswhat must pass before the agent says "done"

quickstart.

npm install -g cue-ai                          # 1. install
cue shell install                              # 2. activate the claude shim (one-time; --codex adds codex)
cue discover search "code review"              # 3. find a skill
cue discover install review/code-review        # 4. add it
claude                                         # 5. launch — the cuecard is loaded

Step 2 is what makes claude load your cuecard: it installs a ~/.local/bin/claude shim that hands off to cue launch. Skip it and claude just runs vanilla Claude Code.

Search. Install. Use. No config files to edit. Works the same with codex, cursor, cline, gemini, and five other agents.


works with.


by the numbers.


the money shot.

Loading everything costs you tokens on every single message. cuecards cut your always-on context ~9–16× — and you can reproduce every number below with cue cost --compare.

LoadoutAlways-on contextCost / 100 msgs (Sonnet input)
Without cuecards — full (every skill + MCP)~81k tokens~$24 😱
With cuecards — backend profile~9k tokens~$2.70 ✅
With cuecards — caveman-quick~6.8k tokens~$2.00 🚀

That's ~9× fewer always-on tokens on a backend loadout (≈12× on caveman-quick, up to ≈16× on the leanest profiles) versus loading everything. Your model also picks the right tool faster because it's not scanning irrelevant descriptions on every message.

cue cost                      # token budget for your active profile
cue cost --compare            # full table: every profile ranked vs the `full` baseline

why cuecards.

  • 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.
  • Five-dimensional agents. Persona + playbooks + quality gates + evals + failure loop. Not just "more tools loaded" — composable expertise.
  • One cuecard, ten agents. The same profile.yaml materializes into Claude Code, Codex, Cursor, Cline, Gemini, Copilot, Windsurf, Roo, Amp, and Aider native formats.
  • 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.
  • Install every CLI the cuecard needs in one command. cue cli install --all <cuecard> auto-detects apt / brew / snap / pipx / npm per OS.
  • Block "done" claims with quality gates. Stop-hook validators auto-run tests, lint, and build before the agent can declare a task complete.
  • Open safe, meaningful PRs on skill repos. Built-in 90-day per-repo cooldown, 25-PRs/day cap, and <!-- cue: ignore --> opt-out marker.
  • Failure-feedback loop. cue failures --propose reads recent session failures and asks Claude to draft profile improvements.

reading cue's output — the colored tags.

cuecards-managed agents tag every research- or decision-relevant claim with a colored confidence marker so you can scan trust at a glance:

TierTagMeaning
🟢 Green[VERIFIED] / [KNOWN]Trust it (~90–99%)
🟡 Yellow[INFERRED] / [ASSUMED]Verify if stakes matter (~50–85%)
🟠 Orange[GUESSED] / [STALE]Verify before acting (~20–45%)
🔴 Red[UNKNOWN]Don't trust; agent refused to fabricate

Optional decile calibration on yellow/orange: 🟡 [INFERRED ~80%], 🟠 [GUESSED ~30%]. The ~ signals it's a rough self-estimate, not a true probability.

Full system + when each tag fires: resources/skills/skills/meta/integrity-tags/SKILL.md · Canonical protocol: resources/personas/integrity-protocol.md (auto-injected into every profile via persona_includes).


what you'll see during a run — the reviewer.

cuecards can ship an independent review gate. When the agent finishes a code-producing turn in a cuecard that enables it, cue spawns a fresh, separate reviewer agent over the working-tree diff before the turn is allowed to finish. It runs as a normal step of a Claude Code run — so expect to see a reviewer agent think for a while (a deep pass can run many minutes and tens of thousands of tokens). This is by design, and it earns its keep.

A real catch from a live session: the reviewer flagged a load-bearing unit bug — a product's weight was treated as kilograms in one place but grams in two others (weight >= 1000 ? kg : g). Left in, the per-kg price renders as €0.00 and a cart reads 20000 kg. The gate held the merge until it was fixed.

Two things so the behavior isn't surprising:

  • A red "Stop hook error" is the gate working, not a failure. Claude Code renders any blocking hook that way. It means the reviewer found a CRITICAL/HIGH issue and is holding the turn until you address it. It caps at 2 rounds, then releases. Suppress it for one turn with [skip-auto-review] in your message; turn it off entirely with rm ~/.config/cue/auto-review-enabled.
  • You can watch the review live. A long review otherwise shows only a spinner. Run cue-review-watch in a second pane to see it move file-by-file with findings as they land:
16:42:03  📄 setup-plate-variants.ts
16:42:03     → unit convention
16:42:09     🔴 CRITICAL  weight kg/g ambiguity → per-kg price shows €0.00
16:45:30  ✅ review complete  1 CRITICAL

Enable the gate with touch ~/.config/cue/auto-review-enabled. Full details: docs/review-visibility.md.


the catalog.

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.

cue list                      # show everything
cue auto-detect               # suggest the right one for cwd
cue use medusa-dev            # pin to current directory
claude                        # launches with that cuecard's loadout

Foundation

ProfileWhat it's for
🐢 coreBaseline shared by every cue profile — essentials only
🦄 fullDiagnostic fallback that loads every local skill and MCP

Backend & Languages

ProfileWhat it's for
🐻 backendAPIs, webhooks, security review, CI, packaging, database, deploy
🐹 go-apiGo API development — net/http, gin/echo/chi, GORM, testing
🐍 pythonFastAPI/Django/Flask APIs, SQLAlchemy/Alembic, pytest
🦀 rustAll-in-one Rust — async, web, CLI/TUI, embedded, FFI, WASM, perf

Frontend

ProfileWhat it's for
🦋 frontendFrontend UI implementation, redesign, screenshots, testing
▲ nextjsNext.js full-stack — App Router, Server Components, Vercel
⚡ viteVite + React + TanStack ecosystem
🎲 threejsThree.js 3D — geometry, materials, shaders, animation

Security · Media · Growth · Verticals

ProfileWhat it's for
🔒 cybersecurity754 red/blue team skills + agentshield auditor
🦉 researchSource-backed lookup, extraction, browser/market research
🦚 creative-mediaImage, video, product asset, brand workflows
🎬 videoFrame extraction, audio transcription, visual understanding
🐝 docs-writerDocumentation, Markdown, PDF, Obsidian, structured writing
🦜 marketingCopywriting, SEO, CRO, growth, channels, X/Twitter automation
💼 careerJob hunting, resume, interview prep, salary negotiation
🦊 medusa-devMedusa v2 backend, storefront, admin, migration
🐺 fleet-controlMulti-agent orchestration, Colony coordination, gx safety
🏢 agencyA full agency on tap — 63 delegatable subagents (design, sales, product, PM, finance, game dev, XR, paid media, QA)

Full machine-readable list (all 69): docs/data/profiles.md. Don't see a fit? Run cue auto-detect or cue ai "describe your stack" to scaffold a new one.


one cuecard, every agent.

The same profile.yaml materializes into each agent's native format — .cursorrules, .clinerules, ~/.gemini/skills/*.md, .github/copilot-instructions.md, etc.

cue materialize cursor --profile backend     # → .cursorrules + .cursor/mcp.json
cue materialize --all --profile backend      # → all 10 agents at once
Agentcue materialize commandOutput
Claude Code(default — shim)~/.config/cue/runtime/<profile>/claude/
OpenAI Codex(default — shim)~/.config/cue/runtime/<profile>/codex/
Cursorcue materialize cursor.cursorrules · .cursor/mcp.json
Clinecue materialize cline.clinerules · cline_mcp_settings.json
Gemini CLIcue materialize gemini~/.gemini/skills/*.md
GitHub Copilotcue materialize copilot.github/copilot-instructions.md
Windsurfcue materialize windsurf.windsurfrules · .windsurf/mcp.json
Roo Codecue materialize roo.roo/rules/*.md · .roo/mcp.json
Sourcegraph Ampcue materialize ampAGENTS.md · .amp/mcp.json
Aidercue materialize aider.aider.conventions.md

daily commands.

# Pick a profile
cue use <profile>             # switch profile for this directory
cue list                      # see all available profiles

# Measure
cue cost                      # token budget for active profile
cue cost --compare            # every profile ranked vs the `full` baseline

# System dependencies
cue cli install --all --yes   # install every missing CLI
cue install <profile>         # dry-run: prepare Claude/Codex runtimes
cue install <profile> --with-clis --yes
cue install repo owner/repo --profile <profile> --yes

# Quality + discovery
cue lint-skill <path> [--fix]            # validate SKILL.md against R001-R008
cue marketplace discover --cli-aware     # find skill repos on GitHub
cue install doctor --all-profiles        # audit prepared runtimes
cue failures --propose [profile]         # Claude drafts profile improvements

# Audit
cue optimizer                 # dashboard: skills, MCPs, CLIs, usage per profile
cue doctor --fix              # diff declared vs actual state, auto-repair

cue --help shows the full ~50-subcommand surface. The set above covers everything you'll touch weekly.


install.

npm install -g cue-ai

Then activate the shim once, and pin a profile in any project:

cue shell install             # one-time: installs the claude shim (--codex for codex)
cd ~/projects/q4-launch
echo marketing > .cue-profile
claude                        # launches with the marketing cuecard
PathCommand
One-line scriptcurl -fsSL https://raw.githubusercontent.com/opencue/cuecards/main/get.sh | bash
Manual clonegit clone https://github.com/opencue/cuecards.git ~/Documents/cue && ~/Documents/cue/install.sh
Lean stack (core + caveman + RTK only, cross-OS)paste setup/lean-cue.md into Claude Code
Per-OS bootstrap (full stack)paste setup/macos.md · setup/linux.md · setup/windows.md into Claude Code

install.sh --help lists --yes, --codex, --uninstall. Idempotent — safe to re-run.


FAQ.

No. cue doesn't touch the claude binary — it intercepts the call via a one-line bash shim in ~/.local/bin/claude, sets CLAUDE_CONFIG_DIR, and execs the real binary. Claude Code's update mechanism still runs identically.

No. Pure CLI. When you type claude, the shim runs cue launch, does a sha256 compare, materializes only if anything changed, then execs. Nothing stays resident.

Cold start: 50–200 ms. Warm start: <5 ms (sha256 compare + exec). Imperceptible next to Claude Code's own startup.

No. Everything cue computes (including the per-skill usage bars in cue optimizer) reads from your local ~/.claude/projects/**/*.jsonl transcripts. Nothing leaves the machine.

cueskillport / agent-skills-cliKiro Powers
Skills✅✅✅
MCPs✅—✅
Plugins✅——
Per-directory profiles✅—◐ (IDE-only)
Inheritance✅——
Persona / playbooks / gates / evals✅——
Multi-agent (Cursor/Cline/Copilot/etc.)✅ (10)Claude onlyIDE-only
CLI installer✅——
Failure-feedback loop✅——
Daemon requiredNoneNoneIDE process

cuecards is the only one that treats agent expertise as a composable system.

  • It does not modify or repackage the Claude Code / Codex binary.
  • It does not host a remote skill marketplace — skills live in your repo or come from open-source sources.
  • It does not coordinate multi-agent runs (that's recodeee/colony + gitguardex, layered via the parallel-agents tier).

api.

cuecards.cc has free public accounts and per-user API tokens. Register in the API tokens view, mint a token (shown once), and call the API with a Bearer header:

curl https://cuecards.cc/api/v1/me \
  -H "Authorization: Bearer <your-token>"
# -> { "ok": true, "data": { "id": "...", "email": "...", "name": "..." } }

Auth is BetterAuth (email + password) on Vercel serverless functions backed by Neon Postgres. Setup, env vars, the migration, local dev, and deploy steps live in web/AUTH.md.


deep dives.

The bits that didn't fit on the landing page:

TopicRead
Launch flow (resolve → materialize → exec)docs/launch.md
Profile catalog (all 69, machine-readable)docs/data/profiles.md
Bootstrap contract for AI agents installing cueAGENTS.md
Parallel agents tier (Colony + gitguardex)setup/parallel-agents.md
Confidence-tag system ([VERIFIED], [INFERRED], [GUESSED], etc.)resources/skills/skills/meta/integrity-tags/SKILL.md

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.


who uses cue.

ProjectProfileWhat they do
opencue/cuecardsfull, skill-writerDogfooding cue on itself
recodeee/colonyfleet-controlMulti-agent coordination MCP
recodeee/gitguardexbackendBranch + worktree isolation for parallel agents

Using cue? Open a PR or drop a link in Discussions.


star history.


contributing.

git clone https://github.com/opencue/cuecards.git
cd cue && bun install
bun test                                      # tests (lib + commands)
bun run src/index.ts --help                   # run locally
Want toRun
Add a skillcue skills-new <name> then edit resources/skills/skills/<category>/<name>/SKILL.md
Add a profilecue new <name> then cue validate <name>
Share your profilecue share publish --profile <name>
Report a bugOpen an issue

License: MIT.

Ver o original no GitHub

Bom para

Relacionados