Agentic AI Atlas

Wiki article

docs/user-guide/reference/configuration

Reading · 11 min

Babysitter Configuration Reference reference

Docs(../index.md) › Reference(./index.md) › Configuration

Page nodewiki/docs/user-guide/reference/configuration.mdNearby pages · 9Documents · 0

Continue reading

Nearby pages in the same section.

Adapter Types: the full taxonomy Adapters CLI Reference Babysitter CLI Reference Error Catalog Frequently Asked Questions (FAQ)Babysitter Glossary Security Guide Babysitter Slash Commands Reference Troubleshooting Guide

Docs › Reference › Configuration

Babysitter Configuration Reference

**Version:** 6.0.0 (v6) **Last Updated:** 2026-06-22

Complete reference for all Babysitter configuration options, environment variables, file paths, and settings.

**In plain English:** the variables and paths below work the same on every supported harness. v6 standardized session identification on the harness-agnostic AGENT_SESSION_ID, removed the --plugin-root flag, and made session resolution PID-scoped. Deprecated keys are marked below.

---

Overview

Babysitter configuration is managed through: 1. **Environment variables** - Runtime settings 2. **File-based configuration** - Per-run and per-project settings 3. **CLI flags** - Command-line overrides 4. **Hooks** - Extensible behavior customization

Configuration Philosophy

**Convention over configuration** - Sensible defaults work out of the box
**Explicit overrides** - Environment variables and CLI flags for customization
**Immutable runs** - Run configuration is captured at creation time
**Git-friendly** - Human-readable JSON and markdown files

---

Environment Variables

SDK Variables

Variable	Description	Default	Example
`RUNS_DIR`	Base directory for runs	`.` (current directory)	`.a5c/runs`
`REPO_ROOT`	Repository root directory	Current working directory	`/home/user/project`
`BABYSITTER_LOG_LEVEL`	Logging verbosity	`info`	`debug`, `warn`, `error`
`BABYSITTER_ALLOW_SECRET_LOGS`	Allow logging sensitive data	`false`	`true`

RUNS_DIR

Specifies the base directory where run directories are created and stored.

bash

# Default behavior - runs created in current directory
babysitter run:create --process-id dev/build --entry ./main.js#process

# Override via environment variable
export RUNS_DIR=.a5c/runs
babysitter run:create --process-id dev/build --entry ./main.js#process

# Override via CLI flag (takes precedence)
babysitter run:create --runs-dir .a5c/runs --process-id dev/build --entry ./main.js#process

BABYSITTER_LOG_LEVEL

Controls the verbosity of log output.

Level	Description
`error`	Only errors
`warn`	Warnings and errors
`info`	Normal operation (default)
`debug`	Detailed debugging information

bash

export BABYSITTER_LOG_LEVEL=debug
babysitter run:iterate run-123 --json

BABYSITTER_ALLOW_SECRET_LOGS

When set to true along with --verbose and --json, allows task payloads to be included in output.

bash

BABYSITTER_ALLOW_SECRET_LOGS=true babysitter task:show run-123 ef-abc --json --verbose

**Security Warning:** Only enable in development/debugging. Never enable in production logs.

---

Debug Variables

Variable	Description	Default	Example
`DEBUG`	Node.js debug namespaces	None	`babysitter:*`

bash


# Enable Node.js debug output
export DEBUG=babysitter:*
babysitter run:iterate run-123

---

Session Variables

These variables are set by the harness and used by the plugin. v6 uses **harness-agnostic** names so the same hooks work across all 12 supported harnesses.

Variable	Description	Set By
`AGENT_SESSION_ID`	Current harness session identifier	The active harness
`BABYSITTER_PLUGIN_ROOT`	Plugin installation directory (injected into hooks by the runtime)	The runtime
`BABYSITTER_ENV_FILE`	Path to environment persistence file	The runtime
`BABYSITTER_TRUST_ENV_SESSION`	Opt back into legacy env-first session resolution (`1` to enable)	You (escape hatch)

These are automatically available in hooks and skills. Use them for session isolation and state management.

bash

# In a hook script
echo "Session: $AGENT_SESSION_ID"
echo "Plugin root: $BABYSITTER_PLUGIN_ROOT"

# State file path pattern
STATE_FILE="${BABYSITTER_STATE_DIR:-$HOME/.a5c/state}/${AGENT_SESSION_ID}.md"

