Claude Code Plugin Deep Dive

Overview

The Claude Code plugin (@ever-works/plugins/claude-code) is a pipeline plugin that delegates work generation to Anthropic's Claude Code CLI binary. Rather than orchestrating AI calls through the standard facade system, this plugin downloads and runs the Claude Code CLI as a subprocess, giving it a sandboxed workspace with structured prompts and a file-based communication protocol.

The plugin creates a temporary workspace work, seeds it with existing item data (for updates), executes the Claude Code CLI with detailed system and user prompts, then reads the generated JSON files from the workspace to produce the pipeline result.

• Plugin ID: claude-code
• Category: ai-tools
• Capabilities: pipeline, form-schema
• Configuration Mode: hybrid
• Source: packages/plugins/claude-code/src/

Architecture

Pipeline Steps

The Claude Code plugin defines 6 steps:

Step ID	Step Name	Est. Duration	Description
setup-claude-code	Setup Claude Code	10s	Download CLI binary, verify installation
prepare-context	Prepare Context	5s	Create workspace, seed existing data
generate-items	Generate Items	120s	Execute Claude Code CLI
collect-results	Collect Results	5s	Read generated JSON from workspace
capture-screenshots	Capture Screenshots	30s	Capture images for items
cleanup	Cleanup	2s	Remove temp files, finalize metrics

Step dependencies follow a linear chain: each step requires the previous one.

Workspace Structure

The plugin creates a temporary workspace under BASE_TEMP_DIR (/tmp/claude-code-generator):

/tmp/claude-code-generator/<work-id>/
  _meta/
    taxonomy.json       # Live taxonomy file (items, categories, tags)
    existing-items.json # Seeded existing items (for updates)
    schema.json         # Item JSON schema for validation
  items/
    <slug>.json         # Individual item files generated by CLI

The _meta/ work serves as the communication channel between the pipeline and the CLI. The CLI reads the schema and existing items, then writes generated items as individual JSON files. The taxonomy.json file is watched in real-time for progress updates via taxonomyWatcher.

CLI Binary Management

The plugin downloads the Claude Code CLI binary from a versioned distribution URL:

const CLAUDE_CODE_DIST_URL = 'https://...'; // Distribution endpoint
const DEFAULT_CLI_VERSION = '2.1.37';

The binary is cached locally and reused across generations. Version can be overridden via settings.

Configuration

Settings Schema

Field	Type	Default	Description
oauthToken	string	-	OAuth token for Claude Code authentication (x-secret, x-scope: user)
apiKey	string	-	API key alternative for authentication (x-secret, x-scope: user)
version	string	'2.1.37'	Claude Code CLI version to use
maxTurns	number	500	Maximum conversation turns for the CLI
maxBudgetUsd	number	-	Maximum budget in USD for the generation
model	string	-	Model to use (overrides CLI default)

Constants

Constant	Value	Description
BASE_TEMP_DIR	'/tmp/claude-code-generator'	Root work for workspaces
DEFAULT_CLI_VERSION	'2.1.37'	Default CLI binary version
DEFAULT_MAX_TURNS	500	Default max conversation turns
MAX_BUFFER_SIZE	10 * 1024 * 1024 (10 MB)	Max stdout/stderr buffer size
KILL_TIMEOUT_MS	5000	Timeout for graceful CLI shutdown

Capabilities

Core Capabilities

• pipeline - Full work generation delegating to Claude Code CLI
• form-schema - Dynamic form field definitions

What Makes It Different

Unlike the Standard and Agent pipelines that use the facade system for AI calls:

1. External Process - Runs Claude Code as a subprocess, not in-process AI calls
2. File-Based Communication - Uses the filesystem for input/output, not API responses
3. Autonomous CLI - The CLI has its own tool-calling capabilities (file operations, web access)
4. Real-Time Monitoring - Watches taxonomy.json for live progress updates
5. Budget Control - Supports USD budget limits via CLI flags

API Reference

Plugin Class

class ClaudeCodePlugin implements IPlugin, IPipelinePlugin<ClaudeCodeStepId>, IFormSchemaProvider {
	readonly id = 'claude-code';
	readonly name = 'Claude Code';
	readonly version = '1.0.0';
	readonly category: PluginCategory = 'ai-tools';
	readonly capabilities = ['pipeline', 'form-schema'];
	readonly executionMode = 'engine-orchestrated';

