# 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 |