cc-agent

Local HTTP server that wraps the Claude Code CLI. Run npx cc-agent in any folder — each folder gets its own sticky port, and the server uses that folder's CLAUDE.md, skills, and memory.

Install

npm i -g cc-agent
# or one-shot:
npx cc-agent

Requires the claude CLI on PATH (or pass --claude-cli <path>) and Node.js ≥ 18.

Usage

cd ~/my-project
cc-agent
# ✓ cc-agent running at http://127.0.0.1:34812 for /Users/me/my-project

# In another terminal:
curl http://127.0.0.1:34812/health
curl -X POST http://127.0.0.1:34812/query \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "say hi"}'

Endpoints

Native

• GET /health — service info (no auth).
• POST /query — one-shot, returns { sessionId, result, costUsd, durationMs, numTurns }.
• POST /stream — SSE of raw claude stream-json events.

OpenAI-compatible

• POST /v1/chat/completions — standard OpenAI chat shape. Supports stream: true.
• Claude-specific extensions via headers:
  • X-Claude-Session-Id — resume a claude session
  • X-Claude-Permission-Mode
  • X-Claude-Allowed-Tools (comma-separated)

Subcommands

cc-agent port              # print port for cwd
cc-agent status            # list all folders and live status
cc-agent forget [<path>]   # remove folder from registry
cc-agent logs [-f]         # print/tail server.log

Flags

| Flag | Default | Purpose | |---|---|---| | --bind <addr> | 127.0.0.1 | Bind address. 0.0.0.0 requires --token. | | --token <string> | none | Require Authorization: Bearer <token> on non-/health routes | | --port <n> | sticky/auto | Override the registered port | | --claude-cli <path> | auto-detect | Path to claude binary | | --permission-mode <mode> | dontAsk | Default permission mode passed to claude | | --log-file <path> | <cwd>/.cc-agent/log/server.log | Log file path | | --no-log | off | Disable file logging |

How sticky ports work

The first time you run cc-agent in a folder, it allocates a free port in 33000–39999 and records it in ~/.cc-agent/ports.json keyed by the folder's canonical path. Subsequent runs in the same folder reuse that port. Other folders are allocated different ports, even while their instances are not currently running.

Paths

• Global registry: ~/.cc-agent/ports.json
• Per-folder files: <cwd>/.cc-agent/{port,token,log/server.log}

License

MIT