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

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