quibbler 0.3.0

Code review agent for AI coding assistants via MCP

Quibbler

Quibbler is a code review agent that integrates with AI coding assistants. It reviews completed code changes after they're implemented, catching quality issues, hallucinations, and pattern violations.

Unlike simple linters or static analysis tools, Quibbler is an agent: it can read and understand your codebase context to provide intelligent, context-aware feedback.

What Quibbler Prevents

We've found Quibbler useful in preventing agents from:

• Fabricating results without running commands
• Not running tests or skipping verification steps
• Not following your coding style and patterns
• Hallucinating numbers, metrics, or functionality
• Creating new patterns instead of following existing ones
• Making changes that don't align with user intent

Quibbler maintains context across reviews, learning your project's patterns and rules over time.

Installation

Using uv:

uv tool install quibbler

Using pip:

pip install quibbler

Choosing Your Mode

Quibbler supports two integration modes:

Hook Mode (For Claude Code users)

• Uses Claude Code's hook system for event-driven monitoring
• Passively observes all agent actions (tool use, prompts, etc.)
• Fire-and-forget feedback injection via file writes
• More powerful affordances but Claude Code-specific

MCP Mode (For users of all other coding agents)

• Uses the Model Context Protocol for universal compatibility
• Agent calls review_code tool after making changes
• Synchronous review with immediate feedback
• Simple setup via MCP server configuration

Setup

Choose your mode and follow the appropriate setup instructions:

Option A: MCP Mode Setup

1. Configure MCP Server

Add Quibbler to your agent's MCP server configuration.

For Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "quibbler": {
      "command": "quibbler mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

For other MCP-compatible agents: Refer to your agent's documentation for MCP server configuration.

2. Add to AGENTS.md

Create or update AGENTS.md in your project root to instruct your agent to use Quibbler:

## Code Review Process

After making code changes, you MUST call the `review_code` tool from the Quibbler MCP server with:

- `user_instructions`: The exact instructions the user gave you
- `agent_plan`: **A summary of the specific changes you made** (include which files were modified, what was added/changed, and key implementation details)
- `project_path`: The absolute path to this project

Review Quibbler's feedback and address any issues or concerns raised.

### Example

User asks: "Add logging to the API endpoints"

After implementing, call:

review_code(
user_instructions="Add logging to the API endpoints",
agent_plan="""Changes made:

1. Added logger configuration in config/logging.py
2. Updated routes/api.py to log incoming requests and responses
3. Added request_id middleware for tracing
4. Created logs/ directory with .gitignore""",
   project_path="/absolute/path/to/project"
   )

Option B: Hook Mode Setup

1. Start Quibbler Hook Server

In a terminal, start the Quibbler hook server:

export ANTHROPIC_API_KEY="your-api-key-here"
quibbler hook server
# Or specify a custom port:
quibbler hook server 8081

Keep this server running in the background. It will receive hook events from Claude Code.

2. Configure Hooks in Your Project

In your project directory, run:

quibbler hook add

This creates or updates .claude/settings.json with the necessary hooks to forward events to the Quibbler server.

3. Verify Setup

The .claude/settings.json should now contain hooks that:

• Forward tool use events to Quibbler (quibbler hook forward)
• Display Quibbler feedback to the agent (quibbler hook notify)

When Claude Code runs in this project, Quibbler will automatically observe and intervene when needed.

Configuration

By default, Quibbler uses Claude Haiku 4.5 for speed. You can change this by creating or editing:

Global config (~/.quibbler/config.json):

{
  "model": "claude-sonnet-4-5"
}

Project-specific config (.quibbler/config.json in your project):

{
  "model": "claude-sonnet-4-5"
}

Project-specific config takes precedence over global config.

How It Works

MCP Mode

1. Your agent makes code changes, then calls the review_code tool with user instructions and a summary of changes made
2. Quibbler maintains a persistent review agent per project that:
   • Reviews the completed changes against user intent
   • Uses Read tool to examine the actual changed files and existing patterns in your codebase
   • Validates claims and checks for hallucinations
   • Verifies proper testing and verification steps were included
3. Quibbler returns feedback or approval synchronously
4. Your agent addresses any issues found in the review

Hook Mode

1. Claude Code triggers hooks on events (tool use, prompt submission, etc.)
2. Hook events are forwarded to the Quibbler HTTP server
3. Quibbler maintains a persistent observer agent per session that:
   • Passively watches all agent actions
   • Builds understanding of what the agent is doing
   • Intervenes when necessary by writing feedback to .quibbler/{session_id}.txt
4. Feedback is automatically displayed to the agent via the notify hook
5. The agent sees the feedback and can adjust its behavior

Both modes build understanding over time, learning your project's patterns and saving rules to .quibbler/rules.md.

Customizing Prompts

You can customize Quibbler's system prompt by editing ~/.quibbler/prompt.md. The default prompt will be created on first run.

Project-specific rules in .quibbler/rules.md are automatically loaded and added to the prompt.

Note for Hook Mode: Quibbler writes feedback to a message file that is intended for the agent to read and act on (though users have oversight and can see it). Your agent's system prompt should include a {message_file} placeholder to tell Quibbler where to write its feedback. For example:

When you need to provide feedback to the agent, write it to {message_file}. This is agent-to-agent communication intended for the coding agent to read and act on.

Contributing

If you notice an issue or bug, please open an issue. We welcome contributions - feel free to open a PR.

Join our community on Discord to discuss workflows and share experiences.

License

See LICENSE for details.