Features

Supported Agents

Quick Start

-- Load the extensionLOAD'acp.duckdb_extension';-- Create some sample dataCREATETABLEsales (idINT, productVARCHAR, amountDECIMAL, sale_dateDATE);INSERT INTO salesVALUES    (1,'Widget',99.99,'2024-01-15'),    (2,'Gadget',149.99,'2024-01-16'),    (3,'Widget',99.99,'2024-01-17');-- Query with natural language (statement syntax)CLAUDE what is the total revenue by product?-- Or use the table functionSELECT*FROM claude('which product has the highest average sale amount?');

Requirements

Configuration

-- Disable safe mode to allow mutations (use with caution)SET acp_safe_mode= false;-- See the agent's thinking processSET acp_show_messages= true;-- See the generated SQL before it runsSET acp_show_sql= true;-- Show analysis summarySET acp_show_summary= true;-- Show datasources and calculationsSET acp_show_datasources= true;-- Enable verbose debug outputSET acp_debug= true;-- Increase timeout for complex queriesSET acp_timeout=600;

Safety

Architecture

┌─────────────────────────────────────────────────────────────────────┐│                          DuckDB Process                             ││                                                                     ││  ┌───────────────────────────────────────────────────────────────┐  ││  │                    ACP Extension (C++)                        │  ││  │  - Parses CLAUDE statements and claude() function calls       │  ││  │  - Invokes Rust FFI for agent communication                   │  ││  │  - Executes generated SQL and returns results                 │  ││  └───────────────────────────────────────────────────────────────┘  ││                                │                                    ││                                ▼                                    ││  ┌───────────────────────────────────────────────────────────────┐  ││  │                Rust Core (duckdb_acp_core)                    │  ││  │  - ACP client: spawns agent, communicates via stdio           │  ││  │  - MCP server: HTTP server exposing run_sql, final_sql tools  │  ││  │  - Tool execution via SQL callback to C++                     │  ││  └───────────────────────────────────────────────────────────────┘  ││                    │ stdio (ACP)           ▲                        ││                    ▼                       │ HTTP (MCP)             ││             ┌─────────────┐                │                        ││             │ Claude Code │────────────────┘                        ││             └─────────────┘                                         ││                                                                     │└─────────────────────────────────────────────────────────────────────┘

How It Works

Key Design Decisions

Building from Source

Prerequisites

Build Steps

# Clone with submodulesgit clone --recurse-submodules https://github.com/yourusername/duckdb-acp.gitcd duckdb-acp# Buildmake# The extension will be at:# build/release/extension/acp/acp.duckdb_extension

Project Structure

.├── src/│   ├── acp_extension.cpp      # DuckDB extension entry point│   └── include/│       └── acp_extension.hpp  # Extension header├── duckdb_acp_core/           # Rust core library│   ├── src/│   │   ├── lib.rs             # Library entry│   │   ├── ffi.rs             # C FFI interface│   │   └── mcp_server.rs      # Embedded HTTP MCP server│   └── Cargo.toml├── duckdb/                    # DuckDB submodule└── CMakeLists.txt

Limitations

License

Acknowledgments