mike-bronner/workbench-core

Core infrastructure plugin for Claude Code. Part of the claude-workbench marketplace.
What this is
The infrastructure layer that turns Claude Code from a stateless coding assistant into a persistent collaborator. It provides:
- **One persona** — the shipped output style, installed by setup. It sits in the system prompt, so it survives context compression with no re-injection.
- **One rule source** — the behavioural rules load once, from the shipped output style. No hook restates them, so they cannot drift apart and they never reach a sub-agent.
- **Session logging** — every session is captured as a rolling JSONL log, then summarized by a background agent into a searchable narrative.
- **Operational memory** — a shared, lazy-started local MCP server (markdown-vault-mcp) fronts a searchable vault of decisions, projects, insights, and session history, optionally kept in sync across machines over git.
- **Execution-aware skills** — a PreToolUse(Skill) hook hands any skill its vault-backed learnings file, so each run starts from what past runs learned.
- **Retention management** — automatic cleanup of raw logs (7 days) and checkpoints (7 days); summaries and decisions persist indefinitely.
Installation
Prerequisites
Three things must be on your system before installing the plugin.
1. Claude Code CLI
Install from claude.ai/code.
2. jq — JSON parser used by the hook scripts
3. markdown-vault-mcp — the MCP server backing the memory vault
**You normally don't need to install this yourself** — the plugin self-installs the server on first run. All it needs is uv or pipx on your PATH (uv preferred). The plugin's .claude-plugin/plugin.json declares the memory MCP server (the shared **HTTP** server on a loopback port) and Claude Code auto-wires it on plugin install, so there's no claude mcp add step either.
The server is a **lazy-started, reference-counted shared HTTP server**: the first session that needs it starts it in the background, every Claude Code process registers a ref, and it is stopped a grace period after the last one leaves. One server means one embedding model resident instead of one per session, one writer serializing index updates, and one process able to own the git sync loop. It needs a port and a bearer token, both provisioned by /workbench-core:setup — so run setup and restart before memory works on a fresh install. See Memory server transport and Server lifetime below.
The server comes from upstream pvliesdonk/markdown-vault-mcp. The primary path is the bundled wheel under hooks/wheels/; the git install below is the fallback for when no wheel ships or uv is missing.
This plugin used to install from a mikebronner/markdown-vault-mcp fork, because the index-state fixes it relies on (persistent-index adoption at boot, offline-change reconciliation, tracker skip-state, embedding convergence, raw-transcript exclusion support) were not in any PyPI release. That is no longer true. Those fixes merged upstream on 2026-06-11 (#666, #667, #668, #670) and first shipped in PyPI 3.0.0 on 2026-06-17. The fork now carries **no** commits upstream lacks, so pointing at it only pins you to a stale tree.
If neither uv nor pipx is available, install one:
**Manual install / troubleshooting** — if the bootstrap fails (the launcher logs mcp-memory:-prefixed errors to stderr), install the server yourself:
Verify:
Install the plugin
Where the behavioural rules load
The rules load from one place: the output style /workbench-core:setup installs from assets/personas/clear/output-style.md. An output style is system-prompt tier, so it outranks the base prompt's defaults (such as "no emojis unless asked") without any shell alias, and it survives compaction on its own. It also reaches the main session only, which is where the rules belong.
No hook restates them. Earlier versions loaded the same rules four times per main session: the output style, a ~/.claude/system-overrides.md file passed by a shell alias, the managed ~/.claude/CLAUDE.md block, and a guardrails payload on the warmup's stdout. The copies drifted and contradicted each other. The CLAUDE.md copy also reached every sub-agent, which put "present options" and AskUserQuestion into agents that have neither a human nor the tool. hooks/test-rule-source.sh pins the new shape: twelve rules and three habits of shape in the output style, its pointer to the intake skill, the style obeying its own register, and no rule text in anything the warmup writes or prints.
The hooks module enforces rule 4 without loading it. Its re-prompt and its refusal speak only when a reply breaks the rule, in an attended main-session turn, so they correct a reply and never add a copy to the context.