ChannelCoder

A streamlined SDK and CLI for Claude Code that channels your prompts with powerful features like multi-place variable interpolation, file-based prompts, and streaming support.

Installation

# Using npm
npm install channelcoder

# Using bun
bun add channelcoder

# Global CLI installation
npm install -g channelcoder

Quick Start

SDK Usage

import { claude } from 'channelcoder';

// Simple prompt
const result = await claude('What is TypeScript?');

// Template literals
const language = 'TypeScript';
await claude`Explain ${language} in simple terms`;

// File-based prompt with data
await claude('prompts/analyze.md', {
  data: { taskId: 'FEAT-123', priority: 'high' }
});

// With options
await claude('Review this code', {
  tools: ['Read', 'Grep'],
  system: 'You are a code reviewer'
});

CLI Usage

The CLI provides multiple commands for different execution modes:

# Interactive mode (default) - run Claude interactively
channelcoder interactive prompts/analyze.md -d taskId=FEAT-123

# Run mode - execute and print results
channelcoder run "Explain TypeScript"
channelcoder run prompts/analyze.md --data taskId=FEAT-123

# Stream mode - real-time streaming responses  
channelcoder stream "Write a story"
channelcoder stream prompts/generate.md

# Session management
channelcoder session list                    # List saved sessions
channelcoder session load my-session         # Load and continue a session
channelcoder session remove old-session      # Remove a session

# Worktree management
channelcoder worktree list                   # List git worktrees
channelcoder worktree create feature/new     # Create new worktree
channelcoder worktree remove feature/old     # Remove worktree

Features

🎯 Simple Function API

Mirrors Claude CLI's mental model with a simple function:

// Inline prompts
await claude('Explain quantum computing');

// File prompts (auto-detected by .md extension)
await claude('prompts/complex-analysis.md');

// With all the options you need
await claude('Debug this issue', {
  tools: ['Read', 'Bash'],
  resume: sessionId,
  maxTurns: 10
});

🔄 Variable Interpolation

Powerful multi-place variable support:

// In inline prompts
await claude('Analyze {code} for {issues}', {
  data: {
    code: 'const x = null',
    issues: ['null safety', 'type errors']
  }
});

// In file prompts
// prompts/review.md:
// Review {prTitle} with focus on {concerns ? concerns : "general quality"}
await claude('prompts/review.md', {
  data: { prTitle: 'Add auth system' }
});

🌊 Execution Modes

Different modes for different needs:

import { claude, interactive, stream, run, detached } from 'channelcoder';

// Run mode (default) - Get complete results programmatically
const result = await claude('Generate tests');
console.log(result.data);

// Stream mode - Real-time responses
for await (const chunk of stream('Write documentation')) {
  process.stdout.write(chunk.content);
}

// Interactive mode - Replace process (like running claude directly)
await interactive('Debug this error');
// ⚠️ Code after interactive() never executes!

// Detached mode - Background execution
const result3 = await detached('Long analysis task', {
  logFile: 'analysis.log'
});
console.log('Started background process:', result3.data?.pid);

// Detached streaming - Real-time background monitoring
const result4 = await detached('Generate comprehensive report', {
  logFile: 'report.log',
  stream: true  // Enables real-time JSON chunks in log file
});
// Monitor with: tail -f report.log | jq -r '.content'

🌿 Git Worktree Mode

Run Claude in isolated git worktrees for parallel development and clean experimentation:

// Simple worktree usage - auto-creates if doesn't exist
await claude('Implement new feature', { 
  worktree: 'feature/auth' 
});

// Standalone worktree function for complex workflows
await worktree('feature/payments', async (wt) => {
  console.log(`Working in: ${wt.path}`);
  await claude('Design payment system');
  await claude('Implement payment processing');
  return 'feature-complete';
}, {
  base: 'main',      // Create from main branch
  cleanup: false     // Keep worktree after execution
});

// Worktree utilities for advanced management
import { worktreeUtils } from 'channelcoder';

// List all worktrees
const worktrees = await worktreeUtils.list();

