Claude Code Plugin REST API

A NestJS module for exposing Claude agents as REST API endpoints. Supports two approaches:

File-based Plugins: Expose existing Claude Code plugins (agents, commands, skills) as HTTP endpoints
Code-based Agents: Define agents programmatically with full Claude Agent SDK options

Both approaches give you powerful REST APIs for Claude agents with streaming, authentication, and custom tooling.

Features

Two Agent Approaches: Choose file-based plugins or code-based configuration
REST API: Each agent gets its own HTTP endpoint (/v1/agents/:name or /v1/plugins/:plugin/agents/:agent)
SSE Streaming: Real-time streaming responses via Server-Sent Events
Full SDK Passthrough: AgentConfig extends SDK Options - all SDK features available
Custom Request Schemas: Accept custom JSON bodies with validation
Custom MCP Tools: Add in-process MCP servers with custom tools
Authentication: Built-in basic auth with YAML config or custom providers
Claude Max Support: Works with Claude Max subscription via terminal login

Quick Start

Prerequisites

Node.js 20+
NestJS application
Claude Max subscription (run claude login to authenticate)

Installation

npm install @tigz/claude-code-plugin-rest-api
# or
pnpm add @tigz/claude-code-plugin-rest-api
# or
yarn add @tigz/claude-code-plugin-rest-api

You'll also need NestJS peer dependencies if not already installed:

npm install @nestjs/common @nestjs/core rxjs

Approach 1: File-Based Plugins

Expose existing Claude Code plugins as REST API endpoints. This approach is perfect if you already have Claude Code plugins (agents, commands, skills) and want to make them available via HTTP.

Plugin Structure

.claude/plugins/
└── my-plugin/
    ├── .claude-plugin/
    │   └── plugin.json        # Plugin manifest
    ├── agents/
    │   └── my-agent.md        # Agent definition
    ├── commands/
    │   └── my-command.md      # Command definition
    └── skills/
        └── my-skill/
            └── SKILL.md       # Skill definition

Enable Plugin Endpoints

import { Module } from '@nestjs/common';
import { ClaudePluginModule } from '@tigz/claude-code-plugin-rest-api';

@Module({
  imports: [
    ClaudePluginModule.forRoot({
      enablePluginEndpoints: true,
      pluginDirectory: '.claude/plugins',
      hotReload: true,  // Auto-reload on file changes (dev only)
    }),
  ],
})
export class AppModule {}

Plugin API Endpoints

Method	Endpoint	Description
GET	`/v1/plugins`	List all discovered plugins
GET	`/v1/plugins/:name`	Get plugin details
POST	`/v1/plugins/:plugin/agents/:agent`	Execute plugin agent
POST	`/v1/plugins/:plugin/commands/:cmd`	Execute command
POST	`/v1/plugins/stream`	Create SSE stream session
GET	`/v1/stream/:sessionId`	Consume SSE stream
POST	`/webhook/reload`	Trigger plugin reload (for GitOps)

Execute a Plugin Agent

# Request/Response mode
curl -X POST http://localhost:3000/v1/plugins/my-plugin/agents/my-agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d '{"prompt": "Analyze this code"}'

# Response
{
  "success": true,
  "result": "The code analysis shows...",
  "cost": 0.03,
  "turns": 2,
  "usage": { "inputTokens": 890, "outputTokens": 234 }
}

Stream Plugin Responses

# 1. Create stream session
SESSION=$(curl -s -X POST http://localhost:3000/v1/plugins/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d '{"plugin": "my-plugin", "agent": "my-agent", "prompt": "Explain this"}' \
  | jq -r '.sessionId')

# 2. Consume SSE stream
curl -N http://localhost:3000/v1/stream/$SESSION \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)"

Approach 2: Code-Based Agents

Define agents programmatically in your NestJS module with full Claude Agent SDK options. This approach gives you maximum flexibility and type safety.

Define Agents in Code

import { Module } from '@nestjs/common';
import { ClaudePluginModule } from '@tigz/claude-code-plugin-rest-api';

