107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
# Spiceflow
|
|
|
|
The ~~spice~~ *tokens* must flow.
|
|
|
|
A mobile-friendly web app for controlling AI coding assistants (Claude Code, OpenCode) remotely.
|
|
|
|
```
|
|
Your Phone/Browser <-> Spiceflow Server <-> Claude Code CLI (on your computer)
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
./script/dev # Start everything
|
|
# Backend: http://localhost:3000
|
|
# Frontend: http://localhost:5173
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ HTTP/WS ┌──────────────────┐ stdin/stdout ┌─────────────────┐
|
|
│ Your Browser │ <──────────────> │ Spiceflow │ <─────────────────> │ Claude Code │
|
|
│ (SvelteKit) │ │ Server (Clojure)│ │ CLI │
|
|
└─────────────────┘ └────────┬─────────┘ └─────────────────┘
|
|
│
|
|
v
|
|
┌─────────────────┐
|
|
│ SQLite DB │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
spiceflow/
|
|
├── server/ # Clojure backend (API, database, CLI integration)
|
|
├── client/ # SvelteKit frontend (PWA, UI components)
|
|
└── e2e/ # Playwright tests
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
| Concept | Description |
|
|
|---------|-------------|
|
|
| **Session** | A conversation with Claude Code. Has messages, settings, and working directory. |
|
|
| **Adapter** | Code that talks to a CLI (Claude, OpenCode, tmux). |
|
|
| **Permission** | When Claude wants to edit files or run commands, you must approve. |
|
|
|
|
## How a Message Flows
|
|
|
|
1. Browser sends POST to `/api/sessions/:id/send`
|
|
2. Server saves user message, starts CLI with `--resume`
|
|
3. Server sends message to CLI stdin
|
|
4. CLI outputs JSONL (one JSON per line)
|
|
5. Server parses JSONL, broadcasts via WebSocket
|
|
6. Browser shows streaming response
|
|
7. Server saves assistant message when done
|
|
|
|
## Features
|
|
|
|
### Permission Handling
|
|
|
|
When Claude wants to edit files or run commands:
|
|
- **Accept**: Allow the action
|
|
- **Deny**: Block it
|
|
- **Steer**: Say "No, but do this instead..."
|
|
|
|
### Auto-Accept Edits
|
|
|
|
Enable in session settings to auto-approve `Write` and `Edit` tools only. Does not auto-approve `Bash`, `WebFetch`, etc.
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| Backend | Clojure 1.11, Ring/Jetty, Reitit, SQLite |
|
|
| Frontend | SvelteKit 2.5, Svelte 4, TypeScript, Tailwind |
|
|
| Testing | Playwright, Kaocha |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Backend
|
|
cd server && clj -M:dev # REPL: (go), (reset), (stop)
|
|
clj -M:test # Unit tests
|
|
|
|
# Frontend
|
|
cd client && npm run dev # Dev server
|
|
npm run check # TypeScript
|
|
|
|
# E2E
|
|
cd e2e && npm test # Run tests
|
|
npm run test:ui # Interactive
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Environment variables or `server/resources/config.edn`:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `SPICEFLOW_PORT` | 3000 | Server port |
|
|
| `SPICEFLOW_HOST` | 0.0.0.0 | Server host |
|
|
| `SPICEFLOW_DB` | spiceflow.db | SQLite path |
|
|
| `CLAUDE_SESSIONS_DIR` | ~/.claude/projects | Claude sessions |
|