II.
Page overview
Reference · livepage:docs-user-guide-reference-configuration
Babysitter Configuration Reference overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-user-guide-reference-configuration.
Attributes
nodeKind
Page
sourcePath
docs/user-guide/reference/configuration.md
sourceKind
repo-docs
title
Babysitter Configuration Reference
displayName
Babysitter Configuration Reference
slug
docs/user-guide/reference/configuration
articlePath
wiki/docs/user-guide/reference/configuration.md
article
[Docs](../index.md) › [Reference](./index.md) › 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.
---
## On this page
- [Overview](#overview)
- [Environment Variables](#environment-variables)
- [SDK Variables](#sdk-variables)
- [Debug Variables](#debug-variables)
- [Session Variables](#session-variables)
- [Directory Structure](#directory-structure)
- [Runs Directory](#runs-directory)
- [Run Directory Structure](#run-directory-structure)
- [Plugin Directory](#plugin-directory)
- [Configuration Files](#configuration-files)
- [run.json](#runjson)
- [inputs.json](#inputsjson)
- [state.json](#statejson)
- [hooks.json](#hooksjson-claude-code)
- [Hook Configuration](#hook-configuration)
- [Hook Discovery](#hook-discovery)
- [Hook Types](#hook-types)
- [Custom Hook Development](#custom-hook-development)
- [Process Configuration](#process-configuration)
- [Task Definitions](#task-definitions)
- [Breakpoint Configuration](#breakpoint-configuration)
- [Default Values](#default-values)
- [Configuration Precedence](#configuration-precedence)
---
## 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](./glossary.md) 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](../getting-started/migration.md).
---
## Directory Structure
### Runs Directory
Default location: `.a5c/runs/` (configurable via `RUNS_DIR` or `--runs-dir`)
```
.a5c/
└── runs/
├── run-20260125-143012-feature-a/
├── run-20260125-150000-bugfix/
└── run-20260126-090000-refactor/
```
### Run Directory Structure
Each run has the following structure:
```
.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
```
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](../features/hooks.md) 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](../features/hooks.md) 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
---
## Related Documentation
- [CLI Reference](./cli-reference.md) - Complete CLI documentation
- [Glossary](./glossary.md) - Term definitions
- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
---
## Next steps
- **Next:** [Security](./security.md)
- **Related:** [CLI Reference](./cli-reference.md), [Troubleshooting](./troubleshooting.md)
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-user-guide-reference·PageUser Guide Reference