@Module({
  imports: [
    ClaudePluginModule.forRoot({
      agents: {
        // Full-access agent with all tools pre-approved
        'uber-agent': {
          systemPrompt: 'You are a powerful coding assistant with full access.',
          permissionMode: 'bypassPermissions',
          tools: { type: 'preset', preset: 'claude_code' },
          maxTurns: 50,
          maxBudgetUsd: 10.0,
        },

        // Read-only analyst - can only read, not modify
        'code-reviewer': {
          systemPrompt: 'Review code for quality, security, and best practices.',
          allowedTools: ['Read', 'Glob', 'Grep'],
          permissionMode: 'default',
          maxTurns: 20,
        },

        // Task executor with custom MCP servers
        'task-runner': {
          systemPrompt: 'Execute tasks autonomously.',
          permissionMode: 'bypassPermissions',
          tools: { type: 'preset', preset: 'claude_code' },
          mcpServers: {
            database: myDatabaseMcpServer,
            slack: mySlackMcpServer,
          },
        },
      },
    }),
  ],
})
export class AppModule {}

Agent API Endpoints

Each agent is automatically exposed via REST endpoints:

Method	Endpoint	Description
GET	`/v1/agents`	List all user-defined agents
GET	`/v1/agents/:name`	Get agent configuration
POST	`/v1/agents/:name`	Execute agent (request/response)
POST	`/v1/agents/:name/stream`	Create SSE stream session
GET	`/v1/stream/:sessionId`	Consume SSE stream

Execute an Agent

# Request/Response mode
curl -X POST http://localhost:3000/v1/agents/uber-agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d '{"prompt": "Refactor the auth module to use JWT"}'

# Response
{
  "success": true,
  "result": "I've refactored the auth module...",
  "cost": 0.05,
  "turns": 3,
  "usage": { "inputTokens": 1234, "outputTokens": 567 }
}

Stream Agent Responses

# 1. Create stream session
SESSION=$(curl -s -X POST http://localhost:3000/v1/agents/uber-agent/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d '{"prompt": "Explain this codebase"}' \
  | jq -r '.sessionId')

# 2. Consume SSE stream
curl -N http://localhost:3000/v1/stream/$SESSION \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)"

AgentConfig Options

AgentConfig extends the Claude Agent SDK's Options type, giving you full access to all SDK features plus our REST API extension (requestSchema).

Commonly Used Options

Option	Type	Description
`systemPrompt`	`string`	Agent's system prompt (required)
`model`	`string`	Model to use (default: claude-sonnet-4-5)
`cwd`	`string`	Working directory for file operations
`permissionMode`	`PermissionMode`	`'default'` \| `'acceptEdits'` \| `'bypassPermissions'`
`tools`	`ToolsConfig`	`{ type: 'preset', preset: 'claude_code' }` or tool array
`allowedTools`	`string[]`	Tool allowlist
`disallowedTools`	`string[]`	Tools to block
`mcpServers`	`Record<string, McpServerConfig>`	Custom MCP servers
`plugins`	`SdkPluginConfig[]`	Additional plugins to load
`maxTurns`	`number`	Max conversation turns
`maxBudgetUsd`	`number`	Max budget in USD
`outputFormat`	`OutputFormat`	JSON schema for structured output
`requestSchema`	`RequestSchema`	Custom request body schema (REST API extension)

Advanced SDK Options

Since AgentConfig extends the SDK's Options type, you also have access to:

Option	Type	Description
`hooks`	`Record<HookEvent, HookCallbackMatcher[]>`	Hook callbacks for events
`agents`	`Record<string, AgentDefinition>`	Custom subagent definitions
`sandbox`	`SandboxSettings`	Sandbox configuration
`settingSources`	`SettingSource[]`	Load settings from filesystem
`betas`	`SdkBeta[]`	Beta features (e.g., `'context-1m-2025-08-07'`)
`maxThinkingTokens`	`number`	Limit model thinking tokens
`fallbackModel`	`string`	Fallback if primary model fails
`enableFileCheckpointing`	`boolean`	Track file changes for rewind

