claude-gladiator-mcp

A Model Context Protocol (MCP) server that helps Claude Code learn from its own mistakes. Observe patterns during work, then reflect to get recommendations for updating your rules, hooks, and skills.

Inspired by the continuous learning experiments for Claude Code: Everything Claude Code by Affaan-m, Claudeception by blader, and Homunculus by humanplane. Research foundations: Voyager (Wang et al., 2023) and Reflexion (Shinn et al., 2023).

install

Requirements:

From shell:

claude mcp add claude-gladiator-mcp -- npx claude-gladiator-mcp

From inside Claude (restart required):

Add this to our global mcp config: npx claude-gladiator-mcp

Install this mcp: https://github.com/Vvkmnn/claude-gladiator-mcp

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "claude-gladiator-mcp": {
      "command": "npx",
      "args": ["claude-gladiator-mcp"],
      "env": {}
    }
  }
}

There is no npm install required — no external dependencies or local databases, only clustering algorithms.

skill

Optionally, install the skill to teach Claude when to proactively observe and reflect:

npx skills add Vvkmnn/claude-gladiator-mcp --skill claude-gladiator --global

This makes Claude automatically observe tool failures, user corrections, and codebase patterns. The MCP works without the skill, but the skill improves discoverability.

plugin

For automatic observation hooks and session-end reflection prompts, install from the claude-emporium marketplace:

/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-gladiator@claude-emporium

The claude-gladiator plugin provides:

Hooks (targeted, zero overhead on success):

• After Bash/Edit/Write errors → Observe failure pattern via gladiator_observe
• Before session ends → Reflect on unprocessed observations via gladiator_reflect

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

features

MCP server that gives Claude a learning loop. Observe patterns, cluster them, evolve your configuration.

gladiator_observe

Record a pattern worth learning from — tool failures, corrections, conventions, decisions. Deduplicates by SHA-256 hash of summary.

gladiator_observe summary=<summary> tags=<tags> context=<context>
  > "Edit failed on config.ts — 3 identical import blocks, fixed by including surrounding context"
  > "User wanted tests in __tests__/ not next to source — project convention"
  > "All API routes use zod validation middleware — schema in routes/schemas/"

┌─ ⚔ ───────────────────────────────────────────────────── Recorded ─┐
│ Edit failed on config.ts — 3 identical import blocks               │
│ Recommend (rule): Next time: included 3 lines above                │
│ Tags: edit, disambiguation                                         │
│ Backlog: 3 unprocessed of 12 total                                 │
└────────────────────────────────────────────────────────────────────┘

{
  "id": "obs_1738012345_a7f3",
  "ts": "2025-01-27T18:32:25.000Z",
  "summary": "Edit failed on config.ts — 3 identical import blocks",
  "recommendation": "Next time: included 3 lines above",
  "artifact_type": "rule",
  "context": {
    "tool": "Edit",
    "error": "old_string not unique",
    "before": "used import line only",
    "after": "included 3 lines above"
  },
  "tags": ["edit", "disambiguation"],
  "processed": false
}

gladiator_reflect

Cluster unprocessed observations, scan existing ~/.claude/rules/, ~/.claude/hooks/, and ~/.claude/skills/, and recommend whether to update an existing artifact or create a new one.

gladiator_reflect
  > "I've accumulated 5 observations about edit failures — what patterns emerge?"
  > "Review what I've learned this session before it's lost"

gladiator_reflect query="testing"
  > "Search past observations about testing conventions"

Cluster mode (unprocessed observations exist):

┌─ ⚔ ──────────────────────────────────────────────────── Reflected ─┐
│ 5 observations → 2 groups                                          │
│ 8 existing artifacts scanned (IDF-weighted)                        │
│                                                                    │
│ UPDATE avoid: edit-disambiguation (3 obs)                          │
│   - Next time: included 3 lines above                              │
│   - Include surrounding function context for disambiguation        │
│   - Check for duplicate imports before editing                     │
│ NEW rule: testing-convention (2 obs)                               │
│   - Next time: moved to __tests__/utils.test.ts                    │
│   - Use __tests__/ directory for all test files                    │
└────────────────────────────────────────────────────────────────────┘