Session Resolution (v6)

Session resolution is now **PID-scoped**: the active session is resolved from PID-scoped session markers rather than inheriting blindly from the environment. This prevents one shell's session ID from leaking into another. If you need the legacy env-first behavior (for example, in a wrapper that deliberately exports a session ID), set:

bash

export BABYSITTER_TRUST_ENV_SESSION=1

**Deprecated (do not use as canonical):** CLAUDE_SESSION_ID → AGENT_SESSION_ID; BABYSITTER_SESSION_ID → AGENT_SESSION_ID. The --plugin-root flag and the CLAUDE_PLUGIN_ROOT variable are **gone** — plugin-root resolution is handled automatically by the runtime, which injects BABYSITTER_PLUGIN_ROOT into hooks for you. It is not a variable you set. See the Migration Guide.

---

Directory Structure

Runs Directory

Default location: .a5c/runs/ (configurable via RUNS_DIR or --runs-dir)

Code

.a5c/
└── runs/
    ├── run-20260125-143012-feature-a/
    ├── run-20260125-150000-bugfix/
    └── run-20260126-090000-refactor/

Run Directory Structure

Each run has the following structure:

Code

.a5c/runs/<runId>/
├── run.json              # Run metadata (immutable after creation)
├── inputs.json           # Initial inputs (immutable after creation)
├── code/
│   └── main.js           # Process implementation
├── artifacts/
│   ├── process.md        # Process description
│   ├── plan.md           # Implementation plan
│   └── ...               # Other generated artifacts
├── journal/
│   ├── 000001.<ulid>.json  # Event 1
│   ├── 000002.<ulid>.json  # Event 2
│   └── ...                 # Append-only event log
├── state/
│   └── state.json        # Derived state cache (gitignored, rebuildable)
└── tasks/
    └── <effectId>/
        ├── task.json     # Task definition
        ├── input.json    # Task inputs
        ├── result.json   # Task result (written by SDK)
        ├── output.json   # Value file (written by executor)
        ├── stdout.log    # Standard output
        └── stderr.log    # Standard error

File Descriptions

File	Purpose	Mutability
`run.json`	Run metadata, process configuration	Immutable
`inputs.json`	Initial process inputs	Immutable
`code/main.js`	Process implementation	Editable
`artifacts/*`	Generated files (plans, specs)	Generated
`journal/*`	Event log	Append-only
`state/state.json`	Cached state	Derived (rebuildable)
`tasks/*/task.json`	Task definitions	Immutable
`tasks/*/result.json`	Task results	Written by SDK

Plugin Directory

Location: Managed by Claude Code plugin system

Code

plugins/babysitter-unified/
├── plugin.json           # Plugin manifest
├── versions.json         # Unified SDK/plugin version marker
├── skills/
│   └── babysit/
│       └── SKILL.md      # Skill instructions
├── hooks/
│   ├── session-start.sh
│   ├── stop.sh
│   ├── pre-tool-use.sh
│   └── user-prompt-submit.sh
├── per-harness/          # Harness-specific generated surfaces and docs
└── bin/                  # Shared install helpers

---

Configuration Files

run.json

Created by run:create. Contains immutable run metadata.

**Schema:**

json

{
  "runId": "run-20260125-143012",
  "createdAt": "2026-01-25T14:30:12.123Z",
  "process": {
    "processId": "dev/build",
    "entry": ".a5c/processes/build/main.js#buildProcess",
    "revision": "1.0.0"
  },
  "request": "Build the authentication module",
  "prompt": "Build the authentication module with JWT tokens and role-based access control"
}

Field	Type	Description
`runId`	string	Unique run identifier
`createdAt`	ISO 8601	Creation timestamp
`process.processId`	string	Process type identifier
`process.entry`	string	Entry point `<path>#<export>`
`process.revision`	string	Optional version/revision
`request`	string	Optional human-readable description
`prompt`	string	Optional initial user prompt (persisted for context recovery)

---

inputs.json

Initial inputs provided to the process.

**Schema:** User-defined, passed to process function as first argument.

**Example:**

json

{
  "feature": "user-authentication",
  "targetQuality": 85,
  "maxIterations": 5,
  "config": {
    "database": "sqlite",
    "testFramework": "jest"
  }
}

---

state.json

Derived state cache. Rebuilt from journal if missing.

