workbench-core

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, identity-aware collaborator. It provides:

• Persistent identity — persona files (soul-hot.md, profile.md) injected at session start and re-injected after context compression so the agent never drifts.
• Guardrails — absolute behavioral rules that ship with the plugin, load last (highest authority), and are enforced by the interview skills. Guardrails can't be overridden by persona or profile choices.
• Session logging — every session is captured as a rolling JSONL log, then summarized by a background agent into a searchable narrative.
• Operational memory — a local MCP server (markdown-vault-mcp) fronts a searchable vault of decisions, projects, insights, and session history.
• Execution-aware skills — a behavioral protocol that gives any skill persistent memory via vault-backed learnings files.
• Retention management — automatic cleanup of raw logs (28 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

# macOS
brew install jq

# Debian / Ubuntu
sudo apt install jq

# Fedora / RHEL
sudo dnf install jq

3. markdown-vault-mcp — the MCP server backing the memory vault

You normally don't need to install this yourself — the plugin's launcher (hooks/mcp-memory.sh) self-installs the server from the fork 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 and Claude Code auto-wires it on plugin install, so there's no claude mcp add step either. On a fresh machine the first MCP connection may hit Claude Code's 30s startup timeout while the install runs (~60–90s); the install completes in the background regardless, and the next session connects normally.

The launcher installs from the mikebronner/markdown-vault-mcp fork — the canonical source for this plugin. The fork carries index-state fixes the plugin relies on (persistent-index adoption at boot, offline-change reconciliation, tracker skip-state, embedding convergence, raw-transcript exclusion support) that are not yet in any PyPI release. They have been contributed upstream (pvliesdonk/markdown-vault-mcp#665); once an upstream release carries them, plain PyPI installs will work again — until then, installing from PyPI gets you a server that can exceed Claude Code's 30s MCP startup timeout on first boot.

If neither uv nor pipx is available, install one:

# uv — macOS:
brew install uv
# uv — Linux / other (via official installer):
curl -LsSf https://astral.sh/uv/install.sh | sh

# pipx — macOS:
brew install pipx
# pipx — Debian / Ubuntu:
sudo apt install pipx

Manual install / troubleshooting — if the bootstrap fails (the launcher logs mcp-memory:-prefixed errors to stderr), install the server yourself:

# Recommended — uv (fast, isolated, auto-manages Python version):
uv tool install --from git+https://github.com/mikebronner/markdown-vault-mcp markdown-vault-mcp --with fastmcp --with fastembed

# Alternative — pipx (isolated, no auto-Python-management):
pipx install git+https://github.com/mikebronner/markdown-vault-mcp

# Last resort — pip (global install, conflicts with system Python on modern
# macOS/Linux via PEP 668):
pip install --user git+https://github.com/mikebronner/markdown-vault-mcp

Verify:

markdown-vault-mcp --version

Install the plugin

/plugin marketplace add mike-bronner/claude-workbench
/plugin install workbench-core@claude-workbench

Optional: CLI system-prompt enforcement

Background: Claude Code's default system prompt includes rules like "no emojis unless asked" and specific tone/style directives. If your agent persona contradicts these (e.g., "use emojis liberally"), the system prompt wins — it's architecturally higher authority than CLAUDE.md or hook output, which are both delivered as user messages.

The plugin addresses this at three layers:

Layer	File	Authority	Works in
1	~/.claude/system-overrides.md	System prompt (highest)	CLI only
2	~/.claude/CLAUDE.md managed block	User message	Everywhere
3	SessionStart hook output	Tool result	Everywhere