{
  "observations_analyzed": 5,
  "groups_found": 2,
  "existing_artifacts_scanned": 8,
  "groups": [
    {
      "suggested_name": "edit-disambiguation",
      "artifact_type": "rule",
      "tags": ["edit", "disambiguation", "old_string"],
      "action": "update",
      "update_targets": [{ "type": "rule", "name": "avoid", "path": "~/.claude/rules/avoid.md" }],
      "observations": ["..."]
    },
    {
      "suggested_name": "testing-convention",
      "artifact_type": "rule",
      "tags": ["convention", "testing"],
      "action": "create",
      "update_targets": [],
      "observations": ["..."]
    }
  ],
  "actions": [
    "PREFER updating existing artifacts over creating new ones",
    "Consolidate related observations into a single change when possible",
    "Only create new artifacts when no existing one covers the topic"
  ]
}

Stats mode (nothing unprocessed):

┌─ ⚔ ──────────────────────────────────────────────────────── Stats ─┐
│ Observations: 12 total, 0 unprocessed                              │
│   rule: 8                                                          │
│   skill: 3                                                         │
│   hook: 1                                                          │
└────────────────────────────────────────────────────────────────────┘

Query mode (gladiator_reflect query="edit"):

┌─ ⚔ ──────────────────────────────────────────────────────── Found ─┐
│ "edit" — 4 observations                                            │
│   Edit failed on config.ts — 3 identical import (2h ago)           │
│   Edit old_string matched wrong function in uti (1d ago)           │
│   Edit succeeded after adding file_path context (3d ago)           │
│   Edit conflict on package.json — concurrent wr (5d ago)           │
└────────────────────────────────────────────────────────────────────┘

methodology

How claude-gladiator-mcp works:

gladiator_observe(summary, tags, context)
      │
      ├─ dedup ─── SHA-256(summary) vs last 100 ─── duplicate? → skip
      ├─ classify ─ tags + context → rule | skill | hook | agent
      ├─ recommend  context.after → "Next time: ..."
      └─ append ─── → observations.jsonl


gladiator_reflect(query?, limit?)
      │
      ├─ query? ──────── search all by summary/tags/error → return matches
      │
      ├─ 0 unprocessed ─ return stats: total, by_type, recent 5
      │
      └─ N unprocessed ─┐
          │              │
          ├─ cluster ─── Jaccard(tags) > 0.3 → merge into groups
          │              majority-vote artifact_type per group
          │
          ├─ scan ────── rules/*.md + hooks/* + skills/*/SKILL.md
          │              extract keywords (>3 chars) per artifact
          │
          ├─ score ───── IDF: 1/docFreq(word) per shared keyword
          │              filter words in >40% of artifacts
          │              name match bonus: +5
          │              threshold: >= 3.0 → "update"
          │
          ├─ mark ────── processed = true
          │
          └─ return ──── per cluster: action, targets, observations

Core algorithms:

• Jaccard clustering (clusterObservations): Groups observations with tag overlap > 0.3, majority-votes artifact type per cluster
• IDF-weighted scoring (findOverlappingArtifacts): Scores clusters against existing artifacts, weighting rare words higher (1/docFreq), filtering words in >40% of docs
• Content-based dedup (hashSummary): SHA-256 prefix (8 hex chars) of lowercased summary, checked against last 100 observations
• Auto-classification (classifyArtifact): Keyword regex on tags for hook/agent, context heuristic for skill, default rule

File access:

• Reads/writes: ~/.claude/gladiator/observations.jsonl (JSONL, each line is a self-contained JSON object with timestamp, summary, tags, context, and processing state)
• Scans (read-only): ~/.claude/rules/, ~/.claude/hooks/, ~/.claude/skills/
• Zero external dependencies
• Never leaves your machine

development

git clone https://github.com/Vvkmnn/claude-gladiator-mcp && cd claude-gladiator-mcp
npm install && npm run build
npm test

Package requirements:

• Node.js: >=20.0.0 (ES modules)
• Runtime: @modelcontextprotocol/sdk, zod
• Zero external databases — works with npx

Development workflow:

npm run build          # TypeScript compilation with executable permissions
npm run dev            # Watch mode with tsc --watch
npm run start          # Run the MCP server directly
npm run lint           # ESLint code quality checks
npm run lint:fix       # Auto-fix linting issues
npm run format         # Prettier formatting (src/)
npm run format:check   # Check formatting without changes
npm run typecheck      # TypeScript validation without emit
npm run test           # Lint + type check
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)

Git hooks (via Husky):

• pre-commit: Auto-formats staged .ts files with Prettier and ESLint

Contributing:

• Fork the repository and create feature branches
• Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

• Official MCP servers for reference implementations
• TypeScript SDK for best practices
• Creating Node.js modules for npm package development

license

MIT

Pollice Verso by Jean-Léon Gérôme (1872). "Ave Imperator, morituri te salutant." Claudius replied "Aut non" (or not).