**Schema:**

json

{
  "runId": "run-20260125-143012",
  "status": "running",
  "version": 42,
  "processState": {},
  "invocations": {
    "task/build:1": {
      "effectId": "effect-abc123",
      "status": "completed",
      "resultRef": "tasks/effect-abc123/result.json"
    }
  },
  "pendingEffects": [
    {
      "effectId": "effect-def456",
      "kind": "node",
      "status": "requested",
      "taskId": "task/lint"
    }
  ]
}

Field	Description
`runId`	Run identifier
`status`	`created`, `running`, `waiting`, `completed`, `failed`
`version`	State version (increments with each event)
`processState`	Process-specific state data
`invocations`	Map of completed task invocations
`pendingEffects`	List of pending effects

**Note:** This file is gitignored and can be deleted. It will be rebuilt by run:rebuild-state or the next CLI command.

---

hooks.json (Claude Code)

Hook registration for the Claude Code harness. Other harnesses register continuation hooks via their own manifests (gemini-extension.json, the openclaw daemon, ACP for Hermes, and so on) — see Hooks for the per-harness continuation models.

**Location (Claude Code):** generated from plugins/babysitter-unified/plugin.json

**Schema:**

json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${BABYSITTER_PLUGIN_ROOT}/hooks/session-start.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${BABYSITTER_PLUGIN_ROOT}/hooks/stop.sh"
          }
        ]
      }
    ]
  }
}

**Hook Events (Claude Code):**

SessionStart - When the Claude Code session starts
Stop - When Claude tries to exit (drives the loop on Claude Code only)
PreToolUse - Before tool invocation
PostToolUse - After tool invocation

The Stop-driven loop is **specific to Claude Code**. Do not assume it on AfterAgent (Gemini/antigravity), daemon (openclaw), ACP (Hermes), or session-idle (opencode) harnesses.

---

Hook Configuration

Hook Discovery

Hooks are discovered in priority order:

1. **Per-repo hooks:** .a5c/hooks/<hook-name>/*.sh 2. **Per-user hooks:** ~/.config/babysitter/hooks/<hook-name>/*.sh 3. **Plugin hooks:** plugins/babysitter-unified/hooks/<hook-name>.sh

All executable files (.sh) in the hook directory are executed in lexicographic order.

Hook Types

SDK Lifecycle Hooks

Hook	Trigger	Purpose
`on-run-start`	Run creation	Initialize run resources
`on-run-complete`	Successful completion	Cleanup, notifications
`on-run-fail`	Run failure	Error handling, alerts
`on-iteration-start`	Before iteration	Core orchestration
`on-iteration-end`	After iteration	Finalization, logging
`on-task-start`	Before task execution	Preparation, metrics
`on-task-complete`	After task execution	Cleanup, metrics
`on-breakpoint`	Breakpoint created	Notifications

Harness Continuation Hooks (vary by harness)

The hooks that drive the loop turn-to-turn differ per harness. The Claude Code set is shown below; see Hooks for the full per-harness table (AfterAgent, daemon, ACP, session-idle, thin-skill aliases).

Hook (Claude Code)	Trigger	Purpose
`SessionStart`	Session begins	Session setup
`Stop`	Exit attempt	In-session loop control (Claude Code only)
`PreToolUse`	Before tool call	Validation
`PostToolUse`	After tool call	Logging

Custom Hook Development

Basic Hook Template

bash

#!/bin/bash
set -euo pipefail

# Read JSON payload from stdin
PAYLOAD=$(cat)

# Parse payload
RUN_ID=$(echo "$PAYLOAD" | jq -r '.runId')
EFFECT_ID=$(echo "$PAYLOAD" | jq -r '.effectId // empty')

# Log to stderr (not captured as result)
echo "Processing: $RUN_ID" >&2

# Your logic here
# ...

# Return JSON result via stdout
echo '{"ok": true, "action": "processed"}'

Hook Input/Output

Channel	Purpose
stdin	JSON payload input
stdout	JSON result output (must be valid JSON)
stderr	Logging (not captured)

Making Hooks Executable

bash

chmod +x .a5c/hooks/on-run-complete/my-hook.sh

Example: Slack Notification Hook

bash

#!/bin/bash
set -euo pipefail

PAYLOAD=$(cat)
RUN_ID=$(echo "$PAYLOAD" | jq -r '.runId')
STATUS=$(echo "$PAYLOAD" | jq -r '.status')

# Send to Slack
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Run $RUN_ID completed with status: $STATUS\"}" >&2

echo '{"ok": true}'

---

Process Configuration

Task Definitions

Tasks are defined in the process file using the defineTask helper.

Node Task

javascript

export const buildTask = defineTask('build', (args, ctx) => ({
  kind: 'node',
  title: 'Build project',
  node: {
    entry: './scripts/build.js',
    args: ['--target', args.target],
    env: {
      NODE_ENV: 'production'
    },
    timeout: 300000  // 5 minutes
  },
  io: {
    inputJsonPath: `tasks/${ctx.effectId}/input.json`,
    outputJsonPath: `tasks/${ctx.effectId}/result.json`
  }
}));

Agent Task

javascript

export const analyzeTask = defineTask('analyze', (args, ctx) => ({
  kind: 'agent',
  title: 'Analyze code quality',
  agent: {
    name: 'code-analyzer',
    prompt: {
      role: 'Senior code reviewer',
      task: 'Analyze the codebase for quality issues',
      context: args,
      instructions: [
        'Review code structure',
        'Check naming conventions',
        'Identify potential bugs'
      ],
      outputFormat: 'JSON'
    },
    outputSchema: {
      type: 'object',
      required: ['score', 'issues'],
      properties: {
        score: { type: 'number', minimum: 0, maximum: 100 },
        issues: { type: 'array' }
      }
    }
  }
}));

Skill Task

javascript

export const refactorTask = defineTask('refactor', (args, ctx) => ({
  kind: 'skill',
  title: 'Refactor module',
  skill: {
    name: 'code-refactor',
    context: {
      files: args.files,
      pattern: args.pattern,
      instructions: args.instructions
    }
  }
}));

Breakpoint Configuration

javascript

await ctx.breakpoint({
  question: 'Approve the deployment to production?',
  title: 'Production Deployment Approval',
  context: {
    runId: ctx.runId,
    files: [
      { path: 'artifacts/deploy-plan.md', format: 'markdown', label: 'Deployment Plan' },
      { path: 'artifacts/changes.md', format: 'markdown', label: 'Changes Summary' },
      { path: 'code/main.js', format: 'code', language: 'javascript', label: 'Process Code' }
    ]
  }
});

---

Default Values

SDK Defaults

Setting	Default Value
Runs directory	Current directory (`.`)
Log level	`info`
Max iterations	100 (in testing harness)
Task timeout	None (process-defined)

In-Session Loop Defaults

Setting	Default Value
Max iterations	`0` (unlimited)
State file location	`${BABYSITTER_STATE_DIR:-~/.a5c/state}/${SESSION_ID}.md`

---

Configuration Precedence

When multiple configuration sources exist, they are applied in this order (later overrides earlier):

1. **Built-in defaults** - Hardcoded in SDK 2. **Configuration files** - run.json, inputs.json 3. **Environment variables** - RUNS_DIR, PORT, etc. 4. **CLI flags** - --runs-dir, --json, --verbose

Example Precedence

bash

# Built-in default: runs dir = "."
# Environment variable: RUNS_DIR=.a5c/runs
# CLI flag: --runs-dir /custom/runs

export RUNS_DIR=.a5c/runs
babysitter run:create --runs-dir /custom/runs --process-id dev/build

# Result: runs dir = /custom/runs (CLI flag wins)

---

Configuration Best Practices

Development Environment

bash

# .envrc or .env
export RUNS_DIR=.a5c/runs
export BABYSITTER_LOG_LEVEL=debug

CI/CD Environment

bash

# GitHub Actions example
env:
  RUNS_DIR: .a5c/runs
  BABYSITTER_LOG_LEVEL: info
  BABYSITTER_ALLOW_SECRET_LOGS: false

Security Recommendations

1. **Never commit tokens** - Use environment variables or secrets management 2. **Restrict network binding** - Use --host 127.0.0.1 for local-only access 3. **Enable authentication** - Set AGENT_TOKEN and HUMAN_TOKEN 4. **Audit logs** - Keep BABYSITTER_ALLOW_SECRET_LOGS=false in production

---

Next steps

**Next:** Security
**Related:** CLI Reference, Troubleshooting

Wiki article

docs/user-guide/reference/configuration

Reading · 11 min

Babysitter Configuration Reference reference

Docs(../index.md) › Reference(./index.md) › Configuration

Page nodewiki/docs/user-guide/reference/configuration.mdNearby pages · 9Documents · 0

Continue reading

Nearby pages in the same section.

Docs › Reference › Configuration

Babysitter Configuration Reference

**Version:** 6.0.0 (v6) **Last Updated:** 2026-06-22

Complete reference for all Babysitter configuration options, environment variables, file paths, and settings.

**In plain English:** the variables and paths below work the same on every supported harness. v6 standardized session identification on the harness-agnostic AGENT_SESSION_ID, removed the --plugin-root flag, and made session resolution PID-scoped. Deprecated keys are marked below.

---

Overview

Configuration Philosophy

**Convention over configuration** - Sensible defaults work out of the box
**Explicit overrides** - Environment variables and CLI flags for customization
**Immutable runs** - Run configuration is captured at creation time
**Git-friendly** - Human-readable JSON and markdown files

---

Environment Variables

SDK Variables

Variable	Description	Default	Example
`RUNS_DIR`	Base directory for runs	`.` (current directory)	`.a5c/runs`
`REPO_ROOT`	Repository root directory	Current working directory	`/home/user/project`
`BABYSITTER_LOG_LEVEL`	Logging verbosity	`info`	`debug`, `warn`, `error`
`BABYSITTER_ALLOW_SECRET_LOGS`	Allow logging sensitive data	`false`	`true`

RUNS_DIR

Specifies the base directory where run directories are created and stored.

bash

# Default behavior - runs created in current directory
babysitter run:create --process-id dev/build --entry ./main.js#process

# Override via environment variable
export RUNS_DIR=.a5c/runs
babysitter run:create --process-id dev/build --entry ./main.js#process

# Override via CLI flag (takes precedence)
babysitter run:create --runs-dir .a5c/runs --process-id dev/build --entry ./main.js#process

BABYSITTER_LOG_LEVEL

Controls the verbosity of log output.

Level	Description
`error`	Only errors
`warn`	Warnings and errors
`info`	Normal operation (default)
`debug`	Detailed debugging information

bash

export BABYSITTER_LOG_LEVEL=debug
babysitter run:iterate run-123 --json

BABYSITTER_ALLOW_SECRET_LOGS

When set to true along with --verbose and --json, allows task payloads to be included in output.

bash

BABYSITTER_ALLOW_SECRET_LOGS=true babysitter task:show run-123 ef-abc --json --verbose

**Security Warning:** Only enable in development/debugging. Never enable in production logs.

---

Debug Variables

Variable	Description	Default	Example
`DEBUG`	Node.js debug namespaces	None	`babysitter:*`

bash


# Enable Node.js debug output
export DEBUG=babysitter:*
babysitter run:iterate run-123

---

Session Variables

These variables are set by the harness and used by the plugin. v6 uses **harness-agnostic** names so the same hooks work across all 12 supported harnesses.

Variable	Description	Set By
`AGENT_SESSION_ID`	Current harness session identifier	The active harness
`BABYSITTER_PLUGIN_ROOT`	Plugin installation directory (injected into hooks by the runtime)	The runtime
`BABYSITTER_ENV_FILE`	Path to environment persistence file	The runtime
`BABYSITTER_TRUST_ENV_SESSION`	Opt back into legacy env-first session resolution (`1` to enable)	You (escape hatch)

These are automatically available in hooks and skills. Use them for session isolation and state management.

bash

# In a hook script
echo "Session: $AGENT_SESSION_ID"
echo "Plugin root: $BABYSITTER_PLUGIN_ROOT"

# State file path pattern
STATE_FILE="${BABYSITTER_STATE_DIR:-$HOME/.a5c/state}/${AGENT_SESSION_ID}.md"

Session Resolution (v6)

bash

export BABYSITTER_TRUST_ENV_SESSION=1

**Deprecated (do not use as canonical):** CLAUDE_SESSION_ID → AGENT_SESSION_ID; BABYSITTER_SESSION_ID → AGENT_SESSION_ID. The --plugin-root flag and the CLAUDE_PLUGIN_ROOT variable are **gone** — plugin-root resolution is handled automatically by the runtime, which injects BABYSITTER_PLUGIN_ROOT into hooks for you. It is not a variable you set. See the Migration Guide.

---

Directory Structure

Runs Directory

Default location: .a5c/runs/ (configurable via RUNS_DIR or --runs-dir)

Code

.a5c/
└── runs/
    ├── run-20260125-143012-feature-a/
    ├── run-20260125-150000-bugfix/
    └── run-20260126-090000-refactor/

Run Directory Structure

Each run has the following structure:

Code

.a5c/runs/<runId>/
├── run.json              # Run metadata (immutable after creation)
├── inputs.json           # Initial inputs (immutable after creation)
├── code/
│   └── main.js           # Process implementation
├── artifacts/
│   ├── process.md        # Process description
│   ├── plan.md           # Implementation plan
│   └── ...               # Other generated artifacts
├── journal/
│   ├── 000001.<ulid>.json  # Event 1
│   ├── 000002.<ulid>.json  # Event 2
│   └── ...                 # Append-only event log
├── state/
│   └── state.json        # Derived state cache (gitignored, rebuildable)
└── tasks/
    └── <effectId>/
        ├── task.json     # Task definition
        ├── input.json    # Task inputs
        ├── result.json   # Task result (written by SDK)
        ├── output.json   # Value file (written by executor)
        ├── stdout.log    # Standard output
        └── stderr.log    # Standard error

File Descriptions

File	Purpose	Mutability
`run.json`	Run metadata, process configuration	Immutable
`inputs.json`	Initial process inputs	Immutable
`code/main.js`	Process implementation	Editable
`artifacts/*`	Generated files (plans, specs)	Generated
`journal/*`	Event log	Append-only
`state/state.json`	Cached state	Derived (rebuildable)
`tasks/*/task.json`	Task definitions	Immutable
`tasks/*/result.json`	Task results	Written by SDK

Plugin Directory

Location: Managed by Claude Code plugin system

Code

plugins/babysitter-unified/
├── plugin.json           # Plugin manifest
├── versions.json         # Unified SDK/plugin version marker
├── skills/
│   └── babysit/
│       └── SKILL.md      # Skill instructions
├── hooks/
│   ├── session-start.sh
│   ├── stop.sh
│   ├── pre-tool-use.sh
│   └── user-prompt-submit.sh
├── per-harness/          # Harness-specific generated surfaces and docs
└── bin/                  # Shared install helpers

---

Configuration Files

run.json

Created by run:create. Contains immutable run metadata.

**Schema:**

json

{
  "runId": "run-20260125-143012",
  "createdAt": "2026-01-25T14:30:12.123Z",
  "process": {
    "processId": "dev/build",
    "entry": ".a5c/processes/build/main.js#buildProcess",
    "revision": "1.0.0"
  },
  "request": "Build the authentication module",
  "prompt": "Build the authentication module with JWT tokens and role-based access control"
}

Field	Type	Description
`runId`	string	Unique run identifier
`createdAt`	ISO 8601	Creation timestamp
`process.processId`	string	Process type identifier
`process.entry`	string	Entry point `<path>#<export>`
`process.revision`	string	Optional version/revision
`request`	string	Optional human-readable description
`prompt`	string	Optional initial user prompt (persisted for context recovery)

---

inputs.json

Initial inputs provided to the process.

**Schema:** User-defined, passed to process function as first argument.

**Example:**

json

{
  "feature": "user-authentication",
  "targetQuality": 85,
  "maxIterations": 5,
  "config": {
    "database": "sqlite",
    "testFramework": "jest"
  }
}

---

state.json

Derived state cache. Rebuilt from journal if missing.

**Schema:**

json

{
  "runId": "run-20260125-143012",
  "status": "running",
  "version": 42,
  "processState": {},
  "invocations": {
    "task/build:1": {
      "effectId": "effect-abc123",
      "status": "completed",
      "resultRef": "tasks/effect-abc123/result.json"
    }
  },
  "pendingEffects": [
    {
      "effectId": "effect-def456",
      "kind": "node",
      "status": "requested",
      "taskId": "task/lint"
    }
  ]
}

Field	Description
`runId`	Run identifier
`status`	`created`, `running`, `waiting`, `completed`, `failed`
`version`	State version (increments with each event)
`processState`	Process-specific state data
`invocations`	Map of completed task invocations
`pendingEffects`	List of pending effects

**Note:** This file is gitignored and can be deleted. It will be rebuilt by run:rebuild-state or the next CLI command.

---

hooks.json (Claude Code)

**Location (Claude Code):** generated from plugins/babysitter-unified/plugin.json

**Schema:**

json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${BABYSITTER_PLUGIN_ROOT}/hooks/session-start.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${BABYSITTER_PLUGIN_ROOT}/hooks/stop.sh"
          }
        ]
      }
    ]
  }
}

**Hook Events (Claude Code):**

SessionStart - When the Claude Code session starts
Stop - When Claude tries to exit (drives the loop on Claude Code only)
PreToolUse - Before tool invocation
PostToolUse - After tool invocation

The Stop-driven loop is **specific to Claude Code**. Do not assume it on AfterAgent (Gemini/antigravity), daemon (openclaw), ACP (Hermes), or session-idle (opencode) harnesses.

---

Hook Configuration

Hook Discovery

Hooks are discovered in priority order:

1. **Per-repo hooks:** .a5c/hooks/<hook-name>/*.sh 2. **Per-user hooks:** ~/.config/babysitter/hooks/<hook-name>/*.sh 3. **Plugin hooks:** plugins/babysitter-unified/hooks/<hook-name>.sh

All executable files (.sh) in the hook directory are executed in lexicographic order.

Hook Types

SDK Lifecycle Hooks

Hook	Trigger	Purpose
`on-run-start`	Run creation	Initialize run resources
`on-run-complete`	Successful completion	Cleanup, notifications
`on-run-fail`	Run failure	Error handling, alerts
`on-iteration-start`	Before iteration	Core orchestration
`on-iteration-end`	After iteration	Finalization, logging
`on-task-start`	Before task execution	Preparation, metrics
`on-task-complete`	After task execution	Cleanup, metrics
`on-breakpoint`	Breakpoint created	Notifications

Harness Continuation Hooks (vary by harness)

Hook (Claude Code)	Trigger	Purpose
`SessionStart`	Session begins	Session setup
`Stop`	Exit attempt	In-session loop control (Claude Code only)
`PreToolUse`	Before tool call	Validation
`PostToolUse`	After tool call	Logging

Custom Hook Development

Basic Hook Template

bash

#!/bin/bash
set -euo pipefail

# Read JSON payload from stdin
PAYLOAD=$(cat)

# Parse payload
RUN_ID=$(echo "$PAYLOAD" | jq -r '.runId')
EFFECT_ID=$(echo "$PAYLOAD" | jq -r '.effectId // empty')

# Log to stderr (not captured as result)
echo "Processing: $RUN_ID" >&2

# Your logic here
# ...

# Return JSON result via stdout
echo '{"ok": true, "action": "processed"}'

Hook Input/Output

Channel	Purpose
stdin	JSON payload input
stdout	JSON result output (must be valid JSON)
stderr	Logging (not captured)

Making Hooks Executable

bash

chmod +x .a5c/hooks/on-run-complete/my-hook.sh

Example: Slack Notification Hook

bash

#!/bin/bash
set -euo pipefail

PAYLOAD=$(cat)
RUN_ID=$(echo "$PAYLOAD" | jq -r '.runId')
STATUS=$(echo "$PAYLOAD" | jq -r '.status')

# Send to Slack
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Run $RUN_ID completed with status: $STATUS\"}" >&2

echo '{"ok": true}'

---

Process Configuration

Task Definitions

Tasks are defined in the process file using the defineTask helper.

Node Task

javascript

export const buildTask = defineTask('build', (args, ctx) => ({
  kind: 'node',
  title: 'Build project',
  node: {
    entry: './scripts/build.js',
    args: ['--target', args.target],
    env: {
      NODE_ENV: 'production'
    },
    timeout: 300000  // 5 minutes
  },
  io: {
    inputJsonPath: `tasks/${ctx.effectId}/input.json`,
    outputJsonPath: `tasks/${ctx.effectId}/result.json`
  }
}));

Agent Task

javascript

export const analyzeTask = defineTask('analyze', (args, ctx) => ({
  kind: 'agent',
  title: 'Analyze code quality',
  agent: {
    name: 'code-analyzer',
    prompt: {
      role: 'Senior code reviewer',
      task: 'Analyze the codebase for quality issues',
      context: args,
      instructions: [
        'Review code structure',
        'Check naming conventions',
        'Identify potential bugs'
      ],
      outputFormat: 'JSON'
    },
    outputSchema: {
      type: 'object',
      required: ['score', 'issues'],
      properties: {
        score: { type: 'number', minimum: 0, maximum: 100 },
        issues: { type: 'array' }
      }
    }
  }
}));

Skill Task

javascript

export const refactorTask = defineTask('refactor', (args, ctx) => ({
  kind: 'skill',
  title: 'Refactor module',
  skill: {
    name: 'code-refactor',
    context: {
      files: args.files,
      pattern: args.pattern,
      instructions: args.instructions
    }
  }
}));

Breakpoint Configuration

javascript

await ctx.breakpoint({
  question: 'Approve the deployment to production?',
  title: 'Production Deployment Approval',
  context: {
    runId: ctx.runId,
    files: [
      { path: 'artifacts/deploy-plan.md', format: 'markdown', label: 'Deployment Plan' },
      { path: 'artifacts/changes.md', format: 'markdown', label: 'Changes Summary' },
      { path: 'code/main.js', format: 'code', language: 'javascript', label: 'Process Code' }
    ]
  }
});

---

Default Values

SDK Defaults

Setting	Default Value
Runs directory	Current directory (`.`)
Log level	`info`
Max iterations	100 (in testing harness)
Task timeout	None (process-defined)

In-Session Loop Defaults

Setting	Default Value
Max iterations	`0` (unlimited)
State file location	`${BABYSITTER_STATE_DIR:-~/.a5c/state}/${SESSION_ID}.md`

---

Configuration Precedence

When multiple configuration sources exist, they are applied in this order (later overrides earlier):

Example Precedence

bash

# Built-in default: runs dir = "."
# Environment variable: RUNS_DIR=.a5c/runs
# CLI flag: --runs-dir /custom/runs

export RUNS_DIR=.a5c/runs
babysitter run:create --runs-dir /custom/runs --process-id dev/build

# Result: runs dir = /custom/runs (CLI flag wins)

---

Configuration Best Practices

Development Environment

bash

# .envrc or .env
export RUNS_DIR=.a5c/runs
export BABYSITTER_LOG_LEVEL=debug

CI/CD Environment

bash

# GitHub Actions example
env:
  RUNS_DIR: .a5c/runs
  BABYSITTER_LOG_LEVEL: info
  BABYSITTER_ALLOW_SECRET_LOGS: false

Security Recommendations

---

Next steps

**Next:** Security
**Related:** CLI Reference, Troubleshooting

Babysitter Configuration Reference reference

Continue reading

Babysitter Configuration Reference

On this page

Overview

Configuration Philosophy

Environment Variables

SDK Variables

RUNS_DIR

BABYSITTER_LOG_LEVEL

BABYSITTER_ALLOW_SECRET_LOGS

Debug Variables

Session Variables

Session Resolution (v6)

Directory Structure

Runs Directory

Run Directory Structure

File Descriptions

Plugin Directory

Configuration Files

run.json

inputs.json

state.json

hooks.json (Claude Code)

Hook Configuration

Hook Discovery

Hook Types

SDK Lifecycle Hooks

Harness Continuation Hooks (vary by harness)

Custom Hook Development

Basic Hook Template

Hook Input/Output

Making Hooks Executable

Example: Slack Notification Hook

Process Configuration

Task Definitions

Node Task

Agent Task

Skill Task

Breakpoint Configuration

Default Values

SDK Defaults

In-Session Loop Defaults

Configuration Precedence

Example Precedence

Configuration Best Practices

Development Environment

CI/CD Environment

Security Recommendations

Related Documentation

Next steps

Babysitter Configuration Reference reference

Continue reading

Babysitter Configuration Reference

On this page

Overview

Configuration Philosophy

Environment Variables

SDK Variables

RUNS_DIR

BABYSITTER_LOG_LEVEL

BABYSITTER_ALLOW_SECRET_LOGS

Debug Variables

Session Variables

Session Resolution (v6)

Directory Structure

Runs Directory

Run Directory Structure

File Descriptions

Plugin Directory

Configuration Files

run.json

inputs.json

state.json

hooks.json (Claude Code)

Hook Configuration

Hook Discovery

Hook Types

SDK Lifecycle Hooks

Harness Continuation Hooks (vary by harness)