### Running Multiple Channelcoder Examples - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Provides quick start commands to run multiple Channelcoder examples simultaneously. This includes a shortcut for basic examples and a command to run all non-interactive examples using the launch modes script.

```Bash
bun run example:quick
```

```Bash
bun run examples/launch-modes.ts all
```

--------------------------------

### Running Channelcoder Release Automation Example - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `release.ts` example, demonstrating a real-world application of Channelcoder for release automation, requiring a version argument.

```Bash
bun run examples/release.ts [version]
```

--------------------------------

### Running Basic Channelcoder Usage Example - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `basic-usage.ts` example, demonstrating fundamental Channelcoder features. This snippet shows how to run simple core functionality examples using Bun.

```Bash
bun run examples/basic-usage.ts
```

--------------------------------

### Running ChannelCoder Examples (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Provides commands to execute various example scripts included with ChannelCoder. These commands demonstrate how to run basic, file-based, and launch mode examples using 'bun run', showcasing different ways to interact with the library.

```bash
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
```

--------------------------------

### Installing ChannelCoder via npm and Bun

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This snippet provides commands for installing the ChannelCoder library locally using npm or Bun, and globally for CLI access. Local installation adds the package to your project's dependencies, while global installation makes the `channelcoder` command available system-wide.

```bash
# Using npm
npm install channelcoder

# Using bun
bun add channelcoder

# Global CLI installation
npm install -g channelcoder
```

--------------------------------

### Running File-Based Channelcoder Usage Example - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `file-based-usage.ts` example, which illustrates how to use file-based prompts, including frontmatter and validation capabilities within Channelcoder.

```Bash
bun run examples/file-based-usage.ts
```

--------------------------------

### Running Channelcoder Feature Showcase - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `demo-features.ts` example, which serves as a showcase of various Channelcoder features without performing any actual command execution.

```Bash
bun run examples/demo-features.ts
```

--------------------------------

### Example JSON Output for Version Analysis - JSON

Source: https://github.com/davidpp/channelcoder/blob/main/examples/release-analysis.md

This JSON snippet provides an example of the required output format for the version analysis. It demonstrates the structure and expected data types for fields like `success`, `recommendedVersion`, `changeType`, `confidence`, `reasoning`, `breakingChanges`, and `highlights`, guiding the AI's response generation.

```JSON
{
  "success": true,
  "recommendedVersion": "X.Y.Z",
  "changeType": "major|minor|patch|none",
  "confidence": "high|medium|low",
  "reasoning": "Brief explanation of the recommendation",
  "breakingChanges": true|false,
  "highlights": [
    "Key change or feature 1",
    "Key change or feature 2"
  ]
}
```

--------------------------------

### Running Release Analysis with ChannelCoder (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This snippet demonstrates how to execute the release analysis example using `bun run`. It shows commands for general analysis and for validating a specific target version, assuming the user is within a Git repository.

```bash
# Make sure you're in a git repository
cd your-project

# Run the analysis
bun run examples/release.ts

# Or validate a specific target version
bun run examples/release.ts v2.0.0
```

--------------------------------

### Running Interactive Channelcoder Demo - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `interactive-demo.ts` example, showcasing Channelcoder's process replacement behavior. It can be run with or without an additional context string.

```Bash
bun run examples/interactive-demo.ts
```

```Bash
bun run examples/interactive-demo.ts "debugging TypeScript"
```

--------------------------------

### Running Channelcoder with Different Launch Modes - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `launch-modes.ts` example, allowing specification of various Channelcoder execution modes such as `run`, `stream`, `interactive`, `template`, `file`, or `all`.

```Bash
bun run examples/launch-modes.ts [mode]
```

--------------------------------

### Running Channelcoder Dry Run Demo - Bash

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

Executes the `dry-run-demo.ts` example, which demonstrates how Channelcoder can generate CLI commands for review without actually executing them, useful for planning and debugging.

```Bash
bun run examples/dry-run-demo.ts
```

--------------------------------

### Defining a ChannelCoder Prompt File (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This YAML frontmatter example shows how to define a ChannelCoder prompt file. It specifies input parameters with types (param1: string, param2?: boolean), an output schema (result: string), a system prompt, and allowed tools (Read, Write), providing a structured way to configure prompt behavior.

```yaml
---
input:
  param1: string
  param2?: boolean
output:
  result: string
systemPrompt: "You are a helpful assistant"
allowedTools: [Read, Write]
---
Process {param1}...
```

--------------------------------

