Spiceflow

AI Session Orchestration PWA for monitoring and interacting with Claude Code and OpenCode sessions.

"The spice must flow."

Architecture

┌─────────────────┐     ┌─────────────────────────┐     ┌─────────────────┐
│  Claude Code    │<--->│     Spiceflow Server    │<--->│   PWA Client    │
│  (CLI)          │     │       (Clojure)         │     │    (Svelte)     │
└─────────────────┘     │                         │     └─────────────────┘
                        │  ┌─────────────────┐    │
┌─────────────────┐     │  │ SQLite + DB     │    │
│  OpenCode       │<--->│  │ Abstraction     │    │
│  (CLI)          │     │  │ WebSocket/SSE   │    │
└─────────────────┘     │  └─────────────────┘    │
                        └─────────────────────────┘

Quick Start

Prerequisites

• Clojure CLI (deps.edn)
• Node.js 18+ and pnpm
• SQLite

Server

cd server
clj -M:run

The server will start on http://localhost:3000.

Client

cd client
pnpm install
pnpm dev

The client dev server will start on http://localhost:5173 with proxy to the API.

Production Build

# Build client
cd client
pnpm build

# Run server (serves static files from client/build)
cd ../server
clj -M:run

Features

Permission Handling

When Claude Code requests permission for tools, Spiceflow intercepts and presents them for approval:

• Accept: Grant permission and continue
• Deny: Reject the request
• Steer ("No, and..."): Redirect Claude with alternative instructions

Supported tool types with human-readable descriptions:

• Bash - Shell commands (shows the command)
• Write - File creation (shows file path + diff preview)
• Edit - File modification (shows file path + diff preview)
• WebFetch - URL fetching (shows URL)
• WebSearch - Web searches (shows query)
• NotebookEdit - Jupyter notebook edits
• Skill - Slash command execution

Auto-Accept Edits

Claude sessions can enable "Auto-accept edits" via the settings gear icon to automatically grant file operation permissions:

• Applies to: Write and Edit tools only (file create/modify)
• Does NOT apply to: Bash, WebFetch, WebSearch, or other tools
• Behavior: Permission is recorded in message history (green "accepted" status) without user interaction
• Use case: Reduces interruptions during coding sessions when you trust Claude to make file changes

Real-time Streaming

Messages stream in real-time via WebSocket with:

• Content deltas as Claude types
• Permission request notifications
• Working directory updates
• Session status changes

API Endpoints

Method	Path	Description
GET	/api/health	Health check
GET	/api/sessions	List all tracked sessions
POST	/api/sessions	Create/import a session
GET	/api/sessions/:id	Get session with messages
DELETE	/api/sessions/:id	Delete a session
POST	/api/sessions/:id/send	Send message to session
GET	/api/discover/claude	Discover Claude Code sessions
GET	/api/discover/opencode	Discover OpenCode sessions
POST	/api/import	Import a discovered session
WS	/api/ws	WebSocket for real-time updates

Development

Running Tests

# Server tests
cd server
clj -M:test

# Client type checking
cd client
pnpm check

Project Structure

spiceflow/
├── server/                      # Clojure backend
│   ├── deps.edn
│   ├── src/spiceflow/
│   │   ├── core.clj             # Entry point
│   │   ├── config.clj           # Configuration
│   │   ├── db/
│   │   │   ├── protocol.clj     # DataStore protocol
│   │   │   ├── sqlite.clj       # SQLite implementation
│   │   │   └── memory.clj       # In-memory impl for tests
│   │   ├── adapters/
│   │   │   ├── protocol.clj     # AgentAdapter protocol
│   │   │   ├── claude.clj       # Claude Code adapter
│   │   │   └── opencode.clj     # OpenCode adapter
│   │   ├── api/
│   │   │   ├── routes.clj       # REST endpoints
│   │   │   └── websocket.clj    # WebSocket handlers
│   │   └── session/
│   │       └── manager.clj      # Session lifecycle
│   └── test/spiceflow/
│
├── client/                      # SvelteKit PWA
│   ├── src/
│   │   ├── routes/              # SvelteKit routes
│   │   └── lib/
│   │       ├── api.ts           # API client
│   │       ├── stores/          # Svelte stores
│   │       └── components/      # UI components
│   └── static/                  # PWA assets
│
└── README.md

Configuration

Server

Configuration via resources/config.edn or environment variables:

Variable	Default	Description
SPICEFLOW_PORT	3000	Server port
SPICEFLOW_HOST	0.0.0.0	Server host
SPICEFLOW_DB	spiceflow.db	SQLite database path
CLAUDE_SESSIONS_DIR	~/.claude/projects	Claude sessions directory
OPENCODE_CMD	opencode	OpenCode command

PWA Icons

Generate PWA icons from the SVG favicon:

cd client/static
# Use a tool like svg2png or imagemagick to generate:
# - pwa-192x192.png
# - pwa-512x512.png
# - apple-touch-icon.png (180x180)

License

MIT