pi-caido

An official-grade extension for the Pi Coding Agent (pi) that attaches the agent to the Caido Web Security Proxy and consumes Caido's built-in Model Context Protocol (MCP) server over Streamable HTTP.

🌟 Overview

pi-caido bridges your AI coding assistant directly with Caido, the lightweight web security audit proxy:

1. Consume Caido MCP: Gives the Pi LLM direct access to Caido's 81+ native MCP tools (HTTP request history, HTTPQL queries, active fuzzing/automation, sitemaps, Replay collections, tamper rules, WebSocket/SSE streams, and security findings).
2. Attach to Caido Web Proxy: Routes outgoing HTTP/HTTPS traffic generated by Pi, its tools, or browser subagents through Caido's intercepting proxy (127.0.0.1:8080) for full real-time visibility, inspection, and auditing.

┌─────────────────────────────────────────────────────────┐
│                     Pi Coding Agent                     │
│  ┌────────────────────────┐   ┌──────────────────────┐  │
│  │    LLM Tool Calling    │   │ Outgoing Web Traffic │  │
│  │ (HTTPQL, Replay, Find) │   │ (Tools / Subagents)  │  │
│  └───────────┬────────────┘   └──────────┬───────────┘  │
└──────────────┼───────────────────────────┼──────────────┘
               │ JSON-RPC 2.0 / SSE        │ HTTP / HTTPS Proxy
               ▼                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Caido Web Proxy                      │
│  ┌────────────────────────┐   ┌──────────────────────┐  │
│  │ Streamable HTTP MCP    │   │ Intercepting Proxy   │  │
│  │  http://127.0.0.1:3333 │   │  http://127.0.0.1:8080 │
│  └────────────────────────┘   └──────────────────────┘  │
└─────────────────────────────────────────────────────────┘

🚀 Key Features

• ⚡ Streamable HTTP MCP Integration: Connects via JSON-RPC 2.0 with Server-Sent Events (SSE) support directly to Caido's native endpoint (http://127.0.0.1:3333/mcp).
• 🔍 Full HTTP History Inspection: Query captured requests with native HTTPQL syntax (e.g. req.host.eq:"example.com", req.status.eq:403).
• 🎯 Security Findings Management: Automatically or manually log discovered vulnerabilities into Caido's finding dashboard with request associations.
• 🔁 Replay & Raw Request Dispatch: Inspect, modify, and replay HTTP requests directly from the chat interface.
• 🌐 Auditing Proxy Routing: One-click proxy toggle (/caido proxy on) to inspect outgoing traffic in Caido. Automatically handles TLS certificate interception.
• 📊 TUI Status Bar Badge: Displays live connection status and discovered tool count in the Pi terminal footer.
• 🛠️ Curated & Dynamic Tools: Provides high-efficiency security tools optimized for LLM token usage, plus a generic invoker (caido_call_mcp) providing access to all 81 native Caido MCP tools.

📦 Installation

Option 1: Install into Pi via NPM Package

Add pi-caido to your Pi configuration (~/.pi/agent/settings.json):

{
  "packages": [
    "npm:pi-caido"
  ]
}

Or install globally:

npm install -g pi-caido

Option 2: Load Locally for Development

Clone and link the extension:

git clone https://github.com/KanyCrew/pi-caido.git
cd pi-caido
npm install
npm run build

Run Pi with the extension:

pi -e ./dist/index.js

⚙️ Configuration

pi-caido works out of the box with Caido's defaults. To customize endpoints, create a configuration file or set environment variables:

Configuration File (~/.pi/agent/caido.json or .caido.json):

{
  "mcpUrl": "http://127.0.0.1:3333/mcp",
  "proxyUrl": "http://127.0.0.1:8080",
  "proxyEnabled": false,
  "timeoutMs": 15000,
  "allowInsecureTls": true
}

Environment Variables:

| Variable | Default | Description | |---|---|---| | CAIDO_MCP_URL | http://127.0.0.1:3333/mcp | Caido Streamable HTTP MCP endpoint | | CAIDO_PROXY_URL | http://127.0.0.1:8080 | Caido upstream proxy address | | CAIDO_PROXY_ENABLED | false | Enable proxy routing on startup (1 or true) | | CAIDO_API_KEY | (optional) | Authorization bearer token for Caido |

⌨️ Slash Commands (/caido)

Inside Pi interactive mode, use the /caido slash command:

| Command | Description | |---|---| | /caido status | View MCP connection health, server info, tool count, and proxy status | | /caido connect [url] | Connect or reconnect to the Caido MCP server | | /caido disconnect | Disconnect from Caido MCP | | /caido proxy on [url] | Route outgoing Pi traffic through Caido intercepting proxy | | /caido proxy off | Restore direct network routing | | /caido proxy status | Show current proxy routing state | | /caido tools | List all discovered tools from Caido | | /caido help | Show the interactive command guide |

🤖 Available LLM Tools

When the extension is loaded, Pi's model can call these tools:

| Tool Name | Description | |---|---| | caido_status | Check MCP and web proxy connection status and health. | | caido_list_requests | Search HTTP requests in Caido using HTTPQL filters (e.g. req.host.eq:"api.target.com"). | | caido_get_request | Inspect full request and response headers and bodies by request ID. | | caido_send_request | Send raw HTTP requests or trigger replay tasks through Caido. | | caido_create_finding | Record security findings and vulnerabilities directly in Caido. | | caido_list_scopes | Retrieve configured allowlist and denylist scope definitions. | | caido_call_mcp | Execute any of the 81 native Caido MCP tools dynamically (e.g. list_tamper_rules, get_sitemap_entries_by_ids). |

🛠️ Development & Testing

# Clone the repository
git clone https://github.com/KanyCrew/pi-caido.git
cd pi-caido

# Install dependencies
npm install

# Typecheck TypeScript
npm run typecheck

# Build bundled distribution
npm run build

# Run unit tests
npm test

📤 Publishing to GitHub

git remote add origin https://github.com/KanyCrew/pi-caido.git
git push -u origin main

📄 License

MIT © 2026 KanyCrew