### Running Root Cause Analysis with ChannelCoder (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This snippet provides commands to run the root cause analysis example. It includes options for running demo scenarios, analyzing a custom error with specific patterns, and performing a quick pattern search using the `bun run` command.

```bash
# Run demo scenarios
bun run examples/root-cause-analysis.ts

# Analyze a custom error
bun run examples/root-cause-analysis.ts --custom "TypeError: x is not a function" "function.*x"

# Quick pattern search
bun run examples/root-cause-analysis.ts --search "TODO|FIXME"
```

--------------------------------

### Defining AI Assistant System Prompt and Tools (Configuration)

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/system.md

This configuration block sets the system prompt, which guides the AI assistant's persona and initial instructions, and specifies the tools it is allowed to use, such as 'Read' and 'Write'.

```Configuration
systemPrompt: You are a helpful assistant
allowedTools: [Read, Write]
```

--------------------------------

### Example File-Based Prompt Definition (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This YAML snippet defines a file-based prompt (`analyze.md`) with input variables (`task`, `details`), a `systemPrompt`, and `allowedTools`. It demonstrates how to structure a prompt file for ChannelCoder.

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

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

--------------------------------

### Using Inline Prompts with ChannelCoder CLI (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This section provides various examples of using the `channelcoder` CLI for inline prompts. It covers simple prompts, integrating tools, streaming responses, resuming and continuing conversations, limiting agentic turns, and configuring MCP.

```bash
# 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)"
```

--------------------------------

### Quick Start: ChannelCoder CLI Basic Usage

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This Bash snippet illustrates common command-line operations with the ChannelCoder CLI. It shows how to execute file-based prompts with data interpolation, use inline prompts with variables, specify tools and system prompts, and resume previous conversation sessions using a session ID.

```bash
# Run a prompt file with data
channelcoder prompts/analyze.md -d taskId=FEAT-123

# Inline prompt with variables
channelcoder -p "Summarize: {text}" -d text="Hello world"

# With tools and system prompt
channelcoder prompt.md -t "Read Write" -s "Be concise"

# Resume session
channelcoder -r session-id
```

--------------------------------

### Configuring ChannelCoder SDK Options (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript example showcases the full range of options available when calling the `claude` function in the ChannelCoder SDK. It covers data interpolation, system and tool configurations, session management, execution control, and output formatting.

```typescript
// 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,
  
  // Other
  verbose: true,
  outputFormat: 'json',
  timeout: 60000
});
```

--------------------------------

### Example Task Analysis Output JSON

Source: https://github.com/davidpp/channelcoder/blob/main/examples/analyze-task.md

This JSON snippet illustrates the expected output format for the task analysis. It includes a success flag, the type of analysis (feature, bugfix, chore, or documentation), a brief summary, and an array of implementation steps.

```json
{
  "success": true,
  "analysis": {
    "type": "feature|bugfix|chore|documentation"
  },
  "summary": "Brief summary of the task",
  "steps": ["step1", "step2", "..."]
}
```

--------------------------------

### Multi-variable Interpolation in ChannelCoder Prompts (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This YAML snippet illustrates how multiple variables can be defined and passed to a ChannelCoder prompt. It shows common Git-related data points like current version, last tag, commits, and file changes, which are then interpolated into the prompt template.

```yaml
currentVersion: "1.2.3"
lastTag: "v1.2.0"
commits: "git log output..."
fileChanges: "git diff stats..."
```

--------------------------------

### Specifying Tool Patterns via CLI (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Demonstrates how to allow specific tool command patterns using the 'channelcoder' CLI. This example shows how to enable 'Bash' commands with 'git:*' patterns, along with 'Read' and 'Write' tools, providing fine-grained control over Claude's capabilities.

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

--------------------------------

### ChannelCoder Streaming and Interactive Modes (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This TypeScript snippet illustrates different execution modes for ChannelCoder prompts: streaming and interactive. The streaming example iterates over chunks for real-time responses, while the interactive mode replaces the current process, noting that code after it will not execute.

```typescript
// Streaming
for await (const chunk of stream('your-prompt.md', { data })) {
  console.log(chunk.content);
}

// Interactive (replaces current process!)
await interactive('your-prompt.md', { data });
// ⚠️ Code after interactive() never executes!
```

--------------------------------

### Using ChannelCoder Prompt in TypeScript Script

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This TypeScript snippet demonstrates how to import and use the `claude` function from `channelcoder` to execute a prompt file. It shows how to pass data to the prompt and how to handle the typed result, with automatic input validation based on the prompt's frontmatter schema.

```typescript
import { claude } from 'channelcoder';

const result = await claude('your-prompt.md', {
  data: {
    param1: 'value',
    param2: true
  }
});

// Input validation happens automatically if schema in frontmatter
if (result.success) {
  console.log(result.data); // Typed based on output schema
}
```

--------------------------------

### Defining Allowed Tools in ChannelCoder Prompts (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This YAML snippet demonstrates how to restrict tool usage within a ChannelCoder prompt for safety. It specifies `Bash(rg:*)` for ripgrep, `Bash(git log:*)` for git history, and `Read` for file reading, explicitly noting the absence of `Write` or `Edit` tools.

```yaml
allowedTools:
  - "Bash(rg:*)"      # ripgrep for searching
  - "Bash(git log:*)" # git history
  - Read              # file reading
  # Note: No Write or Edit tools
```

--------------------------------

### Quick Start: ChannelCoder SDK Basic Usage

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet demonstrates fundamental ways to use the ChannelCoder SDK's `claude` function. It covers sending simple inline prompts, using template literals for variable injection, loading prompts from files with associated data, and configuring Claude with specific tools and system prompts for tailored AI interactions.

```typescript
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'
});
```

--------------------------------

### Conditional Content in ChannelCoder Prompts (Markdown)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This Markdown snippet demonstrates how to implement conditional content within a ChannelCoder prompt using a ternary operator. It shows how to include text only if a `targetVersion` variable is present, allowing for dynamic prompt generation based on input.

```markdown
${targetVersion ? "Validate target: ${targetVersion}" : ""}
```

--------------------------------

### Structured Debugging Output from ChannelCoder (JSON)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/README.md

This JSON snippet illustrates the structured output format for debugging information generated by ChannelCoder. It includes fields for the root cause (file, line, description), a call trace, a hypothesis, and a suggested fix, providing a standardized format for analysis results.

```json
{
  "rootCause": {
    "file": "src/service.ts",
    "line": 42,
    "description": "Null check missing"
  },
  "callTrace": [...],
  "hypothesis": "...",
  "suggestedFix": "..."
}
```

--------------------------------

### Processing JSON Output from ChannelCoder (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Shows how to capture and parse JSON output from the 'channelcoder' CLI for automation purposes. The example uses 'jq' to extract specific fields like 'success' from the JSON result, facilitating programmatic interaction with Claude's responses.

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

--------------------------------

### Validating Frontmatter Programmatically (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript example shows how to programmatically validate frontmatter configurations using ChannelCoder's `FrontmatterSchema` (a Zod schema) and define types with `Frontmatter`. It highlights how invalid keys will cause an error during validation.

```typescript
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" }
};
```

--------------------------------

### Configuring Allowed Tools for ChannelCoder Task Implementation (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/prompts/implement.md

This YAML snippet defines the set of tools permitted for use during the implementation of a ChannelCoder SDK task. It includes standard development tools like Read, Write, Edit, and Bash, as well as specific Scopecraft MCP tools for task management, such as listing, getting, updating, and moving tasks, and managing workflows, phases, and features.

```YAML
allowedTools:
  - Read
  - Write
  - Edit
  - MultiEdit
  - Bash
  - Grep
  - Glob
  - TodoWrite
  - TodoRead
  # Scopecraft MCP tools for task management
  - mcp__scopecraft-cmd__task_list
  - mcp__scopecraft-cmd__task_get
  - mcp__scopecraft-cmd__task_update
  - mcp__scopecraft-cmd__task_move
  - mcp__scopecraft-cmd__task_next
  - mcp__scopecraft-cmd__workflow_current
  - mcp__scopecraft-cmd__phase_list
  - mcp__scopecraft-cmd__feature_list
```

--------------------------------

### Tracking API Costs in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This example demonstrates how to track cumulative API costs using the `metadata.cost` property from the `claude` function's result. A wrapper function, `trackCosts`, is used to increment a `totalSpent` variable and log per-turn and cumulative costs, providing insights into API usage.

```typescript
let totalSpent = 0;

async function trackCosts(prompt: string, options = {}) {
  const result = await claude(prompt, options);
  
  if (result.metadata?.cost) {
    totalSpent += result.metadata.cost;
    console.log(`Turn cost: $${result.metadata.cost}`);
    console.log(`Total spent: $${totalSpent}`);
  }
  
  return result;
}
```

--------------------------------

### Managing Sessions for Conversational Continuity in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This example demonstrates two approaches to session management: simple continuation using `sessionId` from a previous result, and a more robust `ClaudeSession` class. The class maintains the session ID internally, allowing for stateful, multi-turn conversations without manually passing the ID for each prompt.

```typescript
// Simple session continuation
const first = await claude('Start analysis', options);
const second = await claude('Continue', {
  resume: first.metadata?.sessionId
});

// Stateful wrapper
class ClaudeSession {
  private sessionId?: string;
  
  async send(prompt: string, options = {}) {
    const result = await claude(prompt, {
      resume: this.sessionId,
      ...options
    });
    
    this.sessionId = result.metadata?.sessionId;
    return result;
  }
}
```

--------------------------------

### Interpolating Variables in Inline Prompts in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This TypeScript example demonstrates two methods for variable interpolation in inline prompts: using the `data` option to pass an object with key-value pairs, and using standard JavaScript template literals. Both approaches enable dynamic insertion of values into prompts before sending them to Claude.

```typescript
// Using data option
await claude('Analyze {taskId}', {
  data: { taskId: 'FEAT-123' }
});

// Using template literals
const taskId = 'FEAT-123';
await claude`Analyze ${taskId}`;
```

--------------------------------

### Defining Input, System Prompt, and Tools (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/simple-greeting.md

This YAML configuration block defines the expected input parameters (`name`, optional `greeting`), sets a system-wide prompt for an AI assistant, and specifies a list of allowed tools (`Read`). It establishes the foundational context and capabilities for a conversational agent.

```YAML
input:
  name: string
  greeting?: string

systemPrompt: "You are a friendly assistant. Respond concisely."

allowedTools:
  - Read
```

--------------------------------

### Defining Channelcoder Input Schema and System Prompt (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/simple-test.md

This YAML snippet defines the input parameters for a channelcoder project, including a required 'name' (string) and an optional 'greeting' (string). It also sets a 'systemPrompt' for the AI assistant, instructing it to be friendly and concise, and specifies 'allowedTools' like 'Read' for the assistant's capabilities.

```YAML
input:
  name: string
  greeting?: string

systemPrompt: "You are a friendly assistant. Respond concisely."

allowedTools:
  - Read
```

--------------------------------

### ChannelCoder Development and Release Commands (Bun)

Source: https://github.com/davidpp/channelcoder/blob/main/CLAUDE.md

This snippet lists essential `bun` commands for building, testing, code quality, development, and release management of the ChannelCoder project. It covers compilation, various test modes, linting, formatting, and the multi-step release workflow.

```bash
# Build and Test
bun run build          # Compile TypeScript
bun run test           # Run all tests with Bun's built-in test runner
bun run test:watch     # Watch mode for TDD
bun run test:compat    # Run Node.js compatibility tests
bun run typecheck      # Type checking only

# Code Quality (ALWAYS run before committing)
bun run check          # Smart check - only changed files
bun run check:full     # Full project check
bun run lint:fix       # Auto-fix linting issues
bun run format         # Format code with Biome

# Development
bun run dev            # Watch mode for development
bun run example:quick  # Test SDK examples
bun run cli:help       # Test CLI functionality

# Release Management
bun run release:precheck   # Verify release readiness
bun run release:analyze    # Analyze changes for release
bun run release:execute    # Execute release process
bun run release:publish    # Publish to npm

# Run specific test file
bun test path/to/test.ts
```

--------------------------------

### Configuring System Prompts via CLI (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Explains how to provide system prompts to Claude using the 'channelcoder' CLI. System prompts can be supplied inline as a string or referenced from a file path, allowing for flexible configuration of Claude's initial behavior or persona.

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

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

--------------------------------

### ChannelCoder CLI: Command Line Options Reference

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This Bash snippet provides a comprehensive reference for the ChannelCoder CLI's command-line options. It details various flags for specifying inline prompts, passing data, setting system prompts, managing allowed/disallowed tools, configuring MCP, resuming conversations, limiting turns, and controlling verbosity.

```bash
channelcoder [prompt-file] [options]
# or
channelcoder [prompt-file] [options]

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
  -v, --verbose            Verbose output
  -h, --help               Show help
```

--------------------------------

### ChannelCoder File-Based Prompts: Frontmatter Configuration

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This YAML snippet illustrates the frontmatter syntax used in ChannelCoder for configuring file-based prompts. It shows how to define system prompts (inline or file-based), append to system prompts, specify allowed and disallowed tools with granular control, and configure Model Context Protocol (MCP) settings directly within the prompt file.

```yaml
---
# 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"
```

--------------------------------

### Generating a Personalized Greeting (Templating)

Source: https://github.com/davidpp/channelcoder/blob/main/examples/simple-greeting.md

This template snippet constructs a personalized greeting using the provided `greeting` and `name` input variables. It defaults to 'Hello' if `greeting` is not supplied and then prompts for a simple greeting response, demonstrating dynamic content generation.

```Templating
${greeting || "Hello"}, ${name}!

Please respond with a simple greeting back.
```

--------------------------------

### Setting System Prompt for Semantic Versioning Expert - YAML

Source: https://github.com/davidpp/channelcoder/blob/main/examples/release-analysis.md

This YAML snippet defines the system prompt for the AI, instructing it to act as a semantic versioning expert. It provides clear rules for recommending major, minor, or patch version bumps based on breaking changes, new features, or bug fixes, respectively, ensuring consistent analysis.

```YAML
You are a semantic versioning expert. Analyze code changes and recommend
appropriate version bumps following these rules:
- Breaking changes → MAJOR (1.0.0 → 2.0.0)
- New features → MINOR (1.0.0 → 1.1.0)
- Bug fixes → PATCH (1.0.0 → 1.0.1)
- No changes → NONE (keep current version)
```

--------------------------------

### Defining Input Schema for Version Analysis - YAML

Source: https://github.com/davidpp/channelcoder/blob/main/examples/release-analysis.md

This YAML snippet defines the input schema required for the version analysis process. It specifies parameters like `currentVersion`, `lastTag`, `commits`, `fileChanges`, and an optional `targetVersion`, all as strings, to provide context for the AI agent's analysis.

```YAML
currentVersion: string
lastTag: string
commits: string
fileChanges: string
targetVersion?: string
```

--------------------------------

### Defining Prompt Files with YAML Frontmatter (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Outlines the structure of ChannelCoder prompt files, which use Markdown with YAML frontmatter. The frontmatter allows defining optional input validation schemas, output schemas, and Claude-specific options like 'systemPrompt' and 'allowedTools' with pattern matching. The main prompt content supports interpolation.

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

# Output schema (optional)
out: 
  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}
```

--------------------------------

### Defining Output Schema for Version Recommendation - YAML

Source: https://github.com/davidpp/channelcoder/blob/main/examples/release-analysis.md

This YAML snippet outlines the expected JSON output structure from the version analysis. It includes fields such as `success`, `recommendedVersion`, `changeType`, `confidence`, `reasoning`, `breakingChanges`, and `highlights` (an array of strings), ensuring a standardized response format.

```YAML
success: boolean
recommendedVersion: string
changeType: string
confidence: string
reasoning: string
breakingChanges: boolean
highlights: string[]
```

--------------------------------

### Specifying Allowed Tools for Version Analysis - YAML

Source: https://github.com/davidpp/channelcoder/blob/main/examples/release-analysis.md

This YAML snippet lists the external tools that the AI agent is permitted to use during its analysis. Currently, it allows 'Read' and 'Grep', indicating potential capabilities for reading files or searching content, which can aid in deeper code change examination.

```YAML
- Read
- Grep
```

--------------------------------

### Channelcoder Dynamic Greeting Template

Source: https://github.com/davidpp/channelcoder/blob/main/examples/simple-test.md

This template snippet generates a dynamic greeting based on provided inputs. It uses the 'greeting' input if available, otherwise defaults to 'Hello', and then appends the 'name' input. This forms the initial part of the response, making it personalized.

```Channelcoder Template
${greeting || "Hello"}, ${name}!
```

--------------------------------

### Basic ChannelCoder SDK Usage (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet demonstrates the fundamental usage of the `claude` function from the ChannelCoder SDK. It shows how to send simple string prompts, use template literals for dynamic content, and load prompts from files with associated data.

```typescript
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' }
});
```

--------------------------------

### Running File-Based Prompts via CLI (Bash)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This Bash command demonstrates how to execute a file-based prompt (`analyze.md`) using the `channelcoder` CLI. It shows how to pass data variables (`-d`) for interpolation within the prompt.

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

--------------------------------

### ChannelCoder SDK: Execution Modes

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet illustrates the different execution modes available in the ChannelCoder SDK. It demonstrates the default `run` mode for programmatic result retrieval, the `stream` mode for real-time chunked responses, and the `interactive` mode for a direct terminal interaction that replaces the current process, along with explicit usage of the `run` function.

```typescript
import { claude, interactive, stream, run } 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!

// Explicit run mode
const result2 = await run('Analyze code', { tools: ['Read'] });
```

--------------------------------

### Building Claude CLI Commands in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This TypeScript function, 'buildCommand', demonstrates how the SDK constructs the Claude CLI command array based on various options. It handles conversation resumption (--resume, --continue) and conditionally adds the --print flag for non-interactive modes, ensuring the correct command line arguments are generated.

```TypeScript
// buildCommand() in process.ts
async buildCommand(options: CCOptions & PromptConfig): Promise<string[]> {
  const cmd = ['claude'];
  
  // Handle conversation resumption
  if (options.resume) {
    cmd.push('--resume', options.resume);
  } else if (options.continue) {
    cmd.push('--continue');
  }
  
  // Only add --print for non-interactive modes
  if (options.mode !== 'interactive') {
    cmd.push('--print');
  }
  
  // Add other options...
  return cmd;
}
```

--------------------------------

### Defining Release Metadata JSON Structure

Source: https://github.com/davidpp/channelcoder/blob/main/scripts/prompts/release-analysis.md

This JSON snippet defines the structure for the `.release/metadata.json` file. It captures key release metrics and information such as success status, version, release date, a summary, breaking changes, highlights, categories of changes, total changes, commit count, and files changed. This metadata is useful for release tracking and reporting.

```json
{
  "success": true,
  "version": "X.Y.Z",
  "release_date": "{RELEASE_DATE}",
  "summary": "One-line release summary",
  "breaking_changes": false,
  "highlights": ["Most important change", "Second most important"],
  "categories_used": ["Added", "Fixed"],
  "total_changes": 5,
  "commit_count": 10,
  "files_changed": 15
}
```

--------------------------------

### Launching Interactive Mode with Shell Exec (TypeScript/Shell)

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This code demonstrates how the SDK launches the Claude CLI in interactive mode by using 'execSync' with a shell 'exec' command. This strategy replaces the current Node.js process with the Claude CLI process, optimizing memory usage, enabling direct signal handling, and ensuring clean process management.

```TypeScript
// launchInteractive implementation
const shellCommand = `exec echo '${escapedPrompt}' | exec claude ${escapedArgs}`;
execSync(shellCommand, { stdio: 'inherit', shell: true });
```

--------------------------------

### Defining Release Changelog Markdown Format

Source: https://github.com/davidpp/channelcoder/blob/main/scripts/prompts/release-analysis.md

This Markdown snippet outlines the standard format for the `.release/changelog.md` file, focusing on user-facing changes. It includes sections for 'Added' features, 'Changed' functionalities, and 'Fixed' issues, providing a clear and concise summary of updates for end-users. The format adheres to common changelog conventions.

```markdown
## [X.Y.Z] - {RELEASE_DATE}

### Added
- **Feature Name**: User benefit description

### Changed  
- **Feature Name**: What changed for users

### Fixed
- **Issue Area**: What was broken and now works
```

--------------------------------

### ChannelCoder SDK: Simple Function API

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet highlights the simplicity and flexibility of the `claude` function in the ChannelCoder SDK. It demonstrates sending direct inline prompts, using file-based prompts (auto-detected by extension), and passing a comprehensive options object to control AI behavior, including specifying tools, resuming sessions, and limiting agentic turns.

```typescript
// 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
});
```

--------------------------------

### Using Input Variables in a String Template

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/optional.md

This snippet demonstrates how to embed variables from a defined input schema into a string template. It uses placeholder syntax `{variable}` for direct substitution and `{variable || 'default'}` for providing a fallback value if the variable is undefined or null, ensuring graceful handling of optional data.

```Template
Hello {name}, age: {age || 'unknown'}
```

--------------------------------

### Defining Release Version JSON Structure

Source: https://github.com/davidpp/channelcoder/blob/main/scripts/prompts/release-analysis.md

This JSON snippet defines the structure for the `.release/version.json` file. It includes fields for current and new version numbers, the type of version bump (major, minor, patch), confidence level, reasoning for the bump, and indicators for breaking changes and notable features. This file is crucial for automated version management.

```json
{
  "current_version": "{CURRENT_VERSION}",
  "new_version": "X.Y.Z",
  "bump_type": "major|minor|patch",
  "confidence": "high|medium|low", 
  "reasoning": "Brief explanation",
  "breaking_changes": false,
  "notable_features": ["feature1", "feature2"]
}
```

--------------------------------

### Running Smart Check for Full Project

Source: https://github.com/davidpp/channelcoder/blob/main/CLAUDE.md

This command executes the 'scripts/code-check.ts' script to perform a complete error check across the entire project. It's useful for comprehensive validation or when running CI/CD checks.

```Shell
scripts/code-check.ts --full
```

--------------------------------

### Analyzing Git Changes with Bash

Source: https://github.com/davidpp/channelcoder/blob/main/scripts/prompts/release-analysis.md

This snippet provides Bash commands to analyze Git changes between a specified last tag and the current HEAD. `git log --oneline` shows a concise history of commits, while `git diff --stat` provides a summary of file changes, helping to understand the scope of the release.

```bash
git log {LAST_TAG}..HEAD --oneline
git diff {LAST_TAG}..HEAD --stat
```

--------------------------------

### Defining Tool Access Patterns in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This snippet illustrates various ways to specify tool access for Claude. It shows how to provide a simple list of allowed tools, apply tool restrictions using Claude CLI syntax (e.g., `Bash(git:*)`), and explicitly disallow certain tools, enabling fine-grained control over Claude's capabilities.

```typescript
// Simple tool list
await claude('prompt', {
  tools: ['Read', 'Write', 'Bash']
});

// Tool restrictions (Claude CLI syntax)
await claude('prompt', {
  tools: ['Bash(git:*)', 'Read(**/*.ts)']
});

// Disallow specific tools
await claude('prompt', {
  tools: ['Read', 'Write'],
  disallowedTools: ['Bash']
});
```

--------------------------------

### Referencing Defined Parameters in a Template

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/schema-defaults.md

This snippet demonstrates how to reference the previously defined 'status' and 'count' parameters within a simple text template. The curly braces `{}` indicate placeholders that will be replaced by the actual parameter values at runtime.

```Templating
Status: {status}
Count: {count}
```

--------------------------------

### Creating Domain-Specific Wrapper Functions in TypeScript

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This snippet illustrates how to create a domain-specific wrapper function, `analyzeTask`, that encapsulates common parameters and logic for interacting with the `claude` function. It pre-configures prompt paths, data, and tools, while also allowing for options overrides, promoting code reusability and maintainability.

```typescript
// Domain-specific wrapper
async function analyzeTask(taskId: string, options = {}) {
  return claude('prompts/analyze-task.md', {
    data: { taskId },
    tools: ['Read', 'Grep'],
    ...options  // Allow overrides
  });
}

// Usage
await analyzeTask('FEAT-123');
await analyzeTask('FEAT-123', { verbose: true });
```

--------------------------------

### Streaming Responses with ChannelCoder SDK (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet demonstrates how to use the `stream` function from the ChannelCoder SDK to receive AI responses in real-time. It iterates over chunks of content, allowing for progressive display or processing of the generated output.

```typescript
import { stream } from 'channelcoder';

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

--------------------------------

### Managing Claude Sessions with ChannelCoder (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Shows how to resume previous Claude sessions. Users can either specify a 'session-id' to continue a particular conversation or use 'continue: true' to resume the most recent session, allowing for persistent conversational context.

```typescript
// 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
});
```

--------------------------------

### ChannelCoder SDK: Variable Interpolation

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This TypeScript snippet showcases ChannelCoder's powerful multi-place variable interpolation. It demonstrates how to inject dynamic data into both inline prompts and file-based prompts using the `data` option, allowing for highly customizable and reusable prompt templates.

```typescript
// 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' }
});
```

--------------------------------

### Migrating from Class-Based to Function-Based Claude API (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This snippet illustrates the transition from the older class-based API (cc.run, cc.fromFile, cc.prompt) to the new function-based API (claude) for interacting with the Claude CLI. The new API simplifies calls by using a direct 'claude' function and modifies the 'fromFile' signature to accept an options object.

```TypeScript
// Old way
const result = await cc.run('prompt');
const result = await cc.fromFile('file.md', data);
await cc.prompt`Hello ${name}`.launch();

// New way
const result = await claude('prompt');
const result = await claude('file.md', { data });
await claude`Hello ${name}`;
```

--------------------------------

### Accessing Input Data with ChannelCoder Templating

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/nested.md

These lines demonstrate how to access and display specific fields from the defined input data structure using ChannelCoder's custom templating syntax. It shows direct interpolation of 'user.name', 'user.email', and 'settings.theme' into output strings, illustrating basic data binding.

```ChannelCoder Templating
User: {user.name} ({user.email})
Theme: {settings.theme}
```

--------------------------------

### Defining Schemas with YAML Notation

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This YAML snippet illustrates the syntax for defining data schemas within ChannelCoder, which are automatically converted to Zod schemas. It covers basic types (string, number, boolean), optional fields using '?', arrays using '[]', and nested objects.

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

--------------------------------

### Defining Input and Output Schemas (YAML)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

This YAML snippet demonstrates how to define structured input and output schemas for ChannelCoder. It supports basic types (string, number, boolean), optional fields, arrays, and nested objects, which are used for validating variables before interpolation and Claude's responses.

```yaml
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
```

--------------------------------

### ChannelCoder SDK `ClaudeOptions` Interface Definition

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This snippet defines the `ClaudeOptions` interface, which specifies the configuration parameters available for controlling Claude interactions in the ChannelCoder SDK. It details options for data interpolation, system prompts, tool management, session continuation, execution control (e.g., `maxTurns`, `mode`), and output preferences like `verbose` and `outputFormat`. These options map directly to Claude CLI flags.

```TypeScript
interface ClaudeOptions {
  // Data & Prompts
  data?: Record<string, any>;        // Variable interpolation
  system?: string;                   // System prompt (inline or .md file)
  appendSystem?: string;             // Append to system prompt
  
  // Tools
  tools?: string[];                  // Allowed tools (maps to --tools)
  disallowedTools?: string[];        // Disallowed tools
  mcpConfig?: string;                // MCP server config file
  permissionTool?: string;           // MCP permission tool
  
  // Session Management
  resume?: string;                   // Resume session by ID
  continue?: boolean;                // Continue most recent session
  
  // Execution Control
  maxTurns?: number;                 // Limit agentic turns
  mode?: 'run' | 'stream' | 'interactive';  // Execution mode
  includeEvents?: boolean;           // Include event tracking;
  
  // Other
  verbose?: boolean;                 // Verbose output
  outputFormat?: 'json' | 'text';    // Output format
}
```

--------------------------------

### Defining Input Parameters in YAML/DSL

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/schema-defaults.md

This snippet defines two input parameters, 'status' and 'count', specifying their data types (string, number) and default values. This structure is typically used for schema validation or initial state configuration within a domain-specific language.

```YAML
input:
  status:
    type: string
    default: "pending"
  count:
    type: number
    default: 0
```

--------------------------------

### Defining Input Schema with YAML

Source: https://github.com/davidpp/channelcoder/blob/main/test/prompts/optional.md

This snippet defines a structured input schema using a YAML-like syntax. It specifies 'name' as a required string, 'age' as an optional number, and 'active' as an optional boolean. This schema can be used to validate or type-check incoming data for a process or function.

```YAML
input:
  name: string
  age?: number
  active?: boolean
```

--------------------------------

### Launching Interactive Mode with ChannelCoder (TypeScript)

Source: https://github.com/davidpp/channelcoder/blob/main/README.md

Illustrates how to launch Claude in an interactive shell session using 'interactive'. This mode replaces the current Node.js process, giving Claude direct terminal control and making it suitable for long, interactive sessions without Node.js memory overhead. Code after this call will not execute.

```typescript
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
```

--------------------------------

### Resuming and Continuing Sessions in ChannelCoder SDK

Source: https://github.com/davidpp/channelcoder/blob/main/docs/sdk-structure.md

This snippet demonstrates how to resume or continue existing Claude sessions using the ChannelCoder SDK across different execution modes. It shows how to use the `resume` option with a `sessionId` for `run` and `interactive` modes, and the `continue: true` option for `stream` mode. When resuming, a prompt is not typically needed as the session context is restored.

```TypeScript
// Run mode with resume
await run('Continue analysis', { resume: sessionId });
// Command: claude --print --resume SESSION_ID

// Stream mode with continue
await stream('Continue', { continue: true });
// Command: claude --print --output-format stream-json --continue

// Interactive mode with resume (no prompt needed)
await interactive('', { resume: sessionId });
// Command: exec claude --resume SESSION_ID
```

--------------------------------

### Running Smart Check Against Base Branch

Source: https://github.com/davidpp/channelcoder/blob/main/CLAUDE.md

This command runs the 'scripts/code-check.ts' script, comparing changes against a specified base branch (e.g., 'main'). It helps identify errors introduced in a specific feature branch relative to the main development line.

```Shell
scripts/code-check.ts --base=main
```