See the Claude Agent SDK documentation for the complete list of options.

Key Options Explained

permissionMode: 'bypassPermissions': Pre-approves all tool uses - no confirmation needed
tools: { type: 'preset', preset: 'claude_code' }: Enables all Claude Code built-in tools
allowedTools: Restrict agent to specific tools only
mcpServers: Add custom MCP servers for database, APIs, etc.
settingSources: Load skills from user/project settings
outputFormat: Enforce structured JSON output with schema validation
hooks: Respond to events like PreToolUse, PostToolUse, SessionStart
agents: Define custom subagents for the Task tool

Re-exported SDK Types

For convenience, commonly used SDK types are re-exported from the package:

import type {
  Options,              // Full SDK options type
  PermissionMode,       // 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'
  OutputFormat,         // JSON schema output format
  McpServerConfig,      // MCP server configuration
  AgentDefinition,      // Subagent definitions
  SDKMessage,           // Union of all message types
  SDKResultMessage,     // Result message type
  Query,                // AsyncGenerator with control methods
} from '@tigz/claude-code-plugin-rest-api';

Structured Output Example

Use outputFormat to get validated JSON responses:

ClaudePluginModule.forRoot({
  agents: {
    'code-analyzer': {
      systemPrompt: 'Analyze code and return structured results.',
      outputFormat: {
        type: 'json_schema',
        schema: {
          type: 'object',
          properties: {
            summary: { type: 'string' },
            score: { type: 'number', minimum: 0, maximum: 10 },
            issues: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  severity: { type: 'string', enum: ['low', 'medium', 'high'] },
                  message: { type: 'string' },
                  line: { type: 'number' }
                },
                required: ['severity', 'message']
              }
            }
          },
          required: ['summary', 'score'],
          additionalProperties: false
        }
      }
    }
  }
})

The response includes structuredOutput with validated JSON:

{
  "success": true,
  "result": "...",
  "structuredOutput": {
    "summary": "Well-structured code with minor issues",
    "score": 8,
    "issues": [
      { "severity": "low", "message": "Consider adding type annotations", "line": 42 }
    ]
  }
}

Raw Response Mode

For agents with outputFormat, the API automatically returns the structured JSON directly (raw response mode). You can override this behavior:

# Default behavior - returns structured JSON directly
curl -X POST http://localhost:3000/v1/agents/code-analyzer \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Analyze the number 42"}'

# Returns:
{
  "summary": "Well-structured code with minor issues",
  "score": 8,
  "issues": [...]
}

# Get wrapped response with metadata instead
curl -X POST http://localhost:3000/v1/agents/code-analyzer \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Analyze the number 42", "rawResponse": false}'

# Returns:
{
  "success": true,
  "result": "...",
  "structuredOutput": { "summary": "...", "score": 8, ... },
  "cost": 0.02,
  "turns": 1,
  "usage": { "inputTokens": 123, "outputTokens": 45 }
}

For agents without outputFormat, you can still enable raw response mode:

curl -X POST http://localhost:3000/v1/agents/math-helper \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2+2?", "rawResponse": true}'

# Returns just the text response:
The answer is 4.

Custom Request Schema (REST API Extension)

The requestSchema option lets agents accept custom JSON bodies instead of the standard {prompt: string} format:

ClaudePluginModule.forRoot({
  agents: {
    'order-processor': {
      systemPrompt: 'Process orders and return confirmation.',
      requestSchema: {
        schema: {
          type: 'object',
          properties: {
            orderId: { type: 'string' },
            items: { type: 'array', items: { type: 'object' } },
          },
          required: ['orderId', 'items'],
        },
        promptTemplate: 'Process this order:\n{{json}}',
      },
      outputFormat: {
        type: 'json_schema',
        schema: {
          type: 'object',
          properties: {
            confirmed: { type: 'boolean' },
            total: { type: 'number' },
          },
          required: ['confirmed', 'total'],
        },
      },
      permissionMode: 'bypassPermissions',
    },
  },
})

Now the agent accepts custom JSON directly:

