claude-gladiator — Claude Code plugin: what it does, how to install
claude-gladiator is a Claude Code plugin that catches tool failures and prompts reflection before sessions close.
MIT ★ 78 updated 2026-03-05
/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-gladiator@claude-emporiumWhat claude-gladiator does
The plugin registers two hooks: PostToolUse on Bash, Edit, and Write, plus a Stop hook at session end. When an action fails, it prompts Claude to record the failure context using gladiator_observe. Successful calls remain completely silent with zero token cost.
At session exit, the Stop hook checks for unprocessed entries and runs gladiator_reflect. Claude groups the issues into clusters and suggests updates to project rules or skills. You can also trigger a manual batch review anytime via /review-gladiator [topic].
The plugin depends directly on the claude-gladiator-mcp server. Without registering that MCP server, the observation and reflection tools will not function. You can toggle behaviors in ~/.claude/settings.json with observe_after_failure and reflect_before_stop keys.
What it helps with
- record failure context whenever Bash, Edit, or Write commands fail
- cluster recurring session mistakes into concrete recommendations
- propose rule and skill updates based on observed tool errors
- run batch retrospective analysis on session history by topic
Example prompts for the agent
- /review-gladiator typescript-errors
- /review-gladiator
- Process pending gladiator observations and suggest rule updates
How to install claude-gladiator
Plugin marketplace
/plugin marketplace add Vvkmnn/claude-emporium/plugin install claude-gladiator@claude-emporiumStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about claude-gladiator
How to install claude-gladiator in Claude Code?
Run /plugin marketplace add Vvkmnn/claude-emporium to register the marketplace, then execute /plugin install claude-gladiator@claude-emporium.
What does claude-gladiator do?
It monitors tool failures during coding sessions, logs them via MCP tools, and prompts the agent to turn those mistakes into updated project rules before shutting down.
What prerequisite setup is required?
You must install the MCP backend first by running claude mcp add gladiator -- npx claude-gladiator-mcp.
Source text
claude-gladiator · MIT
# Claude Gladiator
Continuous learning hooks for Claude Code. Observes tool failure patterns and prompts reflection before session ends.
## Installation
```bash
/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-gladiator@claude-emporium
```
## Requirements
MCP server: [`claude-gladiator-mcp`](https://www.npmjs.com/package/claude-gladiator-mcp)
```bash
claude mcp add gladiator -- npx claude-gladiator-mcp
```
## Hooks
| Event | Trigger | What It Does |
|-------|---------|-------------|
| `PostToolUse` | `Bash` · `Edit` · `Write` | Observes tool failure patterns (silent on success) |
| `Stop` | `*` | Prompts reflection if unprocessed observations exist |
## Commands
| Command | Description |
|---------|-------------|
| `/review-gladiator [topic]` | Batch learn from observations and session history |
## MCP Tools
| Tool | Purpose |
|------|---------|
| `gladiator_observe` | Record a pattern worth learning from |
| `gladiator_reflect` | Cluster observations and get recommendations |
## Settings
Configure in `~/.claude/settings.json` under `claude-emporium`:
```json
{
"claude-emporium": {
"suggest_siblings": false,
"claude-gladiator": {
"observe_after_failure": false,
"reflect_before_stop": false
}
}
}
```
| Key | Default | What It Controls |
|-----|---------|-----------------|
| `observe_after_failure` | `true` | Observe tool failure patterns after errors |
| `reflect_before_stop` | `true` | Prompt reflection before session ends |
| `suggest_siblings` | `true` | Show install suggestions for sibling plugins (global) |
## How It Works
Hooks inject prompts that trigger `claude-gladiator-mcp` tools at high-impact moments. Tool failures are observed with context (error, tool, input), and accumulated observations are clustered into recommendations at session end.
Typical overhead: ~100-200 tokens per session.
## Hook Notifications
**After a tool failure** (PostToolUse) — Claude sees:
```
⚔️ [claude-gladiator] Edit failed — observe this pattern.
gladiator_observe(
summary="<describe what failed and how you fixed it>",
context={error:"old_string not unique", tool:"Edit",
before:"old_string: \"import { z }\"", after:"<what worked>"},
tags=["error", "edit"]
)
Error: old_string not unique
📜 [claude-historian] is active — check past solutions via get_error_solutions()
during reflection.
```
Claude calls `gladiator_observe` with the error context filled in. Silent on success — zero tokens when tools don't fail.
**Before session ends** (Stop) — Claude sees:
```
⚔️ [claude-gladiator] 3 unprocessed observations — consider reflecting before
session ends.
gladiator_reflect()
Review clusters, propose updates to existing rules/skills/hooks (prefer updating
over creating), and apply with user approval.
📜 [claude-historian] is active — enrich reflection with search_conversations()
and get_error_solutions().
🔮 [claude-oracle] is active — search for existing solutions before creating
new artifacts.
```
Claude runs the reflection workflow before context is lost. Only fires when unprocessed observations exist — silent otherwise. Sibling lines only appear when those plugins are installed.
## License
MIT
© vvkmnn · MIT · Vvkmnn/claude-emporium