inquisitor

Optimal-path problem solving for AI agents Triage · Prune · Investigate — never overcomplicate

Overview

inquisitor makes AI agents solve problems the way a chess engine plays chess: it cannot explore every branch, so it estimates complexity first, prunes paths that add no information, and spends its search budget only where the problem actually is.

It ships as two coordinated layers:

• MCP server (inquisitor-mcp) — the engine. Web search, project analysis, code tracing, project scaffolding, and a persistent investigation state machine. Works with any MCP-compatible agent: OpenCode, Claude Code, Claude Desktop, Cursor.

• Agent skill (skills/inquisitor/SKILL.md) — the behavioral layer. Injects the triage heuristic, the pruning rules, and the full methodology into the agent's reasoning.

The methodology synthesizes four sources:

Web search, codebase scans, and code tracing are tools invoked when local evidence is insufficient — never mandatory rituals.

Related MCP server: Recursive Thinking MCP Server

How it decides

Every problem goes through 10-second triage before anything else:

                        ┌─────────────┐
                        │   TRIAGE    │  heuristic complexity estimate
                        └──────┬──────┘
          ┌────────────────────┼────────────────────┐
          ▼                    ▼                    ▼
     ┌─────────┐          ┌─────────┐          ┌─────────┐
     │ TRIVIAL │          │ SIMPLE  │          │ COMPLEX │
     └────┬────┘          └────┬────┘          └────┬────┘
          │                    │                    │
     fix → verify      criteria → minimal      full Newton 7-phase
     (no ceremony)     evidence → fix →        DEFINE → AXIOMS →
                       verify                  ANALYSIS → EXPERIMENT →
                                               SYNTHESIS → VALIDATE →
                                               QUERY (with session
                                               tracking as memory)

Escalation is allowed — two failed fix attempts or contradicting evidence bumps the class up. Inflated ceremony is not — a 7-phase investigation of a typo is as wrong as a blind guess at a race condition.

Installation

Requires uv and Python 3.12+.

Step 1 — Clone and install

git clone https://github.com/0x2fycy3/inquisitor.git ~/tools/inquisitor
cd ~/tools/inquisitor
uv sync

The clone path is up to you — just use the same absolute path in the config below. ~ does not expand inside JSON config files, so write the full path (e.g. /home/you/tools/inquisitor).

You do not run the server manually. It's a stdio MCP server: your agent spawns and manages it automatically. (If you do run uv run inquisitor-mcp by hand, it prints a ready message on stderr and waits silently — that's normal. Ctrl+C to exit.)

Step 2 — Register the MCP server with your agent

OpenCode — add to ~/.config/opencode/opencode.json (global) or ./opencode.json (per-project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inquisitor": {
      "type": "local",
      "command": [
        "uv", "run",
        "--directory", "/home/you/tools/inquisitor",
        "inquisitor-mcp"
      ],
      "enabled": true
    }
  }
}

Claude Code — add to .mcp.json in your project, or ~/.claude.json for all projects:

{
  "mcpServers": {
    "inquisitor": {
      "command": "uv",
      "args": ["run", "--directory", "/home/you/tools/inquisitor", "inquisitor-mcp"]
    }
  }
}

Claude Desktop — same mcpServers block in claude_desktop_config.json (Settings → Developer → Edit Config).

Step 3 — Install the skill (the behavioral layer)

Symlink it so it stays up to date with the repo:

# OpenCode
mkdir -p ~/.config/opencode/skills
ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.config/opencode/skills/inquisitor

# Claude Code
mkdir -p ~/.claude/skills
ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.claude/skills/inquisitor

(Copying the folder works too — you'll just need to re-copy after updates.)

Step 4 — Restart your agent

Config is loaded at startup. Quit and reopen OpenCode / Claude Code, then verify: the inquisitor_* tools appear in the tool list, and the inquisitor skill is available.

Tools

Example: inquisitor_search

inquisitor_search(
    query="httpx ConnectTimeout retry pattern",
    max_results=8,
    time_range="year",              # day | week | month | year
    include_domains=["github.com"], # optional site: filter
    fetch_content=True,             # full page text, not just snippets
)

Example: phase tracking (COMPLEX path)

inquisitor_phase_set(
    target_phase="experiment",
    findings="500 only occurs when session token > 4KB",
    evidence="repro script output; nginx.conf:34 large_client_header_buffers",
    open_questions="why did token size grow after v2.3 deploy?",
)

Project Structure

inquisitor/
├── src/inquisitor/
│   ├── server.py                # MCP entry point (FastMCP, 6 tools)
│   ├── config.py                # env configuration
│   ├── tools/                   # thin MCP adapters
│   │   └── search / analyze / trace / scaffold / phase / verify
│   └── backend/                 # pure Python, zero MCP dependency
│       ├── search.py            # DDG / Brave / SearXNG + re-ranking
│       ├── extract.py           # trafilatura → readability fallback, SSRF guard
│       ├── analyzer.py          # project structure scan
│       ├── tracer.py            # callers / callees mapping
│       └── phase_tracker.py     # Newton state machine (SQLite)
├── skills/inquisitor/SKILL.md   # behavioral layer for the agent
├── tests/                       # 36 tests
└── docs/superpowers/specs/      # design spec

The backend/ package is importable standalone — no MCP required:

from inquisitor.backend.search import search
results = search("python asyncio best practices", max_results=5)

Environment Variables

No API key is required — DuckDuckGo works out of the box.

Security

• SSRF guard: content fetching refuses non-http(s) schemes and loopback / private / link-local / metadata targets (localhost, 127.0.0.1, 10.x, 192.168.x, 169.254.169.254, …).

• Path traversal guard: session names are sanitized before touching the filesystem.

• No shell execution: subprocess calls use argument lists, never shell=True.

• Parameterized SQL throughout the session store.

• The server runs locally over stdio with your user's privileges — it does not listen on the network.

Development

uv sync                  # install deps
uv run pytest tests/ -v  # run tests
uv run ruff check .      # lint

Tech

• uv — package manager

• FastMCP — MCP server framework

• ddgs / httpx — search + HTTP

• trafilatura + readability-lxml — content extraction (two-tier fallback)

• SQLite — investigation state

• pytest / ruff — tests and lint

Acknowledgments

The methodology and architecture stand on these shoulders:

• Sir Isaac Newton — Opticks (1704) — the Analysis→Synthesis method and the closing Queries pattern. Public domain via Project Gutenberg.

• Gerard J. Holzmann (NASA/JPL) — The Power of Ten: Rules for Developing Safety Critical Code — the template for a rule set small enough to remember and strict enough to check mechanically.

• andrej-karpathy-skills (forrestchang) — behavioral guidelines derived from Andrej Karpathy's observations on LLM coding pitfalls.

• ponytail (Dietrich Gebert) — the decision ladder and the lazy-senior-dev discipline.

• last30days-skill (mvanhorn) — inspiration for multi-source research design and the SKILL.md-as-contract pattern.

Licensed under MIT.