coding-agent-server

Claude Agent SDK wrapper with JWT authentication and HTTP callback support. Designed for both local development and cloud sandbox environments.

Features

• Three Running Modes: Private (local), Sandbox (SaaS), Sandbox-Debug
• JWT Authentication: Optional JWT verification for secure access
• SSE Streaming: Real-time streaming responses from Claude Agent SDK
• Session Management: Multi-turn conversation with automatic session persistence
• File Operations: Read, write, and watch file changes via SSE
• Git Integration: Track changes, commit, push, and revert with PAT support
• Dev Server Management: Start/stop development servers with dependency installation

Installation

npm install coding-agent-server
# or
pnpm add coding-agent-server

Running Modes

1. Private Mode (Local Development)

Uses local ~/.claude configuration. No JWT required, no callback needed.

{
  "mode": "private"
}

2. Sandbox Mode (SaaS)

For cloud deployments. Requires JWT secret and callback URL to fetch SDK configuration.

{
  "mode": "sandbox",
  "callbackUrl": "https://your-api.com/agent/config",
  "secret": "your-jwt-secret"
}

3. Sandbox-Debug Mode

Like Sandbox but uses local agent.json for SDK config instead of callback API.

{
  "mode": "sandbox-debug",
  "secret": "your-jwt-secret",
  "sdk": {
    "authToken": "your-anthropic-key",
    "model": "claude-sonnet-4-20250514"
  }
}

Configuration

Create agent.json in your work directory or /tmp/agent.json:

{
  "mode": "private",
  "projectId": "my-project",
  "port": 2329,
  "serverPort": 3001,
  "sdk": {
    "authToken": "sk-ant-xxx",
    "baseUrl": "https://api.anthropic.com",
    "model": "claude-sonnet-4-20250514",
    "permissionMode": "auto",
    "systemPrompt": "Optional custom system prompt"
  },
  "git": {
    "name": "Your Name",
    "email": "[email protected]",
    "autoSave": "push",
    "pat": "ghp_xxx",
    "remote": "https://github.com/user/repo.git",
    "branch": "main"
  }
}

CLI Usage

# Start with default settings
coding-agent-server

# Specify work directory
coding-agent-server --work-dir /path/to/project

# Custom ports
coding-agent-server --agent-port 2329 --server-port 3001

API Endpoints

Agent Interface

POST /chat

Send a message and receive streaming response (SSE).

Headers:

• Authorization: Bearer <jwt_token> (required in sandbox mode)

Body:

{
  "prompt": "Create a hello world function",
  "sessionId": "optional-session-id"
}

Response: SSE stream with Claude Agent SDK events

POST /chat/answer

Provide an answer to a pending question from the agent.

Body:

{
  "sessionId": "session-id",
  "answer": "Yes, proceed with the changes"
}

POST /chat/permission

Grant or deny permission for a pending tool execution.

Body:

{
  "sessionId": "session-id",
  "granted": true
}

Dev Server Management

POST /server/start

Start the development server with automatic dependency installation (SSE).

Response: SSE stream with status updates:

• installing - Installing dependencies
• installed - Dependencies installed
• starting - Starting dev server
• running - Dev server is running

POST /server/stop

Stop the running development server.

Response:

{
  "success": true,
  "message": "Dev server stopped"
}

File Operations

GET /file/get?paths=path1,path2,**/*.ts

Get file contents and watch for changes (SSE).

Response: SSE stream with file change events:

{
  "src/index.ts": {
    "content": "file content here",
    "type": "add"
  }
}

POST /file/write?path=src/index.ts

Write file content (accepts raw buffer or text).

Response:

{
  "success": true,
  "path": "src/index.ts",
  "size": 1234
}

GET /file/changes

Get current git changes (staged + unstaged).

Response:

{
  "success": true,
  "changes": [
    {
      "path": "src/index.ts",
      "status": "modified",
      "diff": "..."
    }
  ],
  "count": 1
}

POST /file/push

Save changes to git (stage + commit + push).

Body:

{
  "message": "feat: add new feature"
}

Response:

{
  "success": true,
  "commitHash": "abc123",
  "pushed": true
}

POST /file/revert

Revert the last commit. Uses git reset for unpushed commits, git revert for pushed commits.

Response:

{
  "success": true,
  "reverted": true,
  "method": "reset",
  "message": "Commit was not pushed. Reverted using reset."
}

Publishing

cd packages/coding-agent-server
npm run build
npm publish

License

MIT