// Create/remove worktrees manually
await worktreeUtils.create('experiment/new-arch', { base: 'develop' });
await worktreeUtils.remove('feature/old');

// Check worktree existence
if (await worktreeUtils.exists('feature/auth')) {
  console.log('Auth worktree already exists');
}

Why Use Worktrees?

Parallel Development: Work on multiple features without stashing/switching
Clean Experiments: Test risky changes in isolated environments
Context Preservation: Each worktree maintains its own file state
Session Enhancement: Combine with sessions for branch-specific conversations

Worktree Options

interface WorktreeOptions {
  // Branch name (required for creation)
  branch?: string;
  
  // Base branch for new worktree
  base?: string;
  
  // Custom path (auto-generated if not provided)
  path?: string;
  
  // Remove worktree after execution (default: true for temporary)
  cleanup?: boolean;
  
  // Force creation vs. error if exists (default: false - upsert)
  create?: boolean;
}

Composing Features

Worktrees work seamlessly with other ChannelCoder features:

// Worktree + Session
const s = session();
await s.claude('Start OAuth feature', { worktree: 'feature/oauth' });
await s.claude('Add tests'); // Continues in same worktree

// Worktree + Docker
await claude('Test in total isolation', {
  worktree: 'experiment/risky',
  docker: true
});

// Worktree + Streaming
await worktree('feature/docs', async () => {
  for await (const chunk of stream('Generate documentation')) {
    process.stdout.write(chunk.content);
  }
});

🐳 Docker Mode

Run Claude in an isolated Docker container for enhanced security with dangerous permissions:

// Simple Docker mode - auto-detect Dockerfile
await claude('Risky operation', { docker: true });

// Specify Docker image
await claude('Analyze system', { 
  docker: { image: 'my-claude:latest' } 
});

// With custom mounts and environment
await claude('Process data', {
  docker: {
    image: 'claude-sandbox',
    mounts: ['./data:/data:ro'],
    env: { NODE_ENV: 'production' }
  }
});

Setting Up Docker Mode

Create a Dockerfile with Claude CLI installed:

FROM node:20-slim
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace

Build your image:

docker build -t my-claude .

Use with channelcoder:

await claude('Task', { docker: { image: 'my-claude' } });

Auto-Detection

When using docker: true, channelcoder will:

Look for a Dockerfile in your project
Build an image automatically (with caching)
Mount your working directory as /workspace

Docker Options

interface DockerOptions {
  // Auto-detect Dockerfile (default: true)
  auto?: boolean;
  
  // Docker image to use
  image?: string;
  
  // Path to Dockerfile (default: ./Dockerfile)
  dockerfile?: string;
  
  // Additional volume mounts
  mounts?: string[];  // Docker format: "host:container:mode"
  
  // Environment variables
  env?: Record<string, string>;
}

CLI Reference

channelcoder <command> [options]

Commands:
  run          Execute prompt and exit (print mode) - non-interactive
  interactive  Interactive mode with Claude (default)
  stream       Stream responses in real-time
  session      Manage conversation sessions
  worktree     Manage git worktrees

Global Options:
  -h, --help     Show help
  -v, --version  Show version

Run 'channelcoder <command> --help' for command-specific options

Command Details

`channelcoder run [prompt-file] [options]`

Execute a prompt and print the result without interaction.

Options:
  -p, --prompt <text>      Inline prompt instead of file
  -d, --data <key=value>   Data for interpolation (repeatable)
  -s, --system <prompt>    System prompt (text or .md file)
  -t, --tools <tools>      Allowed tools (e.g., "Read Write")
  --disallowed-tools       Disallowed tools (comma-separated)
  --append-system <text>   Append to system prompt
  --mcp-config <file>      Load MCP servers from JSON file
  --permission-tool <tool> MCP tool for permission prompts
  -r, --resume <id>        Resume conversation by session ID
  -c, --continue           Continue most recent conversation
  --max-turns <n>          Limit agentic turns
  --json                   Output JSON format
  -v, --verbose            Verbose output

`channelcoder interactive [prompt-file] [options]`

Launch Claude in interactive mode (default command).

Options: Same as 'run' command

