Skip to content

Kibitzer

The person watching your chess game who can't help offering opinions.

Kibitzer is a standalone Claude Code extension that watches how agents use tools and suggests better alternatives. It optionally coordinates with Fledgling (code intelligence), blq (build/test capture), and jetsam (git workflow) — but none are required.

Kibitzer is level 1: specified rules over structured data. No LLM in the decision loop. Every decision traces to config.toml.

What it does

Kibitzer has two interfaces:

Passive (hooks) — PreToolUse and PostToolUse hooks fire automatically on every tool call. They guard paths, intercept bash commands, track counters, and suggest improvements. The agent doesn't invoke these.

Active (MCP server) — Two tools the agent can call explicitly: ChangeToolMode to switch modes and GetFeedback to check status, get coaching suggestions, and see intercepted patterns.

Quick start

pip install kibitzer
cd your-project/
kibitzer init --hooks --mcp

For shell integration (prompt indicator, command coaching, pre-commit guard):

kibitzer init --shell --git-hooks

For richer coaching with fledgling conversation analytics:

pip install kibitzer[fledgling]

This creates: - .kibitzer/config.toml — project configuration (edit to customize) - .kibitzer/state.json — runtime state (don't edit) - .claude/hooks/kibitzer-pre.sh — PreToolUse hook - .claude/hooks/kibitzer-post.sh — PostToolUse hook - .claude/settings.json — hooks registered - .mcp.json — MCP server entry

Documentation

  • Tutorial — set up kibitzer for your terminal in 5 minutes
  • Modes — the 6 modes and how path protection works
  • Coach — what patterns the coach detects and when
  • Interceptors — bash command interception and the observe/suggest/redirect ratchet
  • Shell Hooks — CLI commands, shell prompt, pre-commit guard, command coaching
  • Configuration — full config.toml reference
  • Architecture — how the pieces fit together
  • Python API — use kibitzer from Python (for lackpy, Riggs, custom tools)
  • Integration — how kibitzer works with blq, jetsam, fledgling, and superpowers

Design principles

  1. No LLM in the loop. Every decision is a specified rule in config.toml. Counters, thresholds, pattern matches.

  2. Graceful degradation. blq not installed? Skip BlqInterceptor. Jetsam not installed? Skip JetsamInterceptor. None installed? Path guard and coach still work.

  3. Observe before enforce. All interceptor plugins start in observe mode. Graduate to suggest then redirect by editing one line in config.

  4. The agent sees the reason. Every deny includes why and how to fix it. "Path 'tests/foo.py' is not writable in the current mode. Use the ChangeToolMode tool to switch modes."

  5. Hooks are fast. Read a JSON file, check a condition, output JSON. Target: <100ms per invocation.