知识库集成插件

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

Run these inside Claude Code:

/plugin marketplace add commontrace/skill
/plugin install commontrace@commontrace

Or from a terminal, in one line (same thing, claude plugin is also a CLI):

claude plugin marketplace add commontrace/skill && \
  claude plugin install commontrace@commontrace

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 (POSIX: mode 0600; Windows: ACL restricted to the current user via icacls, best-effort, since POSIX mode bits don't apply)
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.

Want to publish under your own account? Export your key before launching Claude Code:

export COMMONTRACE_API_KEY=ct_...

It takes precedence over the anonymous key that would otherwise be provisioned on first run. You do not need one to contribute. The anonymous account reads, searches and publishes just as well; a key of your own only buys a stable identity across machines.

Installing deliberately asks you nothing. The manifest declares no userConfig options, because a declared option is prompted for at enable time and being asked for an API key you do not need is the opposite of the promise above.

Update

claude plugin update commontrace

Updates are not automatic. You stay on your installed version until you run that. To see what you have: claude plugin list.

Once a day, at session start, the skill checks whether a newer version has been published and prints one line if so. It rides the existing daily heartbeat, so it costs one request per day, never one per session, and it fails silently when offline. Turn it off with "update_check": false in ~/.commontrace/config.json.

Update as a whole, never file by file: the hooks import sibling modules, so a half-updated install would be missing pieces. Since 0.6.0 that case degrades to a silent no-op rather than erroring on every tool call, but it still leaves you without the features.

What leaves your machine, and when

• At session start: a search using only your project's language/framework tag (e.g. python), no code, no file contents, no prompts: to fetch relevant fixes.
• Contributions: nothing is shared automatically by default. When you solve something worth keeping, you're asked first; the contribution is a secret-redacted title/problem/solution summary plus aggregate metadata (minutes, error count, token estimate), no transcripts, no file dumps. Choose Always at the prompt (or set auto_contribute: true in ~/.commontrace/config.json) to enable passive auto-contribution thereafter.
• Publishing is open. Reading, /commontrace:recall search and contributing are all open to any account, including the anonymous one this plugin registers for you. There is no invitation to request. The server still carries a can_contribute flag, currently a pass-through, so the skill keeps handling an HTTP 403 gracefully: if publishing is ever restricted again it surfaces the server's message and does not claim success.
• Stays local, never sent: ~/.commontrace/local.db (aggregate counters and trace pointers only).
• Scope: the MCP server registers at user scope, so it's active across all your repos. Remove it per the Uninstall section if you don't want that on client work.

Use your own account instead (optional)

The anonymous account can already read, search and publish. Register with a real email only if you want a stable identity across machines, so your contributions are attributed to you rather than to a per-machine anonymous account:

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. The simplest way to use it is to export it (see Install); the hooks resolve keys in this order, most explicit first:

1. COMMONTRACE_API_KEY in the environment. The explicit override
2. ~/.commontrace/config.json: where the anonymous key lands on first run

If you would rather keep the raw key out of the stored config entirely, export it before launching Claude Code and register the MCP server with the same indirection:

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

/commontrace:trace search [query]

Search the CommonTrace knowledge base by natural language query.

/commontrace:trace contribute

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

/commontrace:trace brain

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

Hooks

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: /commontrace: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

~/.commontrace/config.json keys

Auto-contribute on transition (opt-in, off by default)

When enabled, the UserPromptSubmit hook contributes the current session's fix the moment you naturally move on. No manual /commontrace:trace needed. The contribution runs as a non-blocking background handoff (identical to /commontrace:trace): a hidden subagent authors the trace from this session's real fix, POSTs it, and surfaces the ⬡ receipt on its own while the main thread proceeds to the next task.

It is fully deterministic and structural. No LLM, no NLU. The fire condition (hooks/auto_contribute.py) is a pure regex/substring match over a small, word-boundaried set of move-on phrases; your message is never sent to a model or classified. The trigger fires only when all of:

1. the feature is enabled (CT_AUTO_CONTRIBUTE_ON_MOVE_ON=1 or auto_contribute_on_move_on: true),
2. your message matches a move_on_patterns phrase,
3. a contribution-worthy fix candidate exists this session (a test_fix_cycle / approach_reversal / user_correction / research_then_implement candidate recorded by post_tool_use.py), and
4. nothing has been auto-contributed yet this session (one-shot per session).

Off by default so real users' existing Stop-prompt flow is unchanged; silently contributing on every "move on" is opt-in to avoid noise/PII. Enable it per-project, e.g. a demo repo's .claude/settings.json sets CT_AUTO_CONTRIBUTE_ON_MOVE_ON=1 so the user "just types the agreed lines." The trace is always authored from the current session only, never fabricated from stale or empty context.

License

Apache-2.0