ccgate

Local gateway for controlling Claude Code from a webpage.

Note: This is a proof-of-concept for educational and experimental use. It demonstrates how to bridge browser-based interfaces with local CLI tools via HTTP/SSE. Use at your own discretion.

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated (claude --version)

Quick Start

npx ccgate https://myapp.example.com

This starts a local server on http://localhost:3456 that bridges HTTP/SSE requests to the Claude Code CLI, allowing requests from the specified origin (plus localhost).

How It Works

Browser  ──HTTP POST──▶  ccgate (localhost:3456)  ──spawn──▶  Claude Code CLI
   ▲                            │                                    │
   └──────── SSE stream ────────┴────────────────────────────────────┘

The gateway spawns Claude Code with --print --continue, so conversation history persists per project directory (stored in ~/.claude/projects/).

API

GET /health

Health check endpoint.

curl http://localhost:3456/health

GET /projects

Lists Claude Code projects discovered from the session store (~/.claude/projects/).

curl http://localhost:3456/projects

GET /sessions

Lists conversation sessions for a project.

curl "http://localhost:3456/sessions?cwd=/path/to/project"

Returns session metadata including sessionId, firstPrompt, created, modified, gitBranch, and projectPath. Reads from sessions-index.json when available, falling back to scanning JSONL session files.

POST /prompt

Sends a prompt to Claude Code. Returns an SSE stream.

curl -N -X POST http://localhost:3456/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello", "cwd": "/path/to/project"}'

Request body:

• prompt (required): The prompt to send
• cwd (optional): Working directory (must be under $HOME)
• sessionId (optional): Resume a specific session (uses --resume). If omitted, continues the most recent session (--continue).

SSE events:

• start - Processing started
• chunk - Response content chunk
• stderr - Stderr output from Claude
• done - Processing complete (includes exit code)
• error - Error occurred

Configuration

Usage

npx ccgate <origin>      # Start the gateway for the specified origin
npx ccgate --help        # Show help

The origin is required and must be an http(s) URL. Localhost is always allowed in addition to the specified origin.

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3456 | Port to listen on |

Security

This tool is designed for local development use only.

Capabilities

Security scanners may flag the following capabilities. Here's why each is needed:

| Capability | Why It's Needed | |------------|-----------------| | Spawns child processes | Invokes the claude CLI to handle prompts | | HTTP server | Accepts requests from your browser/webapp | | Filesystem access | Reads session data from ~/.claude/projects/ |

Security Measures

• Localhost binding: Only listens on 127.0.0.1, not accessible from other machines
• Origin enforcement: Requests with an untrusted Origin header are rejected with 403 (prevents malicious webpages from triggering CLI commands via no-cors fetch)
• CORS restrictions: Only allows requests from localhost, 127.0.0.1, and the origin specified on the command line
• Scoped filesystem reads: Only reads session data from ~/.claude/projects/ — no home directory scanning
• Path validation: The cwd parameter must resolve to a path under $HOME; symlinks are resolved to prevent traversal attacks
• Environment filtering: Only safe environment variables are passed to the Claude subprocess (blocks NODE_OPTIONS, LD_PRELOAD, etc.)
• No shell execution: Prompts are passed as array arguments to spawn(), not through a shell
• Request size limits: 1MB max request body

What This Tool Does NOT Do

• Does not make outbound network requests (Claude CLI handles its own API calls)
• Does not store or log credentials
• Does not run install scripts (postinstall, etc.)
• Has zero npm dependencies (no supply chain risk)

Threat Model

This gateway trusts any process running on localhost. If you have malicious software on your machine, it could send requests to the gateway. This is the same trust model as other local development tools (webpack-dev-server, Vite, etc.).

Not recommended for:

• Multi-user servers
• Production environments
• Machines with untrusted software

CORS Allowlist

Localhost origins (localhost:* and 127.0.0.1:*) are always allowed.

The origin you specify on the command line is the only additional origin allowed:

npx ccgate https://myapp.example.com

This explicit approach ensures you always know which origin is authorized—no hidden config files.

License

MIT