Claude Code Server Development

Expert guidance for working with the claude-code-server codebase - a WebSocket server that provides a web interface for executing Claude Code CLI commands remotely with real-time output streaming.

Project Overview

This is a production-grade WebSocket server built with Express, Socket.io, and TypeScript. It manages child processes for Claude commands and streams output in real-time through WebSocket connections. The architecture emphasizes functional programming patterns, strong typing, and comprehensive test coverage.

Development Workflow

When working on this project, follow these steps:

1. **Setup and Installation**

- Run `npm install` to install all dependencies

- Verify TypeScript and Jest are properly configured

- Check that the `claude` CLI is available in your environment

2. **Development Mode**

- Use `npm run dev` for hot-reload development

- The server will restart automatically on file changes

- Default port is 3000 (configurable via `PORT` environment variable)

- Access the web UI at `http://localhost:3000`

3. **Building**

- Run `npm run build` to compile TypeScript to JavaScript

- Output files are placed in the `./dist` directory

- Production server runs from compiled JavaScript: `npm start`

- Use `npm run start:dev` to build and start in one command

4. **Testing**

- Run `npm test` for single test execution

- Use `npm run test:watch` for continuous testing during development

- Generate coverage reports with `npm run test:coverage`

- All tests should pass before committing changes

Architecture Guidelines

Functional and Type-Safe Design

This project uses **functional programming** and **strong typing** instead of class-based architecture:

**No Classes**: Use pure functions and interfaces

**Immutable State**: Process state is managed through functional transformations

**Type Safety**: All functions have explicit type signatures

**Composability**: Small, focused functions that compose together

Core Modules

1. **src/server.ts**

- Main server setup with Express and Socket.io

- HTTP endpoint configuration

- WebSocket initialization

- Server lifecycle management

2. **src/types.ts**

- Central type definitions for the entire project

- Key interfaces: `ProcessManager`, `ClaudeCommand`, `ProcessOutput`, `ServerConfig`

- All types are exported and reused throughout the codebase

3. **src/processManager.ts**

- Pure functions for process lifecycle management

- Functions operate on `ProcessManager` state object

- Process spawning: `claude -p [command]` pattern

- Single-process-per-client constraint

- Working directory validation and security

4. **src/socketHandlers.ts**

- Functional event handlers for Socket.io

- Compose process management functions with WebSocket communication

- Handle `execute-command`, `kill-process`, and related events

5. **public/index.html**

- Terminal-like web interface

- Embedded JavaScript for real-time communication

- User input and output display

Testing Architecture

The project uses **Jest with TypeScript support** (ts-jest):

**src/__tests__/processManager.test.ts**: Unit tests for process management functions

**src/__tests__/server.test.ts**: Integration tests for HTTP endpoints and WebSocket communication

**Mocking Strategy**: External `claude` command is mocked; process lifecycle events are simulated

**Security Testing**: Directory traversal and path validation are tested

Key Implementation Details

Process Management

Processes are spawned using `child_process.spawn` with the pattern: `claude -p [command]`

Only **one command can run at a time** per client

Process state is tracked in the `ProcessManager` object

Process stdin is **immediately closed** to prevent hanging on input prompts

Output (stdout/stderr) is streamed in real-time through Socket.io events

Security Model

**Working Directory Validation**: Commands must execute within a base directory

**Path Traversal Prevention**: Relative paths are validated before execution

**Base Directory Configuration**: Set via first command-line argument (default: current directory)

**CORS Configuration**: Accepts all origins (intended for VPN/trusted environments)

**System Command Execution**: Commands are executed through the Claude CLI, not arbitrary shell commands

Real-Time Communication

Socket.io events:

**Client → Server**:

- `execute-command`: Run a Claude command with optional relative working directory

- `kill-process`: Terminate the currently running process

**Server → Client**:

- `output`: Stream command output (type: stdout/stderr/system/error)

- `process-killed`: Confirmation of successful process termination

Configuration

**Port**: Set via `PORT` environment variable (default: 3000)

**Base Directory**: First command-line argument (default: `process.cwd()`)

**TypeScript Config**: Strict mode, ES2020 target, source in `./src`, output to `./dist`

Development Best Practices

1. **When Adding Features**

- Define types first in `src/types.ts`

- Write pure functions in appropriate modules

- Add unit tests for new functions

- Update integration tests if Socket.io events change

- Ensure working directory validation is maintained

2. **When Fixing Bugs**

- Write a failing test that reproduces the bug

- Fix the issue in the relevant functional module

- Verify all tests pass

- Check that security constraints still hold

3. **When Refactoring**

- Maintain functional programming patterns

- Keep functions pure and composable

- Preserve strong typing throughout

- Ensure test coverage remains high

- Do not introduce class-based patterns

4. **Code Style**

- Use explicit type annotations

- Prefer `const` over `let`

- Avoid mutation; use functional transformations

- Keep functions small and focused

- Document complex logic with comments

Important Constraints

**Functional Architecture**: Do NOT introduce classes. Use pure functions and interfaces.

**Single Process Limit**: Only one Claude command can run per client at a time.

**Working Directory Security**: All path validation must prevent directory traversal.

**Test Coverage**: New code must include unit tests. Integration tests should cover WebSocket flows.

**TypeScript Strict Mode**: All code must pass strict TypeScript checks.

**Mocked CLI in Tests**: The `claude` command must be mocked in tests to avoid external dependencies.

Common Tasks

Adding a New Socket.io Event

1. Define the event payload type in `src/types.ts`

2. Create a handler function in `src/socketHandlers.ts`

3. Register the event listener in `src/server.ts`

4. Add integration tests in `src/__tests__/server.test.ts`

5. Update the web UI in `public/index.html` if needed

Extending Process Management

1. Add new function(s) to `src/processManager.ts`

2. Ensure functions are pure and operate on `ProcessManager` state

3. Add unit tests in `src/__tests__/processManager.test.ts`

4. Update type definitions in `src/types.ts` if state shape changes

5. Compose new functions into socket handlers as needed

Modifying Security Constraints

1. Update validation logic in `src/processManager.ts`

2. Add test cases in `src/__tests__/processManager.test.ts` to verify security

3. Document the security model changes in comments

4. Test directory traversal prevention thoroughly

Files You'll Work With

**src/server.ts**: Server setup and initialization

**src/types.ts**: Type definitions (always start here when understanding the codebase)

**src/processManager.ts**: Process lifecycle and validation logic

**src/socketHandlers.ts**: WebSocket event handling

**src/__tests__/*.test.ts**: Test suites

**src/test-utils/createTestServer.ts**: Test utilities

**public/index.html**: Web UI

**package.json**: Dependencies and scripts

**tsconfig.json**: TypeScript configuration

**jest.config.js**: Jest testing configuration

Troubleshooting

**Port Already in Use**: Change `PORT` environment variable or kill the process using port 3000

**Tests Failing**: Ensure `child_process.spawn` is properly mocked; check that mock implementations match expected behavior

**TypeScript Errors**: Run `npm run build` to see detailed type errors; ensure all types are properly imported from `src/types.ts`

**Process Not Terminating**: Verify that stdin is closed immediately after spawn; check kill signal handling

Claude Code Server Development

Safety Concern

Claude Code Server Development

Project Overview

Development Workflow

Architecture Guidelines

Functional and Type-Safe Design

Core Modules

Testing Architecture

Key Implementation Details

Process Management

Security Model

Real-Time Communication

Configuration

Development Best Practices

Important Constraints

Common Tasks

Adding a New Socket.io Event

Extending Process Management

Modifying Security Constraints

Files You'll Work With

Troubleshooting

Reviews (0)