Crate claude_runner_core

Expand description

§claude_runner_core

Workspace: assistant — claude_runner_core

Claude Code process execution with builder pattern and single execution point.

§Files

File / Directory	Responsibility
`Cargo.toml`	Crate manifest: deps, features, metadata
`src/`	Builder pattern implementation: `ClaudeCommand`, types, process scanner
`tests/`	Builder API, migration validation, verification framework (31 test files)
`docs/`	Behavioral requirements: features, invariants, parameter reference
`task/`	Crate-level task tracking

§Responsibility Table

Entity	Responsibility	Input→Output	Scope	Out of Scope
claude_runner_core	Claude Code process execution	ClaudeCommand Config → Process Output	Command building, process spawning, output capture, token limits	❌ Session storage paths → `claude_profile` ❌ Continuation detection → `claude_profile` ❌ Context injection → `dream_agent` ❌ Parameter parsing → `dream_agent` ❌ Session strategy → `dream_agent`

§Scope

Responsibility:

Claude Code process execution (Command::new(“claude”))
Builder pattern API (ClaudeCommand::new().with_*())
Token limit configuration (200K default)
Process output capture (stdout/stderr)
Single execution point (duplication = 1x)

In Scope:

ClaudeCommand::new() builder entry point
with_working_directory(), with_max_output_tokens(), with_continue_conversation(), etc. (61 typed builder methods)
execute() terminal method with process spawning
stdout/stderr capture and parsing
Exit code handling and error mapping

Out of Scope:

❌ Session storage path resolution → delegated to claude_profile crate
❌ Continuation detection → delegated to claude_profile crate
❌ Context injection from wplan → delegated to dream_agent crate
❌ Parameter parsing from CLI → delegated to dream_agent crate
❌ Session lifecycle strategy → delegated to dream_agent crate

§Features

Builder Pattern: Fluent API with method chaining (NO deprecated factories)
Token Limit Fix: Explicit 200K token default (prevents “exceeded maximum” errors)
Single Execution Point: Consolidates duplicate Command::new(“claude”) calls
Type Safety: Builder pattern enforces correct configuration
Minimal Dependencies: Only error_tools + standard library

§Usage

use claude_runner_core::ClaudeCommand;

// Basic execution
let result = ClaudeCommand::new()
  .with_working_directory("/home/user/project")
  .with_max_output_tokens(200_000)
  .with_continue_conversation(true)
  .execute()?;

println!("Output: {}", result.stdout);

// Advanced configuration
let result = ClaudeCommand::new()
  .with_working_directory("/tmp/work")
  .with_max_output_tokens(200_000)
  .with_model("claude-opus-4-5")
  .with_verbose(true)
  .with_system_prompt("You are a helpful coding assistant")
  .with_message("Fix the bug in main.rs")
  .execute()?;

§Architecture

Builder Pattern Flow:

ClaudeCommand::new()
  └→ with_working_directory()      (fluent method chaining)
  └→ with_max_output_tokens()
  └→ with_continue_conversation()
  └→ execute()                     ← SINGLE execution point
      └→ CommandBuilder::build()   (construct std::process::Command)
      └→ Command::new("claude")    ← ONLY location in entire codebase
      └→ ProcessExecutor::run()    (spawn, capture output)
      └→ Return ExecutionResult

§Migration from Old API

Before (DEPRECATED - DO NOT USE):

// Factory method (DEPRECATED)
ClaudeCommand::generate(/* 40 parameters */)

// Mixed execution (DEPRECATED)
session.execute_interactive()
session.execute_non_interactive()

// Duplicate execution points (2x)
Command::new("claude")  // Location 1
Command::new("claude")  // Location 2

After (THIS CRATE):

// Builder pattern (CORRECT)
ClaudeCommand::new()
  .with_*()
  .execute()

// Single execution point (1x)
Command::new("claude")  // ONLY in claude_runner_core::execute()

§Token Limit Bug Fix

Problem: Default Claude Code token limit is 32K, causing “exceeded maximum” errors

Solution: Set explicit max_output_tokens to 200K:

use claude_runner_core::ClaudeCommand;

let result = ClaudeCommand::new()
  .with_max_output_tokens(200_000)  // Explicit token limit
  .execute()?;

§Reference Documentation

Parameter Reference: docs/claude_params/ — all 59 claude binary parameters (CLI flags + env vars), with builder API mapping and default comparisons
Builder API: src/command.rs doc comments — authoritative builder method documentation
Tests: tests/readme.md — full test suite coverage map
Tasks: task/ — crate-level task tracking

§Dependencies

error_tools: Workspace-standard error handling (Result, Error types)

Total: 1 workspace dependency (error_tools), 0 external direct dependencies

§Testing

cargo nextest run

§Critical Execution Rule

Command::new(“claude”) MUST appear exactly once:

✅ Single occurrence in claude_runner_core::execute()
❌ Zero occurrences in dream_agent
❌ Zero occurrences in claude_profile

Verification: grep -r "Command::new.*claude" src/ should find exactly 1 match. Claude Code CLI Launcher

General-purpose library for executing Claude Code CLI commands programmatically with full parameter control.

§Quick Start

use claude_runner_core::ClaudeCommand;

let cmd = ClaudeCommand::new()
  .with_working_directory( "/tmp/work" )
  .with_max_output_tokens( 200_000 );

let output = cmd.execute()?;
println!( "{}", output.stdout );

§Architecture

Single execution point: All commands go through execute()
Builder pattern: Configuration via chainable with_*() methods
Private fields: Can’t construct with struct literals
No session logic: Pure execution, no state management

§Migration: Old Way Impossible

This crate enforces the new builder pattern at compile time. Old patterns from the deprecated API are impossible:

§Old Pattern 1: Factory Method (Doesn’t Exist)

use claude_runner_core::ClaudeCommand;

// ERROR: generate() method doesn't exist
let cmd = ClaudeCommand::generate("/tmp", "msg", 1000, Strategy::Fresh);

§Old Pattern 2: Direct Construction (Fields Private)

use claude_runner_core::ClaudeCommand;
use std::path::PathBuf;

// ERROR: fields are private
let cmd = ClaudeCommand {
  working_directory: Some(PathBuf::from("/tmp")),
  max_output_tokens: Some(200_000),
  continue_conversation: false,
  message: None,
  args: vec![],
};

§New Pattern: Builder Only

use claude_runner_core::ClaudeCommand;

// the ONLY way to construct ClaudeCommand
let output = ClaudeCommand::new()
  .with_working_directory( "/tmp" )
  .with_max_output_tokens( 200_000 )
  .execute()?;

See spec.md for complete documentation.

Re-exports§

pub use crate::session_dir::SessionManager;
pub use crate::session_dir::Strategy;

Modules§

process: Process scanner: enumerate running Claude Code instances via /proc.
session_dir: Directory-based session isolation for Claude Code invocations.

Structs§

ClaudeCommand: Builder for Claude Code CLI commands
ExecutionOutput: Output from a non-interactive Claude Code execution

Enums§

ActionMode: Tool approval behavior mode
EffortLevel: Effort level for model reasoning
InputFormat: Input format for Claude Code stdin
LogLevel: Logging verbosity level
OutputFormat: Output format for Claude Code execution
PermissionMode: Permission mode for tool execution

Functions§

claude_version: Query installed Claude Code version.