`channelcoder stream [prompt-file] [options]`

Stream responses in real-time.

Options: Same as 'run' command

`channelcoder session <subcommand>`

Manage conversation sessions.

Subcommands:
  list       List all saved sessions
  load       Load and continue a session
  remove     Remove a saved session

`channelcoder worktree <subcommand>`

Manage git worktrees for isolated development.

Subcommands:
  list       List all worktrees
  create     Create a new worktree
  remove     Remove a worktree
  cleanup    Clean up orphaned worktrees

Advanced Features Documentation

For detailed guides on advanced features, see the /documentation folder:

Docker Mode Guide - Run Claude in isolated containers with enhanced security
Git Worktree Mode Guide - Parallel development in isolated git worktrees
Session Management Guide - Multi-turn conversations with context preservation
Stream Parser SDK Guide - Parse and monitor Claude's streaming output

Frontmatter Syntax

File-based prompts support YAML frontmatter for configuration. Here are the actually supported options:

---
# System prompt - Sets the Claude system/assistant prompt
# Can be inline text or a path to a .md/.txt file
systemPrompt: "You are a helpful coding assistant"
# or
systemPrompt: "./system-prompts/analyst.md"

# Append to system prompt
appendSystemPrompt: "Always explain your reasoning"

# Allowed tools - Restrict which tools Claude can use
# These are passed to Claude CLI's --allowedTools flag
allowedTools:
  - "Read"                    # Read files
  - "Write"                   # Write files
  - "Edit"                    # Edit files
  - "Bash"                    # Run any bash command
  - "Bash(git:*)"            # Pattern: only git commands
  - "Bash(npm:test)"         # Specific: only npm test
  - "Grep"                   # Search file contents
  - "WebSearch"              # Search the web

# Disallowed tools - Prevent specific tools
disallowedTools:
  - "Bash(rm:*)"             # No rm commands
  - "Bash(git:push)"         # No git push

# MCP (Model Context Protocol) configuration
mcpConfig: "./mcp-servers.json"
permissionPromptTool: "mcp__auth__prompt"

# Input schema - Validates variables before interpolation
input:
  name: string               # Required string
  age?: number              # Optional number
  tags: string[]            # Array of strings
  config:                   # Nested object
    port: number
    host?: string

# Output schema - Validates Claude's response (SDK only)
output:
  success: boolean
  result:
    type: string
    enum: [feature, bug, chore]  # Enum constraint
  items: 
    - name: string
      done: boolean
---
Your prompt content here...

Note: The following options are passed via CLI or SDK, not frontmatter:

outputFormat - Use --json flag or claude(prompt, { outputFormat: 'json' })
stream - Use --stream flag or stream() function
verbose - Use --verbose flag or claude(prompt, { verbose: true })
timeout - SDK only: claude(prompt, { timeout: 30000 })

Frontmatter Validation

The frontmatter is validated using a Zod schema. Invalid keys will cause an error:

import { FrontmatterSchema, type Frontmatter } from 'channelcoder';

// Validate frontmatter programmatically
const result = FrontmatterSchema.safeParse({
  systemPrompt: "Valid",
  temperature: 0.7  // Error: unknown key
});

// TypeScript type for frontmatter
const config: Frontmatter = {
  systemPrompt: "Assistant prompt",
  appendSystemPrompt: "Be concise",
  allowedTools: ["Read", "Write"],
  disallowedTools: ["Bash(rm:*)"],
  mcpConfig: "./mcp-servers.json",
  permissionPromptTool: "mcp__auth__prompt",
  input: { name: "string" },
  output: { success: "boolean" }
};

Schema Definition Format

Schemas are defined using YAML notation that's automatically converted to Zod schemas:

---
input:
  name: string              # Basic types: string, number, boolean
  age?: number             # Optional with ?
  tags: string[]           # Arrays with []
  metadata:                # Nested objects
    created: string
    updated?: string
---

Supported types:

string - Text values
number - Numeric values
boolean or bool - True/false values
array or type[] - Arrays
object - Nested objects
any - Any value

Note: For programmatic SDK usage, you can also use Zod schemas directly in the validation utilities.

