{
  "id": "page:docs-user-guide-reference-configuration",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/reference/configuration.md",
  "_cluster": "wiki",
  "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": "\n# Babysitter Configuration Reference\n\n**Version:** 1.0\n**Last Updated:** 2026-01-25\n\nComplete reference for all Babysitter configuration options, environment variables, file paths, and settings.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Environment Variables](#environment-variables)\n  - [SDK Variables](#sdk-variables)\n  - [Worker Variables](#worker-variables)\n  - [Debug Variables](#debug-variables)\n  - [Session Variables](#session-variables)\n- [Directory Structure](#directory-structure)\n  - [Runs Directory](#runs-directory)\n  - [Run Directory Structure](#run-directory-structure)\n  - [Plugin Directory](#plugin-directory)\n- [Configuration Files](#configuration-files)\n  - [run.json](#runjson)\n  - [inputs.json](#inputsjson)\n  - [state.json](#statejson)\n  - [hooks.json](#hooksjson)\n- [Hook Configuration](#hook-configuration)\n  - [Hook Discovery](#hook-discovery)\n  - [Hook Types](#hook-types)\n  - [Custom Hook Development](#custom-hook-development)\n- [Process Configuration](#process-configuration)\n  - [Task Definitions](#task-definitions)\n  - [Breakpoint Configuration](#breakpoint-configuration)\n- [Default Values](#default-values)\n- [Configuration Precedence](#configuration-precedence)\n\n---\n\n## Overview\n\nBabysitter configuration is managed through:\n1. **Environment variables** - Runtime settings\n2. **File-based configuration** - Per-run and per-project settings\n3. **CLI flags** - Command-line overrides\n4. **Hooks** - Extensible behavior customization\n\n### Configuration Philosophy\n\n- **Convention over configuration** - Sensible defaults work out of the box\n- **Explicit overrides** - Environment variables and CLI flags for customization\n- **Immutable runs** - Run configuration is captured at creation time\n- **Git-friendly** - Human-readable JSON and markdown files\n\n---\n\n## Environment Variables\n\n### SDK Variables\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|---------|\n| `RUNS_DIR` | Base directory for runs | `.` (current directory) | `.a5c/runs` |\n| `REPO_ROOT` | Repository root directory | Current working directory | `/home/user/project` |\n| `BABYSITTER_LOG_LEVEL` | Logging verbosity | `info` | `debug`, `warn`, `error` |\n| `BABYSITTER_ALLOW_SECRET_LOGS` | Allow logging sensitive data | `false` | `true` |\n\n#### RUNS_DIR\n\nSpecifies the base directory where run directories are created and stored.\n\n```bash\n# Default behavior - runs created in current directory\nbabysitter run:create --process-id dev/build --entry ./main.js#process\n\n# Override via environment variable\nexport RUNS_DIR=.a5c/runs\nbabysitter run:create --process-id dev/build --entry ./main.js#process\n\n# Override via CLI flag (takes precedence)\nbabysitter run:create --runs-dir .a5c/runs --process-id dev/build --entry ./main.js#process\n```\n\n#### BABYSITTER_LOG_LEVEL\n\nControls the verbosity of log output.\n\n| Level | Description |\n|-------|-------------|\n| `error` | Only errors |\n| `warn` | Warnings and errors |\n| `info` | Normal operation (default) |\n| `debug` | Detailed debugging information |\n\n```bash\nexport BABYSITTER_LOG_LEVEL=debug\nbabysitter run:iterate run-123 --json\n```\n\n#### BABYSITTER_ALLOW_SECRET_LOGS\n\nWhen set to `true` along with `--verbose` and `--json`, allows task payloads to be included in output.\n\n```bash\nBABYSITTER_ALLOW_SECRET_LOGS=true babysitter task:show run-123 ef-abc --json --verbose\n```\n\n**Security Warning:** Only enable in development/debugging. Never enable in production logs.\n\n---\n\n### Debug Variables\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|---------|\n| `DEBUG` | Node.js debug namespaces | None | `babysitter:*` |\n\n```bash\n\n# Enable Node.js debug output\nexport DEBUG=babysitter:*\nbabysitter run:iterate run-123\n```\n\n---\n\n### Session Variables\n\nThese variables are set by Claude Code and used by the plugin.\n\n| Variable | Description | Set By |\n|----------|-------------|--------|\n| `AGENT_SESSION_ID` | Cross-harness session identifier (written to `CLAUDE_ENV_FILE` by session-start hook) | Babysitter |\n| `CLAUDE_PLUGIN_ROOT` | Plugin installation directory | Claude Code |\n| `CLAUDE_ENV_FILE` | Path to environment persistence file | Claude Code |\n\nThese are automatically available in hooks and skills. Use them for session isolation and state management.\n\n```bash\n# In a hook script\necho \"Session: $AGENT_SESSION_ID\"\necho \"Plugin root: $CLAUDE_PLUGIN_ROOT\"\n\n# State file path pattern\nSTATE_FILE=\"${BABYSITTER_STATE_DIR:-$HOME/.a5c/state}/${AGENT_SESSION_ID}.md\"\n```\n\n---\n\n## Directory Structure\n\n### Runs Directory\n\nDefault location: `.a5c/runs/` (configurable via `RUNS_DIR` or `--runs-dir`)\n\n```\n.a5c/\n└── runs/\n    ├── run-20260125-143012-feature-a/\n    ├── run-20260125-150000-bugfix/\n    └── run-20260126-090000-refactor/\n```\n\n### Run Directory Structure\n\nEach run has the following structure:\n\n```\n.a5c/runs/<runId>/\n├── run.json              # Run metadata (immutable after creation)\n├── inputs.json           # Initial inputs (immutable after creation)\n├── code/\n│   └── main.js           # Process implementation\n├── artifacts/\n│   ├── process.md        # Process description\n│   ├── plan.md           # Implementation plan\n│   └── ...               # Other generated artifacts\n├── journal/\n│   ├── 000001.<ulid>.json  # Event 1\n│   ├── 000002.<ulid>.json  # Event 2\n│   └── ...                 # Append-only event log\n├── state/\n│   └── state.json        # Derived state cache (gitignored, rebuildable)\n└── tasks/\n    └── <effectId>/\n        ├── task.json     # Task definition\n        ├── input.json    # Task inputs\n        ├── result.json   # Task result (written by SDK)\n        ├── output.json   # Value file (written by executor)\n        ├── stdout.log    # Standard output\n        └── stderr.log    # Standard error\n```\n\n#### File Descriptions\n\n| File | Purpose | Mutability |\n|------|---------|------------|\n| `run.json` | Run metadata, process configuration | Immutable |\n| `inputs.json` | Initial process inputs | Immutable |\n| `code/main.js` | Process implementation | Editable |\n| `artifacts/*` | Generated files (plans, specs) | Generated |\n| `journal/*` | Event log | Append-only |\n| `state/state.json` | Cached state | Derived (rebuildable) |\n| `tasks/*/task.json` | Task definitions | Immutable |\n| `tasks/*/result.json` | Task results | Written by SDK |\n\n### Plugin Directory\n\nLocation: Managed by Claude Code plugin system\n\n```\nplugins/babysitter-unified/\n├── plugin.json           # Plugin manifest\n├── versions.json         # Unified SDK/plugin version marker\n├── skills/\n│   └── babysit/\n│       └── SKILL.md      # Skill instructions\n├── hooks/\n│   ├── session-start.sh\n│   ├── stop.sh\n│   ├── pre-tool-use.sh\n│   └── user-prompt-submit.sh\n├── per-harness/          # Harness-specific generated surfaces and docs\n└── bin/                  # Shared install helpers\n```\n\n---\n\n## Configuration Files\n\n### run.json\n\nCreated by `run:create`. Contains immutable run metadata.\n\n**Schema:**\n```json\n{\n  \"runId\": \"run-20260125-143012\",\n  \"createdAt\": \"2026-01-25T14:30:12.123Z\",\n  \"process\": {\n    \"processId\": \"dev/build\",\n    \"entry\": \".a5c/processes/build/main.js#buildProcess\",\n    \"revision\": \"1.0.0\"\n  },\n  \"request\": \"Build the authentication module\",\n  \"prompt\": \"Build the authentication module with JWT tokens and role-based access control\"\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `runId` | string | Unique run identifier |\n| `createdAt` | ISO 8601 | Creation timestamp |\n| `process.processId` | string | Process type identifier |\n| `process.entry` | string | Entry point `<path>#<export>` |\n| `process.revision` | string | Optional version/revision |\n| `request` | string | Optional human-readable description |\n| `prompt` | string | Optional initial user prompt (persisted for context recovery) |\n\n---\n\n### inputs.json\n\nInitial inputs provided to the process.\n\n**Schema:** User-defined, passed to process function as first argument.\n\n**Example:**\n```json\n{\n  \"feature\": \"user-authentication\",\n  \"targetQuality\": 85,\n  \"maxIterations\": 5,\n  \"config\": {\n    \"database\": \"sqlite\",\n    \"testFramework\": \"jest\"\n  }\n}\n```\n\n---\n\n### state.json\n\nDerived state cache. Rebuilt from journal if missing.\n\n**Schema:**\n```json\n{\n  \"runId\": \"run-20260125-143012\",\n  \"status\": \"running\",\n  \"version\": 42,\n  \"processState\": {},\n  \"invocations\": {\n    \"task/build:1\": {\n      \"effectId\": \"effect-abc123\",\n      \"status\": \"completed\",\n      \"resultRef\": \"tasks/effect-abc123/result.json\"\n    }\n  },\n  \"pendingEffects\": [\n    {\n      \"effectId\": \"effect-def456\",\n      \"kind\": \"node\",\n      \"status\": \"requested\",\n      \"taskId\": \"task/lint\"\n    }\n  ]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `runId` | Run identifier |\n| `status` | `created`, `running`, `waiting`, `completed`, `failed` |\n| `version` | State version (increments with each event) |\n| `processState` | Process-specific state data |\n| `invocations` | Map of completed task invocations |\n| `pendingEffects` | List of pending effects |\n\n**Note:** This file is gitignored and can be deleted. It will be rebuilt by `run:rebuild-state` or the next CLI command.\n\n---\n\n### hooks.json\n\nHook registration for Claude Code integration.\n\n**Location:** generated from `plugins/babysitter-unified/plugin.json`\n\n**Schema:**\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n**Hook Events:**\n- `SessionStart` - When Claude Code session starts\n- `Stop` - When Claude tries to exit\n- `PreToolUse` - Before tool invocation\n- `PostToolUse` - After tool invocation\n\n---\n\n## Hook Configuration\n\n### Hook Discovery\n\nHooks are discovered in priority order:\n\n1. **Per-repo hooks:** `.a5c/hooks/<hook-name>/*.sh`\n2. **Per-user hooks:** `~/.config/babysitter/hooks/<hook-name>/*.sh`\n3. **Plugin hooks:** `plugins/babysitter-unified/hooks/<hook-name>.sh`\n\nAll executable files (`.sh`) in the hook directory are executed in lexicographic order.\n\n### Hook Types\n\n#### SDK Lifecycle Hooks\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `on-run-start` | Run creation | Initialize run resources |\n| `on-run-complete` | Successful completion | Cleanup, notifications |\n| `on-run-fail` | Run failure | Error handling, alerts |\n| `on-iteration-start` | Before iteration | **Core orchestration** |\n| `on-iteration-end` | After iteration | Finalization, logging |\n| `on-task-start` | Before task execution | Preparation, metrics |\n| `on-task-complete` | After task execution | Cleanup, metrics |\n| `on-breakpoint` | Breakpoint created | Notifications |\n\n#### Claude Code Hooks\n\n| Hook | Trigger | Purpose |\n|------|---------|---------|\n| `SessionStart` | Session begins | Session setup |\n| `Stop` | Exit attempt | In-session loop control |\n| `PreToolUse` | Before tool call | Validation |\n| `PostToolUse` | After tool call | Logging |\n\n### Custom Hook Development\n\n#### Basic Hook Template\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Read JSON payload from stdin\nPAYLOAD=$(cat)\n\n# Parse payload\nRUN_ID=$(echo \"$PAYLOAD\" | jq -r '.runId')\nEFFECT_ID=$(echo \"$PAYLOAD\" | jq -r '.effectId // empty')\n\n# Log to stderr (not captured as result)\necho \"Processing: $RUN_ID\" >&2\n\n# Your logic here\n# ...\n\n# Return JSON result via stdout\necho '{\"ok\": true, \"action\": \"processed\"}'\n```\n\n#### Hook Input/Output\n\n| Channel | Purpose |\n|---------|---------|\n| stdin | JSON payload input |\n| stdout | JSON result output (must be valid JSON) |\n| stderr | Logging (not captured) |\n\n#### Making Hooks Executable\n\n```bash\nchmod +x .a5c/hooks/on-run-complete/my-hook.sh\n```\n\n#### Example: Slack Notification Hook\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nPAYLOAD=$(cat)\nRUN_ID=$(echo \"$PAYLOAD\" | jq -r '.runId')\nSTATUS=$(echo \"$PAYLOAD\" | jq -r '.status')\n\n# Send to Slack\ncurl -s -X POST \"$SLACK_WEBHOOK_URL\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\\\"text\\\": \\\"Run $RUN_ID completed with status: $STATUS\\\"}\" >&2\n\necho '{\"ok\": true}'\n```\n\n---\n\n## Process Configuration\n\n### Task Definitions\n\nTasks are defined in the process file using the `defineTask` helper.\n\n#### Node Task\n\n```javascript\nexport const buildTask = defineTask('build', (args, ctx) => ({\n  kind: 'node',\n  title: 'Build project',\n  node: {\n    entry: './scripts/build.js',\n    args: ['--target', args.target],\n    env: {\n      NODE_ENV: 'production'\n    },\n    timeout: 300000  // 5 minutes\n  },\n  io: {\n    inputJsonPath: `tasks/${ctx.effectId}/input.json`,\n    outputJsonPath: `tasks/${ctx.effectId}/result.json`\n  }\n}));\n```\n\n#### Agent Task\n\n```javascript\nexport const analyzeTask = defineTask('analyze', (args, ctx) => ({\n  kind: 'agent',\n  title: 'Analyze code quality',\n  agent: {\n    name: 'code-analyzer',\n    prompt: {\n      role: 'Senior code reviewer',\n      task: 'Analyze the codebase for quality issues',\n      context: args,\n      instructions: [\n        'Review code structure',\n        'Check naming conventions',\n        'Identify potential bugs'\n      ],\n      outputFormat: 'JSON'\n    },\n    outputSchema: {\n      type: 'object',\n      required: ['score', 'issues'],\n      properties: {\n        score: { type: 'number', minimum: 0, maximum: 100 },\n        issues: { type: 'array' }\n      }\n    }\n  }\n}));\n```\n\n#### Skill Task\n\n```javascript\nexport const refactorTask = defineTask('refactor', (args, ctx) => ({\n  kind: 'skill',\n  title: 'Refactor module',\n  skill: {\n    name: 'code-refactor',\n    context: {\n      files: args.files,\n      pattern: args.pattern,\n      instructions: args.instructions\n    }\n  }\n}));\n```\n\n### Breakpoint Configuration\n\n```javascript\nawait ctx.breakpoint({\n  question: 'Approve the deployment to production?',\n  title: 'Production Deployment Approval',\n  context: {\n    runId: ctx.runId,\n    files: [\n      { path: 'artifacts/deploy-plan.md', format: 'markdown', label: 'Deployment Plan' },\n      { path: 'artifacts/changes.md', format: 'markdown', label: 'Changes Summary' },\n      { path: 'code/main.js', format: 'code', language: 'javascript', label: 'Process Code' }\n    ]\n  }\n});\n```\n\n---\n\n## Default Values\n\n### SDK Defaults\n\n| Setting | Default Value |\n|---------|---------------|\n| Runs directory | Current directory (`.`) |\n| Log level | `info` |\n| Max iterations | 100 (in testing harness) |\n| Task timeout | None (process-defined) |\n\n### In-Session Loop Defaults\n\n| Setting | Default Value |\n|---------|---------------|\n| Max iterations | `0` (unlimited) |\n| State file location | `${BABYSITTER_STATE_DIR:-~/.a5c/state}/${SESSION_ID}.md` |\n\n---\n\n## Configuration Precedence\n\nWhen multiple configuration sources exist, they are applied in this order (later overrides earlier):\n\n1. **Built-in defaults** - Hardcoded in SDK\n2. **Configuration files** - `run.json`, `inputs.json`\n3. **Environment variables** - `RUNS_DIR`, `PORT`, etc.\n4. **CLI flags** - `--runs-dir`, `--json`, `--verbose`\n\n### Example Precedence\n\n```bash\n# Built-in default: runs dir = \".\"\n# Environment variable: RUNS_DIR=.a5c/runs\n# CLI flag: --runs-dir /custom/runs\n\nexport RUNS_DIR=.a5c/runs\nbabysitter run:create --runs-dir /custom/runs --process-id dev/build\n\n# Result: runs dir = /custom/runs (CLI flag wins)\n```\n\n---\n\n## Configuration Best Practices\n\n### Development Environment\n\n```bash\n# .envrc or .env\nexport RUNS_DIR=.a5c/runs\nexport BABYSITTER_LOG_LEVEL=debug\n```\n\n### CI/CD Environment\n\n```bash\n# GitHub Actions example\nenv:\n  RUNS_DIR: .a5c/runs\n  BABYSITTER_LOG_LEVEL: info\n  BABYSITTER_ALLOW_SECRET_LOGS: false\n```\n\n### Security Recommendations\n\n1. **Never commit tokens** - Use environment variables or secrets management\n2. **Restrict network binding** - Use `--host 127.0.0.1` for local-only access\n3. **Enable authentication** - Set `AGENT_TOKEN` and `HUMAN_TOKEN`\n4. **Audit logs** - Keep `BABYSITTER_ALLOW_SECRET_LOGS=false` in production\n\n---\n\n## Related Documentation\n\n- [CLI Reference](./cli-reference.md) - Complete CLI documentation\n- [Glossary](./glossary.md) - Term definitions\n- [Troubleshooting](./troubleshooting.md) - Common issues and solutions\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-reference",
      "to": "page:docs-user-guide-reference-configuration",
      "kind": "contains_page"
    }
  ]
}