Development

Guide to running ClaudeControl locally for development and contributing.

Stack

• Backend: Node.js + TypeScript (pure http module, no Express)
• Frontend: Vite + React + Tailwind CSS
• SDK: @anthropic-ai/claude-agent-sdk
• Tests: Playwright (E2E)

Project structure

claude-control/
  backend/
    server.ts          # HTTP server entry point
    config.ts          # Configuration management
    constants.ts       # Shared constants (WS events, status enums)
    types.ts           # TypeScript type definitions
    ws.ts              # WebSocket server
    http.ts            # HTTP routing helpers
    workspaces.ts      # Workspace persistence
    sessions.ts        # SDK session management
    agents/
      store.ts         # Agent state, persistence, indexes
      lifecycle.ts     # Agent creation, messaging, delegation
      roles.ts         # Role detection from project files
      spawn-requests.ts # Multi-agent spawn request handling
    routes/
      agents.ts        # Agent API routes
      workspaces.ts    # Workspace API routes
      settings.ts      # Settings and auth routes
      files.ts         # File browsing routes
      git.ts           # Git integration routes
  frontend/
    src/
      components/      # React components
      hooks/           # Custom React hooks
      lib/             # Utilities and API client
    public/            # Static assets
    index.html         # Entry point
  tests/
    e2e/               # Playwright E2E tests
  bin/
    claudecontrol.js   # CLI entry point
  scripts/             # Build and release scripts

Running locally

Start the backend and frontend in separate terminals:

Backend (default port 12000):

cd backend && PORT=12000 npm run dev

Frontend (default port 12500):

cd frontend && npm run dev

The frontend Vite dev server proxies API requests to the backend using the VITE_API_URL value from frontend/.env.

Building

Build the frontend for production:

cd frontend && npm run build

Type-check the backend:

cd backend && node_modules/.bin/tsc --noEmit

In production mode, the backend serves the built frontend from frontend/dist/.

Testing

Run the E2E test suite with Playwright:

npm run test:e2e

This requires both backend and frontend to be running. The test suite expects the backend on port 4000 by default.

Run a faster subset of tests:

npm run test:e2e:fast

Publishing

Bump version and publish to npm:

npm version patch
npm publish

The prepublishOnly script automatically syncs the version across version.json and validates the README.