Examples

File-based Prompts

Create a prompt file analyze.md:

---
input:
  task: string
  details?: boolean
systemPrompt: "You are a helpful analyst"
allowedTools:
  - Read
  - Grep
---
# Analysis for {task}

{details ? "Provide detailed breakdown." : "Summary only."}

Run it:

channelcoder analyze.md -d task="Review PR" -d details=true

Inline Prompts

# Simple
channelcoder -p "Explain {concept}" -d concept="quantum computing"

# With tools
channelcoder -p "Find files containing {pattern}" \
   -d pattern="TODO" \
   -t "Read Grep"

# Streaming
channelcoder -p "Write a haiku about {topic}" \
   -d topic="coding" \
   --stream

# Resume conversation
channelcoder --resume abc123 -p "Continue with the implementation"

# Continue last conversation
channelcoder --continue -p "What about error handling?"

# Limit agentic turns
channelcoder analyze.md --max-turns 3

# MCP configuration
channelcoder query.md --mcp-config ./servers.json

# Disallow dangerous tools
channelcoder cleanup.md --disallowed-tools "Bash(rm:*),Bash(git:push)"

Complex Data

# Arrays and objects via JSON
channelcoder -p "Process items: {items}" \
   -d 'items=["apple","banana","orange"]'

# Complex nested data
channelcoder -p "Config: {config}" \
   -d 'config={"port":3000,"host":"localhost"}'

SDK Reference

Basic Usage

import { claude } from 'channelcoder';

// Simple prompts
const result = await claude('Explain TypeScript');

// Template literals
const topic = 'async/await';
const result = await claude`Explain ${topic} with examples`;

// File-based prompts
const result = await claude('prompts/analyze.md', {
  data: { taskId: 'FEAT-123' }
});

Options

// All available options
const result = await claude('Your prompt', {
  // Data interpolation
  data: { key: 'value' },
  
  // System configuration
  system: 'You are a helpful assistant',
  appendSystem: 'Be concise',
  
  // Tool configuration
  tools: ['Read', 'Write', 'Bash(git:*)'],
  disallowedTools: ['Bash(rm:*)'],
  mcpConfig: './mcp-servers.json',
  permissionTool: 'mcp__auth__prompt',
  
  // Session management
  resume: 'session-id-here',
  continue: true,
  
  // Execution control
  maxTurns: 10,
  mode: 'run', // 'run' | 'stream' | 'interactive'
  includeEvents: true,
  
  // Background execution
  detached: true,        // Run in background
  logFile: 'output.log', // Log file for detached mode
  stream: true,          // Enable real-time streaming in detached mode
  
  // Other
  verbose: true,
  outputFormat: 'json',
  timeout: 60000
});

Streaming

import { stream } from 'channelcoder';

// Stream responses
for await (const chunk of stream('Generate a story')) {
  if (chunk.type === 'content') {
    process.stdout.write(chunk.content);
  }
}

Error Handling

const result = await claude('prompt.md', { data });

if (!result.success) {
  console.error('Error:', result.error);
  if (result.warnings) {
    console.warn('Warnings:', result.warnings);
  }
}

// Type-safe error handling
if (result.warnings?.includes('max turns reached')) {
  console.log('Hit maximum turn limit');
}

Interactive Mode

import { interactive } from 'channelcoder';

// Launch Claude interactively (replaces current process)
await interactive('Help me debug this issue');

// Code below this line will NEVER execute!
// The process is replaced by Claude using shell exec

Important: Interactive mode completely replaces your Node.js process with Claude:

No Node.js parent process remains in memory
Claude gets direct terminal control
Exit codes go directly to the shell
Perfect for long Claude sessions without memory overhead

Background Execution & Real-time Monitoring

ChannelCoder supports background execution with real-time monitoring capabilities:

import { detached, session } from 'channelcoder';

// Basic background execution
const result = await detached('Analyze large codebase', {
  logFile: 'analysis.log'
});
console.log('Background process started with PID:', result.data?.pid);

// Real-time streaming to log file
const result2 = await detached('Generate comprehensive report', {
  logFile: 'report.log',
  stream: true  // Enables real-time JSON streaming
});