	async executeStep(
		stepId: ClaudeCodeStepId,
		context: PipelineContext,
		execContext: StepExecutionContext
	): Promise<PipelineContext>;

	getSteps(): PipelineStepDefinition<ClaudeCodeStepId>[];
	getFormSchema(): PluginFormSchema;

	async onLoad(context: PluginContext): Promise<void>;
	async onUnload(): Promise<void>;
	async healthCheck(): Promise<PluginHealthCheck>;
	getManifest(): PluginManifest;
}

Step IDs

type ClaudeCodeStepId =
	| 'setup-claude-code'
	| 'prepare-context'
	| 'generate-items'
	| 'collect-results'
	| 'capture-screenshots'
	| 'cleanup';

Implementation Details

System Prompt

The system prompt is built with these sections:

1. Role & Scope - Defines the agent as a workspace-sandboxed work curator
2. Workspace Structure - Describes the _meta/ work and file conventions
3. Item JSON Schema - Full schema for item files with all required and optional fields
4. Rules (6 rules):
   • Always write items as individual JSON files in the workspace
   • Update taxonomy.json after each batch of items
   • Never invent items without verifiable sources
   • Respect the target item count
   • Use the provided schema for validation
   • Handle errors gracefully
5. Category & Tag Rules - Naming and assignment constraints
6. Markdown Rules - Formatting requirements for item descriptions
7. Dedup Instructions - How to avoid duplicating existing items
8. Modification Workflow - Instructions for CREATE_UPDATE mode
9. Generation Target - Target item count
10. Work Context - Name, description, domain analysis

Taxonomy Watcher

The plugin monitors the taxonomy.json file for real-time progress:

// taxonomy.json structure
{
    items: Array<{ slug: string; name: string; category?: string }>,
    categories: string[],
    tags: string[],
    progress: { current: number; target: number; percentage: number }
}

The watcher emits progress events that are forwarded to the UI, giving users real-time visibility into generation progress.

CLI Execution

The CLI is spawned as a child process with:

• System prompt passed via --system-prompt flag or temp file
• User prompt as the main input
• --max-turns flag for conversation limit
• --max-budget-usd flag for cost control
• --model flag for model override
• Working work set to the workspace
• stdout/stderr captured with MAX_BUFFER_SIZE limit
• Graceful shutdown with KILL_TIMEOUT_MS timeout

Result Collection

After CLI execution, the collect-results step:

1. Reads all .json files from the items/ work
2. Validates each against the item schema
3. Reads the final taxonomy.json for categories and tags
4. Constructs the pipeline result with items, categories, tags, and metrics

Usage Examples

Basic Generation

const request = {
	prompt: 'Create a work of Kubernetes tools and operators',
	config: {
		target_items: 40,
		capture_screenshots: true
	}
};

// Plugin settings (configured per-user)
const settings = {
	oauthToken: 'user-oauth-token', // or apiKey
	maxTurns: 500,
	maxBudgetUsd: 5.0
};

With Model Override

const settings = {
	apiKey: 'sk-ant-...',
	model: 'claude-sonnet-4-20250514',
	maxTurns: 300,
	maxBudgetUsd: 3.0
};

Error Handling

CLI Process Errors

Error	Handling
Binary download failure	Step fails with descriptive error, suggests checking network
CLI spawn failure	Logs error, reports to user, cleanup runs
CLI timeout	Process killed after KILL_TIMEOUT_MS, partial results collected
Buffer overflow	Process killed when stdout exceeds MAX_BUFFER_SIZE
Non-zero exit code	Logs stderr, attempts to collect partial results

Workspace Errors

Error	Handling
Work creation failure	Step fails with filesystem error
File read failure	Individual items skipped, valid items collected
Invalid JSON in item files	Item skipped with warning, others processed
Missing taxonomy.json	Falls back to items-only collection without categories

Authentication Errors

The plugin requires either oauthToken or apiKey. If neither is configured:

• healthCheck() returns unhealthy status
• setup-claude-code step fails with a clear message directing user to configure credentials

Cleanup

The cleanup step always runs, even after failures:

• Removes the temporary workspace work
• Kills any lingering CLI processes
• Finalizes and reports metrics

Related Plugins

• Standard Pipeline - Deterministic 15-step alternative
• Agent Pipeline - Autonomous tool-calling alternative
• AI Provider plugins - Not directly used (CLI handles its own AI calls), but may share the same API keys
• Screenshot plugins (ScreenshotOne, Urlbox) - Used by capture-screenshots step via ScreenshotFacade