curl -X POST http://localhost:3000/v1/agents/order-processor \
  -H "Content-Type: application/json" \
  -d '{"orderId": "123", "items": [{"sku": "ABC", "qty": 2}]}'

# Returns:
{"confirmed": true, "total": 49.99}

Custom MCP Tools Example

Create in-process MCP servers with custom tools using createSdkMcpServer and tool:

import { ClaudePluginModule, createSdkMcpServer, tool, z } from '@tigz/claude-code-plugin-rest-api';

// Create an in-process MCP server with custom tools
const calculatorServer = createSdkMcpServer({
  name: 'calculator',
  version: '1.0.0',
  tools: [
    tool(
      'add',
      'Add two numbers together',
      { a: z.number(), b: z.number() },
      async (args) => ({
        content: [{ type: 'text', text: `${args.a + args.b}` }],
      }),
    ),
    tool(
      'multiply',
      'Multiply two numbers together',
      { a: z.number(), b: z.number() },
      async (args) => ({
        content: [{ type: 'text', text: `${args.a * args.b}` }],
      }),
    ),
  ],
});

@Module({
  imports: [
    ClaudePluginModule.forRoot({
      agents: {
        'calculator-agent': {
          systemPrompt: 'Use the calculator tools to perform calculations.',
          permissionMode: 'bypassPermissions',
          mcpServers: {
            calculator: calculatorServer,
          },
          // MCP tools follow the pattern: mcp__<server-name>__<tool-name>
          allowedTools: ['mcp__calculator__add', 'mcp__calculator__multiply'],
        },
      },
    }),
  ],
})
export class AppModule {}

MCP tools run in the same process as your NestJS application, enabling:

Custom business logic tools
Database access tools
External API integrations
Any async operation

Combining Both Approaches

You can use both file-based plugins and code-based agents together:

ClaudePluginModule.forRoot({
  // Code-based agents
  agents: {
    'code-assistant': {
      systemPrompt: 'You are a coding assistant.',
      permissionMode: 'bypassPermissions',
    },
  },

  // Also enable file-based plugins
  enablePluginEndpoints: true,
  pluginDirectory: '.claude/plugins',
})

This gives you:

/v1/agents/code-assistant - code-based agent
/v1/plugins/my-plugin/agents/my-agent - file-based plugin agent

Self-Improving Agents

Build agents that can modify their own plugin files and submit changes for human review via GitOps. This enables autonomous self-improvement while maintaining human oversight.

How It Works

Git Worktrees: Agents use git worktree to make changes in isolation without affecting the running server
PR-based Review: All changes go through pull requests for human approval
Hot Reload: After PR merge, plugins reload via webhook or file watcher
Rollback on Failure: Plugin discovery preserves previous state if reload fails

Example Self-Improving Agent

ClaudePluginModule.forRoot({
  enablePluginEndpoints: true,
  pluginDirectory: '.claude/plugins',
  hotReload: process.env.NODE_ENV === 'development',
  agents: {
    'self-improver': {
      systemPrompt: `You are a self-improving agent. When you identify improvements:
        1. Create a git worktree: git worktree add ../$NAME -b improve/$NAME
        2. Make changes in the worktree (not the main directory)
        3. Commit and create a PR for human review
        4. Clean up: git worktree remove ../$NAME`,
      permissionMode: 'bypassPermissions',
      allowedTools: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
      maxTurns: 30,
    },
  },
})

Webhook for GitOps Reload

After merging a PR that modifies plugin files, trigger a reload:

curl -X POST http://localhost:3000/webhook/reload \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)"

# Response: { "reloaded": true, "pluginCount": 3 }

Add this to your GitHub Actions workflow:

- name: Trigger plugin reload
  if: contains(github.event.head_commit.modified, '.claude/plugins/')
  run: |
    curl -X POST https://your-server.com/webhook/reload \
      -H "Authorization: Basic ${{ secrets.API_AUTH }}"

Graceful Shutdown

Enable graceful shutdown to wait for in-flight requests during restarts:

// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableShutdownHooks();  // Wait for requests to complete
  await app.listen(3000);
}

