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