artifacts-mcp

Session artifacts for Claude Code. Captures important context (file paths, errors, commands, URLs) during your session and makes it queryable after auto-compact.

Problem

When context grows too large, Claude Code runs "auto-compact" — an in-memory summarization that loses details: file paths, error messages, code snippets, architectural decisions. You end up re-explaining things Claude already knew.

Solution

artifacts-mcp works in three layers:

1. PostToolUse hook — after every tool call, extracts artifacts (file paths, commands, errors, URLs) and stores them to disk
2. PreCompact hook — when auto-compact fires, injects preservation instructions into the compact prompt
3. MCP server — gives Claude tools to query stored artifacts after compaction

You work normally
       |
       v
 Every tool call --> PostToolUse hook extracts artifacts
                     (file paths, commands, errors, URLs)
                     Stored to ~/.config/artifacts-mcp/sessions/
       |
       v
 Context fills up --> Claude auto-compact fires
                      PreCompact hook adds preservation instructions
       |
       v
 After compact --> Claude can query_artifacts via MCP
                   Recovers file paths, errors, decisions lost in compact

No kill, no resume, no JSONL modification. Works with Claude's native auto-compact.

Quick start

git clone https://github.com/user/artifacts-mcp.git ~/artifacts-mcp
cd ~/artifacts-mcp
npm install
bin/cbp install
source ~/.zshrc

Then restart Claude Code for the MCP server to activate.

What the installer does

1. Checks prerequisites (Node 22+, Claude CLI)
2. Registers 3 hooks in ~/.claude/settings.json (PostToolUse, PreCompact, SessionEnd)
3. Registers MCP server in ~/.claude.json
4. Sets up claude alias → wrapper script (sets CLAUDE_AUTOCOMPACT_PCT_OVERRIDE)
5. Adds bin/ to PATH (so cbp works from anywhere)
6. Runs 12 verification checks

Prerequisites

• Node.js 22+ (for --experimental-strip-types)
• Claude Code CLI (claude command)

CLI tool: cbp

Command	What it does
cbp install	Register hooks, MCP server, set up alias, verify
cbp uninstall	Remove hooks, MCP server, alias
cbp verify	Run 12 installation checks
cbp enable	Turn on artifact extraction
cbp disable	Turn off (hooks pass through silently)
cbp status	Show state: hooks, MCP, sessions, artifact counts
cbp set-key <key>	Save Gemini API key to config
cbp config	Show current configuration
cbp cleanup	Remove stale files, expired sessions

How it works

Artifact extraction (PostToolUse)

Runs after every tool call. No LLM, pure parsing — fast:

Tool	Extracted
Write, Edit, Read	file_path + config detection
Bash	command, error (if exit ≠ 0)
Glob, Grep	discovered file_paths
Any tool	URLs from output

Artifacts are stored in ~/.config/artifacts-mcp/sessions/<session-id>.jsonl.

Preservation instructions (PreCompact)

When Claude's auto-compact fires, the PreCompact hook outputs additional instructions that get added to the compact prompt:

• Lists all stored artifact counts
• Enumerates file paths referenced in the session
• Instructs Claude to preserve file paths, errors, code snippets, decisions

MCP tools (after compact)

After compaction, Claude has 3 tools to recover lost context:

Tool	Description
store_artifact	Manually store important info (decisions, code snippets)
query_artifacts	Search artifacts by type and/or text query
get_session_summary	Overview of all artifacts grouped by type

Auto-compact tuning

The wrapper script (cclaude.sh) sets CLAUDE_AUTOCOMPACT_PCT_OVERRIDE to trigger auto-compact earlier (default: 50% of effective window ≈ 90K tokens). This gives more room for the compacted summary. Configurable via autoCompactPercent in config.json.

Configuration

~/.config/artifacts-mcp/config.json — create to override defaults:

{
  // Trigger auto-compact at this % of effective window (default 50)
  "autoCompactPercent": 50
}

Debug logging

When launched via cclaude.sh (the alias), debug logging is enabled automatically:

# Artifact extraction log
tail -f ~/.config/artifacts-mcp/logs/extractor.log

# PreCompact hook log
tail -f ~/.config/artifacts-mcp/logs/precompact.log

Session lifecycle

1. Session starts → MCP server spawns (stdio), PostToolUse hook active
2. Tool calls → artifacts extracted and stored to session JSONL
3. Auto-compact fires → PreCompact adds instructions, Claude summarizes
4. After compact → Claude queries artifacts via MCP tools
5. Session ends → SessionEnd hook marks session, starts 24h TTL
6. 24h later → session artifacts auto-cleaned

File structure

artifacts-mcp/
  bin/
    cbp                    -- CLI tool (install, manage, verify)
    cclaude.sh             -- wrapper: sets AUTOCOMPACT_PCT, debug env
    artifacts-server.js    -- MCP server entry point
  src/
    artifact-extractor.ts  -- PostToolUse hook: extracts artifacts
    precompact-hook.ts     -- PreCompact hook: preservation instructions
    session-end-hook.ts    -- SessionEnd hook: TTL management
    config.ts              -- config loading, defaults
    mcp-server/
      server.ts            -- MCP server (store, query, summary tools)
      store.ts             -- ArtifactStore: JSONL-based per-session storage
      types.ts             -- TypeScript types

Runtime files

Path	Purpose	Lifetime
~/.config/artifacts-mcp/sessions/<id>.jsonl	Session artifacts	24h after session end
~/.config/artifacts-mcp/sessions/<id>.meta.json	Session metadata	24h after session end
~/.config/artifacts-mcp/config.json	User configuration	Permanent
~/.config/artifacts-mcp/enabled	Kill switch	Until disabled
~/.config/artifacts-mcp/logs/*.log	Debug logs	Permanent

Uninstall

cbp uninstall
# Optionally remove all data:
rm -rf ~/.config/artifacts-mcp