Skip to content

PikoClaw Quickstart Guide — zero to running in 5 minutes

PikoClaw Quickstart

Get PikoClaw up and running in 5 minutes with this guide. You'll have the backend API server and frontend development environment running locally, ready to extract knowledge from email archives.

Prerequisites

Before starting, ensure you have:

  • Python 3.11 or higher — Check with python --version
  • Node.js 18 or higher — Check with node --version
  • npm 9 or higher — Check with npm --version
  • Wrangler CLI 3.x — Install with npm install -g wrangler
  • Git — For cloning the repository
  • A Cloudflare account (optional for local dev, required for production deployment)

Step 1: Clone and Install Backend

git clone https://github.com/fuzzywigg/PikoClaw.git
cd PikoClaw

# Create a Python virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -e ".[dev]"

Step 2: Install Frontend Dependencies

cd web
npm install
cd ..

Step 3: Start the Backend API Server

From the project root with your virtual environment activated:

python -m pikoclaw.server

You should see output like:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete

The API is now running at http://localhost:8000. Test it:

curl http://localhost:8000/health

Response: 

{
  "status": "ok",
  "version": "0.5.0",
  "uptime_ms": 1234
}

Step 4: Start Frontend Development Server

In a new terminal (keep the backend running):

cd web
npm run dev

You should see:

> pikoclaw-web@0.5.0 dev
> next dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Open http://localhost:3000 in your browser. You'll see the PikoClaw home page with navigation links to Search, Explore, Agents, Chat, Upload, and Demo.

Step 5: Hello World — Extract Knowledge from a Sample PST

PikoClaw includes a sample PST file for testing. Extract knowledge using the Python CLI:

# From project root with venv activated
python -m pikoclaw.cli extract samples/sample.pst --output hello-world.json

This command: 1. Reads the sample PST file 2. Extracts all messages and contacts 3. Applies PII redaction (emails masked, phone numbers redacted) 4. Clusters messages by topic 5. Builds a contact intelligence index 6. Outputs results to hello-world.json

Next Steps

  • Read the full API Reference to understand all endpoints
  • Deploy to Cloudflare using the Deployment Guide
  • Configure custom domains (api.pappas.work, dev.pappas.work)
  • Explore the test suite — Run pytest to see 40+ unit tests
  • Build your own workflow using the agent framework

Version: 0.5.0 | Last Updated: Mar 27, 2026