// Monitor in real-time with Unix tools
// tail -f report.log | jq -r '.content'          # See content
// tail -f report.log | jq -r '.type'             # See chunk types
// watch -n 1 "wc -l report.log"                  # Monitor progress

Session Background Execution:

// Session with real-time file updates
const s = session({ 
  autoSave: true  // Session file updates in real-time
});

// Background execution with session context
await s.detached('Long-running analysis', {
  logFile: 'session-output.log',
  stream: true
});

// Monitor both Claude output AND session state
// tail -f session-output.log | jq -r '.content'   # Claude output
// watch -n 1 cat ~/.channelcoder/sessions/my-session.json  # Session state

Stream Parser SDK

ChannelCoder includes a powerful Stream Parser SDK for parsing Claude's stream-json output from detached sessions and log files:

import { parseLogFile, monitorLog, streamParser } from 'channelcoder';

// Parse a complete log file
const parsed = await parseLogFile('session.log');
console.log(parsed.content);        // All assistant messages
console.log(parsed.totalCost);      // Total cost
console.log(parsed.events.length);  // Number of events

// Monitor a log file in real-time
const cleanup = monitorLog('active.log', (event) => {
  if (streamParser.isAssistantEvent(event)) {
    console.log('Claude:', streamParser.extractAssistantText(event));
  } else if (streamParser.isToolUseEvent(event)) {
    console.log('Tool used:', event.tool);
  } else if (streamParser.isResultEvent(event)) {
    console.log('Completed! Cost:', event.cost_usd);
  }
});

// Clean up when done
cleanup();

// Low-level parsing
import { parseStreamEvent, eventToChunk } from 'channelcoder/streamParser';

const line = '{"type":"assistant","message":{...}}';
const event = parseStreamEvent(line);
const chunk = eventToChunk(event);

Type Guards for Event Handling:

import { 
  isSystemEvent, 
  isAssistantEvent, 
  isResultEvent,
  isToolUseEvent,
  isErrorEvent 
} from 'channelcoder';

// Type-safe event processing
function processEvent(event: ClaudeEvent) {
  if (isAssistantEvent(event)) {
    const text = streamParser.extractAssistantText(event);
    console.log('Assistant:', text);
  } else if (isToolUseEvent(event)) {
    console.log('Tool:', event.tool, event.input);
  } else if (isResultEvent(event)) {
    if (event.subtype === 'error') {
      console.error('Failed:', event.error);
    } else {
      console.log('Success! Cost: $', event.cost_usd);
    }
  }
}

See examples/task-monitor-tui.ts for a complete real-time monitoring TUI built with the Stream Parser SDK.

Session Management

ChannelCoder provides built-in session management for maintaining conversation context:

import { session } from 'channelcoder';

// Create a new session with auto-save
const s = session({ autoSave: true });

// Use like normal, but with automatic context tracking
await s.claude('What is TypeScript?');
await s.claude('Show me an example'); // Automatically continues conversation

// Save session for later
await s.save('learning-typescript');

// Load and continue a saved session
const saved = await session.load('learning-typescript');
await saved.claude('What about generics?');

// List all saved sessions
const sessions = await session.list();
// [{ name: 'learning-typescript', messageCount: 3, lastActive: Date, ... }]

// Access session data
console.log(s.id());         // Current session ID
console.log(s.messages());   // Conversation history

CLI Session Support:

# Start a new session
channelcoder prompts/debug.md --session my-debug

# Continue a session
channelcoder prompts/continue.md --load-session my-debug

# List all sessions
channelcoder --list-sessions

Session-Required Prompts:

---
session:
  required: true
systemPrompt: "You are debugging an ongoing issue"
---
Continue investigating the error we discussed.

Manual Session Management (without session wrapper):

// Resume a specific session by ID
await claude('Continue our discussion', {
  resume: 'session-id-here'
});

// Continue most recent session
await claude('Continue where we left off', {
  continue: true
});

Prompt File Format

ChannelCoder uses Markdown files with YAML frontmatter:

---
# Input validation (optional)
input:
  name: string
  age?: number
  tags: string[]

# Output schema (optional)
output:
  success: boolean
  message: string

# Claude options
systemPrompt: "path/to/system.md"  # or inline text
allowedTools:
  - Read
  - Write
  - "Bash(git:*)"  # With patterns
---

# Your prompt with {name} interpolation

Age: {age ? age : "not specified"}

Tags: {tags}

Requirements

Claude Code CLI installed and configured
Node.js 18+ or Bun runtime

Tips & Tricks

1. Tool Patterns

Allow specific command patterns:

channelcoder prompt.md -t "Bash(git:*) Read Write"

2. Conditional Content

Use JavaScript expressions in templates:

const isDev = true;
const items = ['a', 'b', 'c'];

await claude`
  ${isDev ? "Include debug info" : ""}
  Process ${items.length} items
`;

3. System Prompts

Can be inline or file paths:

# Inline
channelcoder -p "..." -s "Be concise"

# From file
channelcoder -p "..." -s "prompts/systems/expert.md"

4. Background Monitoring

Perfect for long-running tasks:

# Start background streaming process
channelcoder analysis.md --detached --stream --log analysis.log

# Monitor real-time progress (Unix composable)
tail -f analysis.log | jq -r '.content'           # Content only
tail -f analysis.log | jq -r 'select(.type=="tool_use").tool'  # Tool usage
watch -n 1 "grep -c content analysis.log"         # Progress counter

5. JSON Output

Perfect for automation:

result=$(cc prompt.md --json)
success=$(echo $result | jq -r '.success')

Examples

Check out the /examples directory for:

basic-usage.ts - Simple examples to get started
file-based-usage.ts - Using file-based prompts
launch-modes.ts - Different execution modes
detached-streaming.ts - Background execution with real-time monitoring
task-monitor-tui.ts - NEW Real-time TUI using Stream Parser SDK
demo-features.ts - Feature showcase (no execution)
release.ts - Real-world release automation

Run examples:

bun run example:quick     # Run basic examples
bun run examples/basic-usage.ts
bun run examples/launch-modes.ts run
bun run examples/release.ts

License

MIT

Contributing

Issues and PRs welcome at github.com/davidpp/channelcoder

Named after Claude Shannon, the father of information theory, ChannelCoder channels your prompts to Claude with maximum signal and minimum noise.

Name		Name	Last commit message	Last commit date
Latest commit History 107 Commits
.idea-explorer		.idea-explorer
.serena		.serena
.tasks		.tasks
docker		docker
docs		docs
documentation		documentation
examples		examples
prompts		prompts
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
llms.txt		llms.txt
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

davidpp/channelcoder

Folders and files

Latest commit

History

Repository files navigation

ChannelCoder

Installation

Quick Start

SDK Usage

CLI Usage

Features

🎯 Simple Function API

🔄 Variable Interpolation

🌊 Execution Modes

🌿 Git Worktree Mode

Why Use Worktrees?

Worktree Options

Composing Features

🐳 Docker Mode

Setting Up Docker Mode

Auto-Detection

Docker Options

CLI Reference

Command Details

channelcoder run [prompt-file] [options]

channelcoder interactive [prompt-file] [options]

channelcoder stream [prompt-file] [options]

channelcoder session <subcommand>

channelcoder worktree <subcommand>

Advanced Features Documentation

Frontmatter Syntax

Frontmatter Validation

Schema Definition Format

Examples

File-based Prompts

Inline Prompts

Complex Data

SDK Reference

Basic Usage

Options

Streaming

Error Handling

Interactive Mode

Background Execution & Real-time Monitoring

Stream Parser SDK

Session Management

Prompt File Format

Requirements

Tips & Tricks

1. Tool Patterns

2. Conditional Content

3. System Prompts

4. Background Monitoring

5. JSON Output

Examples

License

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 24

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

`channelcoder run [prompt-file] [options]`

`channelcoder interactive [prompt-file] [options]`

`channelcoder stream [prompt-file] [options]`

`channelcoder session <subcommand>`

`channelcoder worktree <subcommand>`

Packages