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

The plugin's .claude-plugin/plugin.json declares the memory MCP server; Claude Code auto-wires it on plugin install, so you don't need to run claude mcp add. What you do need is the markdown-vault-mcp binary on your PATH — plugin.json invokes markdown-vault-mcp serve, and if the binary isn't there, the MCP silently fails to start and every memory operation breaks.

markdown-vault-mcp is a Python package published on PyPI. It's not pre-installed — pick an installer and run it.

Recommended — uv (fast, isolated, auto-manages Python version):

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

# Install the MCP server:
uv tool install markdown-vault-mcp

Alternative — pipx (isolated, no auto-Python-management):

# Install pipx if not present.
# macOS:
brew install pipx
# Debian / Ubuntu:
sudo apt install pipx

# Install the MCP server:
pipx install markdown-vault-mcp

Last resort — pip (global install, conflicts with system Python on modern macOS/Linux via PEP 668):

pip install --user 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

Layers 2 and 3 are automatic — the plugin generates and maintains them on every startup. Layer 1 requires a one-line shell alias because --append-system-prompt-file is CLI-only (no settings.json equivalent exists).

To activate Layer 1, add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):

alias claude='claude --append-system-prompt-file ~/.claude/system-overrides.md'

Who needs this: Anyone using the Claude Code CLI whose agent persona overrides default system prompt behaviors (emoji usage, tone, sycophancy rules). If your persona doesn't contradict the defaults, Layers 2 and 3 are sufficient.

Who doesn't need this: Desktop app, web app (claude.ai/code), and IDE extension users — these don't go through the shell. For those environments, the plugin relies on Layers 2 and 3 as reinforcement. These work everywhere but can't architecturally override the system prompt.

Configure (required on first install)

The memory MCP server ships unconfigured. Run /workbench:customize on first install to set your paths: