convez.ai
MCP ServerDesenvolvimento WebIntermediário
commontrace

CommonTrace Skill

commontrace/skill

Base de conhecimento compartilhada integrada ao Claude Code com zero configuração

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin MCP para Claude Code que integra uma base de conhecimento compartilhada (CommonTrace) diretamente no fluxo de codificação. Realiza buscas automáticas ao iniciar sessões, oferece comandos slash para pesquisa explícita e contribuição, e auto-submete soluções resolvidas para a base de conhecimento.

Instalação

$npx convez-ai commontrace/skill

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
2
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
v0.1
Issues abertas
1
Contribuidores
2

Casos de uso

  • Reutilizar soluções de problemas já resolvidos pela comunidade
  • Contribuir automaticamente traces de soluções para a base compartilhada
  • Visualizar padrões de dificuldades e aprendizados em gráficos locais
  • Pesquisar corrigências conhecidas para erros em tempo real

Veredito

Solução inovadora de knowledge base descentralizada com instalação zero-config e contribuição automática. Especialmente útil para equipes que querem compartilhar soluções sem overhead administrativo, embora dependa da maturidade e qualidade da comunidade CommonTrace.

README

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

CommonTrace Skill

Claude Code plugin for CommonTrace — integrates the shared knowledge base directly into your coding workflow.

What It Does

  • Zero-config onboarding — install the plugin, start a session; an anonymous account is provisioned automatically
  • Auto-searches CommonTrace at session start based on project context
  • Slash commands for explicit search and contribution
  • Skill guidance teaches Claude when and how to use the knowledge base
  • Auto-contributes resolved traces silently by default (auto mode); queues candidates to pending/ for manual review when auto_contribute: false
  • Local-first artifacts — brain graph, struggle grid, monthly recap; aggregate shapes only, generated on your machine

Install

claude plugin add commontrace@commontrace/skill

That's it. Your next Claude Code session sets everything up automatically:

  1. Creates an anonymous account (random ID, no personal data) and stores the API key at ~/.commontrace/config.json (mode 0600)
  2. Registers the MCP server (claude mcp add commontrace, user scope)
  3. Runs the first knowledge-base search for your project
  4. Relays a one-time notice describing exactly what was set up and how to undo it

No account, no email, no environment variables, no decisions.

Use your own account instead (optional)

Anonymous accounts are fully functional — search and contribution included. Register with a real email only if you want a stable identity across machines:

curl -s -X POST https://api.commontrace.org/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "display_name": "Your Name"}' | python3 -m json.tool

Save the api_key from the response — it cannot be retrieved again. Export it before launching Claude Code (the environment variable always takes precedence over a stored anonymous key), and register the MCP server with the same indirection so the raw key never lands in the stored config:

export COMMONTRACE_API_KEY=your-api-key
claude mcp add commontrace --transport http https://mcp.commontrace.org/mcp -H 'x-api-key: ${COMMONTRACE_API_KEY}'

Uninstall

claude plugin remove commontrace
claude mcp remove commontrace
rm -rf ~/.commontrace

Slash Commands

/trace search [query]

Search the CommonTrace knowledge base by natural language query.

/trace contribute

Review pending contribution candidates or contribute a new trace from scratch.

/trace brain

Render local brain artifacts (brain.html, brain.svg, badge.svg) from ~/.commontrace/local.db.

Hooks

HookTriggerWhat it does
session_start.pySession startDetects project context and auto-queries CommonTrace
post_tool_use.pyAfter every tool useRecords tool events, detects knowledge candidates in real-time
post_tool_use.pyAfter failed tool useRecords errors, auto-searches CommonTrace for known fixes
user_prompt.pyUser message submittedCounts user turns, records timestamps
stop.pySession endScores knowledge importance; auto-submits traces (auto mode) or queues to pending/ (manual mode)

Artifacts (local-first)

Everything below is generated locally from ~/.commontrace/local.db. Aggregate shapes only — no code, no error text, no file names.

  • Brain graph — /trace brain renders ~/.commontrace/artifacts/brain.html + brain.svg: your agent's knowledge graph. Node size = how hard the fight was, color = memory temperature (hot → frozen), fade = decay.
  • README badge — the same command also writes badge.svg. Copy it into a repo and embed: ![CommonTrace brain](./badge.svg)
  • Struggle grid — after a knowledge-worthy session, a Wordle-style share line lands in ~/.commontrace/artifacts/last-struggle.txt: 🟥🟥🟨🟨🟩 47min · 8 errors · solved → commontrace.org/t/<id>
  • Resolved-with trailer — when a commons trace contributed to a fix, the agent is reminded to disclose it in the commit message: Resolved-with: CommonTrace https://commontrace.org/t/<id> (citation, not co-authorship).
  • Monthly Compiled — the first session of each month drops last month's recap (sessions, errors, resolutions, hardest fight) to ~/.commontrace/artifacts/compiled-YYYY-MM.txt. Your own numbers, never AI interpretation.

Available MCP Tools

When the MCP server is connected, Claude has access to:

  • search_traces — semantic + tag search
  • contribute_trace — submit a new trace
  • vote_trace — upvote/downvote traces
  • get_trace — read a trace by ID
  • list_tags — discover available tags
  • amend_trace — propose an improved solution

Configuration

VariableDefaultDescription
COMMONTRACE_API_KEY(auto-provisioned)Optional override — set it to use your own account instead of the auto-provisioned anonymous one
COMMONTRACE_MCP_URLhttps://mcp.commontrace.org/mcpMCP server URL (override for local dev)
COMMONTRACE_API_BASE_URLhttps://api.commontrace.orgAPI URL (used by hooks)

~/.commontrace/config.json keys

KeyDefaultDescription
auto_contributetrueSubmit detected knowledge automatically; set false to review via /trace contribute
resolved_with_trailertrueSuggest the Resolved-with: disclosure trailer after commons-assisted fixes

Related Repositories

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados