spiceflow/CLAUDE.md

CLAUDE.md

Commands

./script/dev              # Start backend + frontend
./script/test             # Run E2E tests

Backend

cd server
clj -M:dev                # Start REPL with dev tools
clj -M:run                # Start server (production mode)
clj -M:test               # Run unit tests

REPL commands:

(go)                      ; Start server + file watcher
(reset)                   ; Reload code
(stop)                    ; Stop server

Frontend

cd client
npm install
npm run dev               # Dev server
npm run build             # Production build
npm run check             # TypeScript check

E2E Tests

cd e2e
npm test
npm run test:headed       # Visible browser
npm run test:ui           # Interactive explorer

Architecture

Backend

server/src/spiceflow/
├── core.clj              # Entry point
├── config.clj            # Settings from config.edn
├── db/
│   ├── protocol.clj      # DataStore interface
│   ├── sqlite.clj        # SQLite implementation
│   └── memory.clj        # In-memory (tests)
├── adapters/
│   ├── protocol.clj      # AgentAdapter interface
│   ├── claude.clj        # Claude Code CLI
│   ├── opencode.clj      # OpenCode CLI
│   └── tmux.clj          # Terminal multiplexer
├── api/
│   ├── routes.clj        # HTTP endpoints
│   └── websocket.clj     # Real-time streaming
└── session/
    └── manager.clj       # Session lifecycle

Frontend

client/src/
├── routes/               # SvelteKit file-based routing
│   ├── +layout.svelte
│   ├── +page.svelte      # Home (session list)
│   └── session/[id]/+page.svelte
├── lib/
│   ├── api.ts            # HTTP + WebSocket client
│   ├── stores/sessions.ts
│   └── components/
└── app.css               # Tailwind

Protocols

Database and CLI adapters use protocols for swappability:

(defprotocol DataStore
  (get-sessions [this])
  (save-message [this msg]))

(defprotocol AgentAdapter
  (spawn-session [this session])
  (send-message [this session msg]))

API Endpoints

Endpoint	Method	Description
/api/health	GET	Health check
/api/sessions	GET	List sessions
/api/sessions	POST	Create session
/api/sessions/:id	GET	Get session with messages
/api/sessions/:id	PATCH	Update session
/api/sessions/:id	DELETE	Delete session
/api/sessions/:id/send	POST	Send message
/api/sessions/:id/permission	POST	Handle permission
/api/sessions/:id/terminal	GET	Get tmux content
/api/sessions/:id/terminal/input	POST	Send tmux input
/api/ws	WebSocket	Event streaming

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
OPENCODE_CMD	opencode	OpenCode binary

Testing Changes

Always test changes before considering them complete. Choose the appropriate testing method:

1. E2E Tests (Playwright)

For UI changes, user flows, and integration between frontend/backend:

cd e2e && npm test                    # Run all E2E tests
cd e2e && npm run test:headed         # Visible browser for debugging
cd e2e && npm test -- -g "test name"  # Run specific test

2. Unit Tests (Clojure)

For backend logic, pure functions, and isolated components:

cd server && clj -M:test              # Run all unit tests

3. REPL Testing

For quick one-off validation of Clojure code during development:

;; In REPL (clj -M:dev, then (go))
(require '[spiceflow.some-ns :as ns])
(ns/some-function arg1 arg2)          ; Test function directly

4. Manual API Testing

For testing HTTP endpoints directly:

# Health check
curl http://localhost:3000/api/health

# List sessions
curl http://localhost:3000/api/sessions

# Create session
curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"provider": "claude"}'

# Get session
curl http://localhost:3000/api/sessions/:id

When to Use Each

Change Type	Recommended Testing
UI component	E2E tests
API endpoint	Manual API + unit tests
Business logic	Unit tests + REPL
User flow	E2E tests
Bug fix	Add regression test + manual verify

Subdirectory CLAUDE.md Files

Each directory has specific details:

• server/ - REPL workflow, Mount lifecycle
• server/src/spiceflow/db/ - Schema, queries
• server/src/spiceflow/adapters/ - Adding adapters
• server/src/spiceflow/api/ - HTTP handlers, WebSocket
• server/src/spiceflow/session/ - Session state
• client/ - SvelteKit, PWA
• client/src/lib/ - API client, stores
• client/src/routes/ - Pages, routing
• e2e/ - E2E tests