claudedeck CLAUDE.md

Project: ClaudeDeck

What this is

A self-hostable web UI + admin console for the Claude Code CLI. Multi-user streaming chat where each message spawns claude -p in an agent workspace; admins manage model / MCP / instructions / users from a panel. Open-source framework (MIT), meant to be forked and customized per deployment.

Lineage: extracted from an internal requirements-gathering service as its reusable, domain-free core. All product-specific integrations (task tracker, domain personas, document workflow) were intentionally dropped. Auth was switched from third-party OAuth to local username/password.

Architecture (load-bearing details)

• Stream-json contract. session-manager.ts spawns claude -p <msg> --output-format stream-json --include-partial-messages --max-turns N --model <m> --verbose [--resume <id>]. Streamed text arrives wrapped as stream_event.event.content_block_delta.delta.text. assistant and result.result events are ignored once streaming has been seen (seenAnyStream flag) to avoid duplicating the reply. result.is_error / non-zero exit → ClaudeCliError. The CLI version is pinned in backend/Dockerfile because this contract is version-sensitive.
• Marker parser (claude/marker-parser.ts, pure, unit-tested). Three-state machine (IDLE / INSIDE_ARTIFACT / INSIDE_QUESTIONS). Filters two block types from visible text: <<<ARTIFACT>>>…<<<ARTIFACT_END>>> (final markdown doc) and <<<QUESTIONS>>>…<<<QUESTIONS_END>>> (JSON questions, strict schema: ≤20 questions × ≤20 options × ≤500 chars, id [a-zA-Z0-9_-], type single|multi|text). ARTIFACT wins over QUESTIONS. Robust to markers split across chunks, 64 KB buffer overrun, invalid JSON, unclosed blocks. Don't change marker strings without updating the parser, tests, and agents/*/CLAUDE.md together.
• Agents = workspace directories under agents/<key>/ (CLAUDE.md + .claude/rules/*.md + .mcp.json + .claude/settings.json) + a row in the agents table (key, label, enabled, sort, workspace_dir, config JSONB with optional model). _base is the scaffold template. CLI cwd = the agent workspace, so each agent is isolated (no CLAUDE.md walk-up contamination — agents/ itself has no CLAUDE.md). Model resolves agent.config.model → global claude_model → 'sonnet'.
• MCP admin (claude/mcp-admin.ts). Writes .mcp.json (definitions) AND .claude/settings.json (enabledMcpjsonServers + permissions.allow: mcp__<name>) together — both are needed for tools to work in non-interactive claude -p. UI accepts only http/sse (RCE prevention). Live status via claude mcp list, filtered to the agent's own servers.
• Auth. Local username/password (auth/password.ts — scrypt; auth/local-auth.ts — routes + first-admin bootstrap; auth/access.ts — requireAuth/requireAdmin + user management). Session is the standard express-session cookie; the WS layer in index.ts reads & HMAC-verifies it directly.
• Sessions are active | expired only (cron expires idle ones; any user message revives an expired one). The latest artifact is stored in sessions.last_artifact. No task/finalize workflow (that was domain-specific and removed).
• Schema lives in db/migrations/001_init.sql, applied idempotently by db/migrate.ts on startup (works for Docker and external DBs). Tables: users, agents, sessions, messages, settings.