Configuration

Module Options

ClaudePluginModule.forRoot({
  // Code-based agents
  agents: { ... },

  // File-based plugin discovery
  enablePluginEndpoints: false,        // Set true to enable /v1/plugins/* endpoints
  pluginDirectory: '.claude/plugins',  // Directory for file-based plugins
  hotReload: false,                    // Enable in development

  // Global limits
  maxTurns: 50,                        // Default max turns
  maxBudgetUsd: 10.0,                  // Default budget

  // Authentication
  auth: {
    disabled: false,                   // Set true to disable auth
    authFilePath: 'auth.yml',          // Path to YAML auth config
    excludePaths: ['/health'],         // Paths to exclude from auth
    provider: customProvider,          // Custom auth provider
  },
})

Async Configuration

ClaudePluginModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    agents: {
      'my-agent': {
        systemPrompt: config.get('AGENT_PROMPT'),
        permissionMode: 'bypassPermissions',
      },
    },
    auth: { disabled: config.get('DISABLE_AUTH') === 'true' },
  }),
  inject: [ConfigService],
})

Authentication

By default, the module uses basic auth with credentials from auth.yml:

users:
  - username: admin
    password: $2b$10$...  # bcrypt hash
  - username: dev
    password: plaintext   # Plain text (dev only!)

To disable authentication:

ClaudePluginModule.forRoot({
  auth: { disabled: true },
})

Testing

# Run e2e tests (CI-safe, no credentials needed)
pnpm test:e2e

# Run local integration tests (requires `claude login`)
pnpm test:local

Headless Server Authentication

Claude Code requires browser-based OAuth for initial login. On headless servers/VPS without a browser, use one of these methods:

Method 1: SSH Port Forwarding (Recommended)

Forward the OAuth callback port from your local machine:

# On your local machine, SSH to server with port forwarding
ssh -L 8080:localhost:8080 user@your-server

# On the server, run login
claude login

The OAuth flow will open in your local browser, but the callback reaches the server through the tunnel.

Method 2: Copy Credentials

Authenticate locally and transfer the credentials file:

# On your local machine
claude login

# Copy credentials to server
scp ~/.config/claude-code/auth.json user@server:~/.config/claude-code/

Method 3: Docker Volume Mount

For containerized deployments, mount your local credentials:

docker run -v ~/.config/claude-code/auth.json:/root/.config/claude-code/auth.json:ro your-image

Or in docker-compose:

volumes:
  - ~/.config/claude-code/auth.json:/root/.config/claude-code/auth.json:ro

Docker

cd examples/basic-server
docker-compose up

Project Structure

.
├── packages/
│   └── claude-code-plugin-rest-api/   # Core NestJS module
├── examples/
│   └── basic-server/                  # Example implementation
└── plans/                             # Design documents

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github/workflows		.github/workflows
examples/basic-server		examples/basic-server
packages/claude-code-plugin-rest-api		packages/claude-code-plugin-rest-api
plans		plans
scripts		scripts
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

Claude Code Plugin REST API

Features

Quick Start

Prerequisites

Installation

Approach 1: File-Based Plugins

Plugin Structure

Enable Plugin Endpoints

Plugin API Endpoints

Execute a Plugin Agent

Stream Plugin Responses

Approach 2: Code-Based Agents

Define Agents in Code

Agent API Endpoints

Execute an Agent

Stream Agent Responses

AgentConfig Options

Commonly Used Options

Advanced SDK Options

Key Options Explained

Re-exported SDK Types

Structured Output Example

Raw Response Mode

Custom Request Schema (REST API Extension)

Custom MCP Tools Example

Combining Both Approaches

Self-Improving Agents

How It Works

Example Self-Improving Agent

Webhook for GitOps Reload

Graceful Shutdown

Configuration

Module Options

Async Configuration

Authentication

Testing

Headless Server Authentication

Method 1: SSH Port Forwarding (Recommended)

Method 2: Copy Credentials

Method 3: Docker Volume Mount

Docker

Project Structure

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages