babysitter

Babysitter implements event sourcing to record every orchestration decision, task execution, and state transition in an immutable journal, enabling deterministic replay where identical inputs always produce identical outputs. The system appends events via a5c_append_event.py orchestrator script and reconstructs workflow state by replaying the event log, eliminating non-determinism from LLM-based decision-making. This architecture guarantees reproducibility across sessions and enables forensic analysis of agent behavior.

Babysitter implements a quality convergence system that automatically iterates on task outputs until they meet defined quality gates before allowing workflow progression. The system evaluates outputs against quality criteria, triggers refinement loops when gates fail, and tracks convergence metrics across iterations. This is integrated into the orchestration loop via quality-gate evaluation hooks that block advancement until thresholds are met, enabling self-improving agentic workflows without manual intervention.

Babysitter provides both a CLI interface and a programmatic SDK for orchestrating workflows, enabling both interactive development and headless execution in CI/CD pipelines. The CLI supports commands for running workflows, inspecting run directories, and managing processes, while the SDK provides a Node.js API for embedding Babysitter in applications. The system supports headless execution via an internal harness that doesn't require an IDE, enabling workflows to run in automated environments. Both CLI and SDK maintain the same orchestration semantics (determinism, event sourcing, quality convergence).

Babysitter includes an Observer Dashboard component that provides real-time visualization of workflow execution, task progress, quality metrics, and orchestration state. The dashboard connects to running workflows and displays live updates of task execution, quality convergence iterations, and human-in-the-loop breakpoints. It enables monitoring of multiple concurrent workflows and provides drill-down capabilities to inspect individual task execution details. The dashboard integrates with the run directory and event journal to provide accurate, up-to-date execution visibility.

Babysitter includes an MCP (Model Context Protocol) server component that exposes Babysitter capabilities through the standardized MCP protocol, enabling integration with any MCP-compatible client. The MCP server allows external tools and applications to invoke Babysitter workflows, query execution state, and receive notifications about workflow progress. This enables Babysitter to be used as a backend service for orchestration, with clients communicating via the standard MCP protocol rather than direct SDK calls.

Babysitter provides a comprehensive task types reference that defines the standard task types supported by the orchestration system (e.g., code generation, testing, refinement, approval). Each task type has a standardized definition including inputs, outputs, quality criteria, and orchestration behavior. Task types are composable and can be extended with custom implementations. The task types reference serves as the contract between orchestration logic and task implementations, ensuring consistency across workflows.

Babysitter implements security best practices for agentic workflows including multi-harness isolation, credential management, and sandboxing of task execution. The system supports running workflows in isolated harness instances to prevent cross-workflow interference, manages credentials securely without exposing them in logs or event journals, and provides guidance on secure deployment patterns. Security considerations are integrated into the orchestration architecture rather than added as an afterthought.

Babysitter provides a breakpoint system that pauses workflow execution at critical decision points and requires explicit human approval before progression. The system integrates with the stop-hook mechanism (babysitter-stop-hook.sh) to halt execution, surface decision context to a human reviewer, and resume only after approval is granted. This is implemented as a special hook type in the lifecycle system that blocks the orchestration loop until human signal is received, enabling safe deployment of agentic workflows in production environments.

Babysitter provides a multi-harness adapter architecture that abstracts away differences between Claude Code, Cursor, and other AI harnesses through a unified SDK interface. The system discovers available harnesses, routes orchestration commands to the appropriate adapter, and manages harness-specific lifecycle hooks. A plugin marketplace system (referenced in .claude-plugin/marketplace.json and .cursor-plugin/marketplace.json) enables distribution of Babysitter as a plugin across multiple IDE and harness ecosystems, with each adapter implementing the same core orchestration contract.

Babysitter implements a skill discovery system that dynamically identifies available skills and processes at runtime, then injects them into the agent's execution context via the Context API. Skills are packaged as reusable process definitions that agents can invoke, and the discovery mechanism scans the process library to populate available capabilities. This enables agents to self-discover what they can do without hardcoded skill lists, and allows workflows to be extended with new skills without modifying orchestration code.

Babysitter enables workflows to be paused and resumed across sessions using the stop-hook mechanism, which gracefully halts execution and preserves all state in the run directory. When a workflow is resumed, the orchestration loop replays the event journal to reconstruct the exact state at the pause point, then continues execution from that point without data loss or re-execution of completed work. This is implemented via the babysitter-stop-hook.sh script and the event sourcing architecture, enabling long-running workflows to survive interruptions.

Babysitter provides a comprehensive hook system that allows custom code to execute at specific lifecycle points in the orchestration loop (e.g., before task execution, after quality evaluation, on workflow completion). The system supports both native orchestrator hooks and custom orchestrators that implement the entire orchestration strategy. Hooks are registered via configuration and executed at defined points in the orchestration state machine, enabling extensibility without modifying core orchestration logic. The hook system integrates with the event sourcing architecture to ensure hooks are deterministic and replay-safe.

Babysitter enables workflows to be defined as composable processes that can be reused, nested, and packaged as distributable units. Processes are defined in code with a standardized structure, can invoke other processes, and can be packaged for distribution via the plugin marketplace. The system supports process composition patterns (sequential, parallel, conditional) and maintains determinism across composed workflows through the event sourcing architecture. Process definitions are stored in the process library and can be discovered and invoked dynamically.

Babysitter supports parallel execution of tasks and processes while maintaining determinism through coordinated event sourcing. The system can execute multiple tasks concurrently, coordinate their results, and ensure that the same parallel execution always produces the same outcome. Parallel patterns are defined in process compositions and coordinated through the orchestration loop, with results aggregated deterministically. This enables efficient execution of independent tasks while preserving the deterministic guarantees of the event sourcing architecture.

Babysitter organizes all workflow state, artifacts, and metadata in a structured run directory that serves as the single source of truth for a workflow execution. The run directory contains the event journal, task outputs, quality metrics, and execution traces, all organized in a predictable structure. This enables easy inspection of workflow execution, debugging of specific tasks, and archival of complete execution records. The run directory structure is designed to be human-readable and machine-parseable, supporting both manual inspection and programmatic access.