{
  "id": "page:docs-user-guide-reference-faq",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/reference/faq.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/reference/faq.md",
    "sourceKind": "repo-docs",
    "title": "Frequently Asked Questions (FAQ)",
    "displayName": "Frequently Asked Questions (FAQ)",
    "slug": "docs/user-guide/reference/faq",
    "articlePath": "wiki/docs/user-guide/reference/faq.md",
    "article": "\n# Frequently Asked Questions (FAQ)\n\n**Version:** 1.1\n**Last Updated:** 2026-01-26\nLast refreshed: 2026-04-25\n**Category:** Reference\n\n---\n\n## Top 5 Questions (Start Here)\n\n**New to Babysitter?** These are the most common questions from first-time users:\n\n| Question | Quick Answer |\n|----------|--------------|\n| **What does Babysitter actually do?** | It automates the \"try → test → fix → repeat\" loop until your code meets quality targets |\n| **How do I start?** | Just type `/babysitter:call build a login page` in Claude Code |\n| **Do I need to write code?** | No - you use natural language. Babysitter handles the rest |\n| **What if something goes wrong?** | Everything is saved automatically. You can always resume or debug |\n| **Is it free?** | Babysitter is included with Claude Code - no additional cost |\n\nStill have questions? Browse the full FAQ below, or check the [Troubleshooting guide](./troubleshooting.md).\n\n---\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Installation and Setup](#installation-and-setup)\n- [Using Babysitter](#using-babysitter)\n- [Breakpoints and Approval](#breakpoints-and-approval)\n- [Quality Convergence](#quality-convergence)\n- [Sessions and Resumption](#sessions-and-resumption)\n- [Process Definitions](#process-definitions)\n- [Performance and Optimization](#performance-and-optimization)\n- [Security and Compliance](#security-and-compliance)\n- [Troubleshooting](#troubleshooting-faq)\n\n---\n\n## Getting Started\n\n### What is Babysitter?\n\nBabysitter is an event-sourced orchestration framework for Claude Code that enables deterministic, resumable, and human-in-the-loop workflow management. It allows you to build complex, multi-step development processes with built-in quality gates, human approval checkpoints, and automatic iteration until quality targets are met.\n\n**Key features:**\n- Structured multi-step workflows\n- Human approval checkpoints (breakpoints)\n- Iterative quality convergence\n- Complete audit trails\n- Session persistence and resumability\n\nSee: [README](../../../README.md)\n\n---\n\n### What is the difference between Babysitter and regular Claude Code?\n\n| Feature | Regular Claude Code | With Babysitter |\n|---------|---------------------|-----------------|\n| Session persistence | Lost on restart | Event-sourced, resumable |\n| Quality iteration | Manual prompting | Automated convergence |\n| Approval gates | Chat-based | Structured breakpoints |\n| Parallel execution | Sequential only | Built-in parallelism |\n| Audit trail | Chat history | Structured journal |\n\nBabysitter adds orchestration capabilities, enabling deterministic workflows with full traceability.\n\n---\n\n### Do I need programming knowledge to use Babysitter?\n\n**No.** You interact with Babysitter using natural language. Simply ask Claude to use the babysitter skill:\n\n```\nUse the babysitter skill to implement user authentication with TDD\n```\n\nOr use the slash command:\n\n```\n/babysitter:call implement user authentication with TDD\n```\n\nHowever, creating custom process definitions does require JavaScript/TypeScript knowledge.\n\nSee: [Getting Started](../getting-started/quickstart.md)\n\n---\n\n### Can I use Babysitter with other AI tools?\n\nBabysitter is specifically designed for Claude Code. The orchestration framework integrates with Claude Code's plugin system and skill infrastructure. While the underlying concepts could be adapted, Babysitter is not currently directly compatible with other AI coding assistants.\n\n---\n\n### What types of tasks is Babysitter best suited for?\n\nBabysitter excels at:\n\n- **Feature development** with TDD and quality gates\n- **Code refactoring** with iterative improvement\n- **Multi-phase workflows** requiring human approval\n- **Complex tasks** spanning multiple files or components\n- **Team workflows** requiring audit trails and approvals\n\nFor simple, one-off tasks, using Claude Code directly may be faster.\n\n---\n\n## Installation and Setup\n\n### What are the prerequisites for Babysitter?\n\n**Required:**\n- Node.js 20.0.0+ (recommend 22.x LTS)\n- Claude Code (latest version)\n- npm 8.0.0+\n\n**Optional:**\n- Git (for version control)\n- jq (for CLI output parsing)\n\nSee: [Installation Guide](../getting-started/installation.md)\n\n---\n\n### Why are there multiple Babysitter npm packages?\n\nBabysitter exposes a few public packages with different roles:\n\n1. **@a5c-ai/babysitter** - Recommended end-user install for the `babysitter` CLI\n2. **@a5c-ai/babysitter-sdk** - SDK/library package and the implementation behind the core CLI\n3. **@a5c-ai/babysitter-agent** - Optional runtime CLI for `call`, `resume`, `plan`, `doctor`, `start-server`, and `tui`\n\nMost users install:\n```bash\nnpm install -g @a5c-ai/babysitter@latest\n```\n\nAdd the optional runtime CLI only if you need those agent runtime commands:\n```bash\nnpm install -g @a5c-ai/babysitter-agent@latest\n```\n\n---\n\n### How much disk space does Babysitter use?\n\nThe `.a5c/runs/` directory stores all run data:\n\n- **Light usage:** 1-5 MB per run\n- **Heavy usage:** 50-100 MB per run (with large artifacts)\n\nMonitor disk usage:\n```bash\ndu -sh .a5c/\ndu -h .a5c/runs/* | sort -h\n```\n\nYou can safely delete old runs to reclaim space:\n```bash\nrm -rf .a5c/runs/<old-run-id>\n```\n\n---\n\n### How do I update Babysitter?\n\n**Update SDK packages:**\n```bash\nnpm update -g @a5c-ai/babysitter @a5c-ai/babysitter-agent\n```\n\n**Update Claude Code plugin:**\n```bash\nclaude plugin marketplace update a5c.ai\nclaude plugin update babysitter@a5c.ai\n```\n\n**Tip:** Update regularly (daily or weekly) for the latest features and fixes.\n\n---\n\n### Why doesn't the babysit skill appear in /skills?\n\nCommon causes and solutions:\n\n1. **Plugin not installed:**\n   ```bash\n   claude plugin marketplace add a5c-ai/babysitter-claude\n   claude plugin install --scope user babysitter@a5c.ai\n   ```\n\n2. **Plugin not enabled:**\n   ```bash\n   claude plugin enable --scope user babysitter@a5c.ai\n   ```\n\n3. **Claude Code not restarted:**\n   - Close all Claude Code windows\n   - Reopen Claude Code\n\n4. **Verify installation:**\n   ```bash\n   claude plugin list | grep babysitter\n   ```\n\nSee: [Installation Troubleshooting](../getting-started/installation.md#troubleshooting)\n\n---\n\n## Using Babysitter\n\n### How do I start a new babysitter run?\n\n**Via natural language:**\n```\nUse the babysitter skill to implement user authentication\n```\n\n**Via slash command:**\n```\n/babysitter:call implement user authentication with TDD\n```\n\n**With options:**\n```\n/babysitter:call implement user authentication --max-iterations 10\n```\n\nSee: [Quickstart](../getting-started/quickstart.md)\n\n---\n\n### How do I pause a babysitter run?\n\nSimply close Claude Code. The run is automatically saved to the event-sourced journal and can be resumed later.\n\nBabysitter is designed to be resumable at any point.\n\n---\n\n### How do I resume a paused run?\n\n**Via natural language:**\n```\nResume the babysitter run for the authentication feature\n```\n\n**Via slash command with run ID:**\n```\n/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\n**Find your run ID:**\n```bash\nls -lt .a5c/runs/ | head -10\n```\n\nSee: [Run Resumption](../features/run-resumption.md)\n\n---\n\n### How do I find my run ID?\n\nThe run ID is displayed when you start a workflow:\n```\nRun ID: 01KFFTSF8TK8C9GT3YM9QYQ6WG\nRun Directory: .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/\n```\n\n**Ask Claude to find recent runs:**\n```\nWhat babysitter runs have I done recently?\n```\n\n**Check run status:**\n```\nWhat's the status of my babysitter run?\n```\n\n---\n\n### Can I run multiple babysitter processes simultaneously?\n\n**Not recommended.** Running multiple babysitter instances in the same directory may cause journal conflicts.\n\nFor parallel work:\n- Use separate directories\n- Use separate runs for independent features\n- Wait for one run to complete before starting another in the same directory\n\n---\n\n### What happens if a task fails?\n\nWhen a task fails, Babysitter:\n\n1. Records the failure in the journal\n2. May retry based on configuration\n3. Reports the error for debugging\n\n**To investigate:**\n```bash\nbabysitter run:events <runId> --filter-type RUN_FAILED --json\n```\n\n**To resume after fixing:**\n```\n/babysitter:call resume\n```\n\n---\n\n### How do I debug a failed run?\n\n1. **Check the journal:**\n   ```bash\n   cat .a5c/runs/<runId>/journal/journal.jsonl | jq .\n   ```\n\n2. **View recent events:**\n   ```bash\n   babysitter run:events <runId> --limit 10 --reverse --json\n   ```\n\n3. **Find the error:**\n   ```bash\n   babysitter run:events <runId> --filter-type RUN_FAILED --json\n   ```\n\n4. **Ask Claude to analyze:**\n   ```\n   Analyze the babysitter run error for <runId> and diagnose\n   ```\n\nSee: [Troubleshooting Guide](./troubleshooting.md)\n\n---\n\n## Quality Convergence\n\n### What is a quality score?\n\nQuality scores are assessments of code quality generated by Babysitter's agent tasks. Scores are based on:\n\n- Test coverage\n- Test quality\n- Code quality metrics (lint, types)\n- Security analysis\n- Requirements alignment\n\nScores range from 0-100.\n\nSee: [Quality Convergence](../features/quality-convergence.md)\n\n---\n\n### How do I set a quality target?\n\nInclude it in your prompt:\n\n```\nUse babysitter with TDD and 85% quality target\n```\n\nOr specify in process inputs:\n```javascript\nconst { targetQuality = 85, maxIterations = 5 } = inputs;\n```\n\n---\n\n### What if quality score doesn't improve?\n\n**Common causes:**\n- Target is unrealistic\n- Fundamental issues blocking improvement\n- Scoring criteria too strict\n\n**Solutions:**\n\n1. **Review iteration feedback:**\n   ```\n   What recommendations came from my quality scoring?\n   ```\n\n2. **Lower the target:**\n   ```\n   /babysitter:call continue with 75% quality target\n   ```\n\n3. **Increase iterations:**\n   ```\n   /babysitter:call continue with max 10 iterations\n   ```\n\n4. **Review blocking issues:** Check lint errors, test failures, etc.\n\n---\n\n### Can I customize quality scoring?\n\nYes. Create custom agent tasks with your scoring criteria:\n\n```javascript\nexport const customScoringTask = defineTask('custom-scorer', (args, taskCtx) => ({\n  kind: 'agent',\n  title: 'Custom quality scoring',\n  agent: {\n    name: 'quality-assessor',\n    prompt: {\n      role: 'quality engineer',\n      task: 'Score based on our team standards',\n      instructions: [\n        'Your custom criteria here',\n        '...'\n      ]\n    }\n  }\n}));\n```\n\n---\n\n### How many iterations are typical?\n\n| Workflow Type | Typical Iterations | Maximum Recommended |\n|---------------|-------------------|---------------------|\n| Simple improvement | 2-3 | 5 |\n| Feature development | 3-5 | 10 |\n| Complex refactoring | 5-8 | 15 |\n\nAlways set iteration limits to prevent runaway loops.\n\n---\n\n## Sessions and Resumption\n\n### How does session resumption work?\n\nBabysitter uses event sourcing:\n\n1. Every action is recorded in the journal\n2. On resume, events are replayed to rebuild state\n3. Completed tasks return cached results\n4. Execution continues from the last pending point\n\nThis makes sessions fully resumable regardless of why they ended.\n\nSee: [Run Resumption](../features/run-resumption.md)\n\n---\n\n### Is progress lost if Claude Code crashes?\n\n**No.** All progress is preserved in the journal. Resume with:\n\n```\n/babysitter:call resume --run-id <runId>\n```\n\n---\n\n### Can different team members continue a run?\n\nYes. Runs are stored in the file system and can be continued by anyone with access:\n\n```\n# Developer A starts\n/babysitter:call implement feature X\n\n# Developer B continues\n/babysitter:call resume the feature X workflow\n```\n\nEnsure you share the `.a5c/` directory (e.g., via Git or shared storage).\n\n---\n\n### What happens to pending breakpoints on resume?\n\nPending breakpoints are preserved. On resume:\n\n1. Babysitter detects the pending breakpoint\n2. Checks if it has been approved\n3. If approved, continues; if not, waits\n\nApprove breakpoints before resuming, or resume and check the breakpoints UI.\n\n---\n\n### Can I route breakpoints to specific team members?\n\nYes. Use the `expert` field to route a breakpoint to specific reviewers:\n\n```javascript\nawait ctx.breakpoint({\n  question: 'Approve the security changes?',\n  expert: ['security-lead', 'tech-lead'],  // Route to specific experts\n  strategy: 'quorum',                       // Require majority approval\n  tags: ['security'],\n});\n```\n\nSupported strategies: `single` (default), `first-response-wins`, `collect-all`, `quorum`. The result includes `respondedBy` (who responded) and `allResponses` (for multi-reviewer strategies).\n\nSee: [Breakpoints](../features/breakpoints.md)\n\n---\n\n### What happens when a breakpoint is rejected?\n\nBreakpoints should never fail a process. The recommended pattern is to loop and retry with the reviewer's feedback:\n\n```javascript\nlet approved = false;\nlet previousFeedback;\nlet attempt = 0;\n\nwhile (!approved) {\n  attempt++;\n  const review = await ctx.breakpoint({\n    question: 'Approve the plan?',\n    previousFeedback,\n    attempt,\n  });\n  if (review.approved) {\n    approved = true;\n  } else {\n    previousFeedback = review.feedback;\n    // Refine work based on feedback before retrying\n  }\n}\n```\n\nSee: [Breakpoints - Robust Rejection Pattern](../features/breakpoints.md)\n\n---\n\n## Process Definitions\n\n### What is a process definition?\n\nA process definition is a JavaScript function that orchestrates workflow logic. It defines:\n\n- What tasks to run\n- In what order\n- With what conditions\n- Where to place breakpoints\n\n```javascript\nexport async function process(inputs, ctx) {\n  const plan = await ctx.task(planTask, { feature: inputs.feature });\n  const review = await ctx.breakpoint({ question: 'Approve plan?' });\n  if (!review.approved) return { success: false, feedback: review.feedback };\n  const result = await ctx.task(implementTask, { plan });\n  return result;\n}\n```\n\n> **Note:** `ctx.breakpoint()` returns a `BreakpointResult` with `{ approved, response?, feedback?, option? }`. Existing code that ignores the return value continues to work.\n\nSee: [Process Definitions](../features/process-definitions.md)\n\n---\n\n### Can I edit a process definition for a running workflow?\n\n**Not recommended.** Process definitions are associated with runs at creation time. Modifying them during execution may cause unexpected behavior.\n\nFor changes, start a new run with the updated process.\n\n---\n\n### What task types are available?\n\n| Type | Use Case | Example |\n|------|----------|---------|\n| **Agent** | LLM-powered tasks | Planning, scoring |\n| **Skill** | Claude Code skills | Code analysis |\n| **Node** | JavaScript scripts | Build, test |\n| **Shell** | Commands | git, npm |\n| **Breakpoint** | Human approval | Review gates |\n\n---\n\n### Can I run tasks in parallel?\n\nYes, using `ctx.parallel.all()`:\n\n```javascript\nconst [coverage, lint, security] = await ctx.parallel.all([\n  () => ctx.task(coverageTask, {}),\n  () => ctx.task(lintTask, {}),\n  () => ctx.task(securityTask, {})\n]);\n```\n\nThis significantly speeds up workflows with independent tasks.\n\nSee: [Parallel Execution](../features/parallel-execution.md)\n\n---\n\n## Performance and Optimization\n\n### How long do babysitter runs typically take?\n\n| Workflow Type | Expected Duration |\n|---------------|-------------------|\n| Simple build & test | 30s - 2m |\n| TDD feature | 3m - 10m |\n| Complex refactoring | 10m - 30m |\n| Full application | 30m - 2h |\n\nDuration depends on iteration count, task complexity, and API latency.\n\n---\n\n### How can I speed up my workflows?\n\n1. **Use parallel execution:**\n   ```javascript\n   await ctx.parallel.all([task1, task2, task3]);\n   ```\n\n2. **Set iteration limits:**\n   ```\n   Use babysitter with max 3 iterations\n   ```\n\n3. **Reduce agent task scope:**\n   ```javascript\n   await ctx.task(analyzeTask, { files: ['specific/file.js'] });\n   ```\n\n4. **Lower quality target** for faster convergence\n\n---\n\n### What affects execution time the most?\n\n1. **LLM API latency** - 2-5 seconds per agent call\n2. **Iteration count** - More iterations = longer runtime\n3. **Task complexity** - Large codebases take longer\n4. **Parallel vs sequential** - Parallel can be 4x faster\n\n---\n\n### How do I monitor a running workflow?\n\nAsk Claude for updates:\n\n```\nWhat's the current progress of my babysitter run?\n```\n\n```\nShow me the recent events in my workflow\n```\n\n```\nHow many iterations have completed?\n```\n\n---\n\n## Security and Compliance\n\n### Is my code sent to external services?\n\nAgent tasks use Claude's API, which means:\n- Code context is sent to the API for analysis\n- No data is stored by the API beyond the session\n- Review Anthropic's privacy policy for details\n\nFor sensitive code, consider:\n- Using shell/node tasks instead of agent tasks\n- Running analysis locally\n- Reviewing what context is sent to agents\n\n---\n\n### Are credentials safe in Babysitter workflows?\n\n**Best practices:**\n\n1. **Use environment variables:**\n   ```javascript\n   const apiKey = process.env.API_KEY;\n   ```\n\n2. **Never hardcode credentials**\n\n3. **Add `.a5c/` to `.gitignore`**\n\n4. **Review journal before sharing:**\n   ```bash\n   grep -i \"password\\|secret\\|key\" .a5c/runs/*/journal/*.json\n   ```\n\nSee: [Security Best Practices](../../../README.md#security-best-practices)\n\n---\n\n### Does Babysitter provide audit trails?\n\nYes. The journal system records:\n- Every task execution\n- Every breakpoint approval/rejection\n- Every state change\n- Complete timestamps\n\n**Export audit trail:**\n```bash\njq '.' .a5c/runs/<runId>/journal/*.json > audit-report.json\n```\n\nSee: [Journal System](../features/journal-system.md)\n\n---\n\n### Should I commit the .a5c directory to Git?\n\n**Generally, no.** Add to `.gitignore`:\n```\n.a5c/\n```\n\nReasons:\n- May contain sensitive data\n- Can grow large\n- State cache is derived, not source\n\nHowever, you may choose to commit journals for audit purposes if they don't contain sensitive information.\n\n---\n\n## Troubleshooting FAQ\n\n### Where can I find error logs?\n\nAsk Claude to show you the relevant information:\n\n1. **Journal events:**\n   ```\n   Show me the events in my babysitter run\n   ```\n\n2. **Task outputs:**\n   ```\n   What was the result of the last task in my workflow?\n   ```\n\n3. **Run state:**\n   ```\n   What's the current state of my babysitter run?\n   ```\n\nSee: [Troubleshooting Guide](./troubleshooting.md)\n\n---\n\n### Why does my run say \"waiting\" but nothing happens?\n\n**Likely cause:** A breakpoint is pending approval.\n\n**Solution:**\n1. Check breakpoints UI: http://localhost:3184\n2. Review and approve/reject the breakpoint\n3. Resume if needed\n\n**Verify:**\n```\nAre there any pending breakpoints in my babysitter run?\n```\n\n---\n\n### Why is the breakpoints UI not accessible?\n\nThe breakpoints UI is integrated into the SDK and starts automatically when a workflow reaches a breakpoint.\n\n**Check if accessible:**\n```bash\ncurl http://localhost:3184/health\n```\n\n**If not accessible:**\n1. Ensure a workflow with breakpoints is running\n2. The UI starts automatically when a breakpoint is reached\n3. Check if another process is using port 3184:\n   ```bash\n   lsof -i :3184\n   ```\n\n**If port is in use:**\nKill the conflicting process or configure a different port in your SDK settings.\n\n---\n\n### How do I report a bug?\n\n1. **Gather information:**\n   - OS and version\n   - Node.js version\n   - Claude Code version\n   - Babysitter CLI version\n   - Full error message\n   - Relevant journal excerpts\n\n2. **Search existing issues:**\n   [GitHub Issues](https://github.com/a5c-ai/babysitter/issues)\n\n3. **Create a new issue:**\n   Include all gathered information and steps to reproduce.\n\n---\n\n## Need More Help?\n\n- [Troubleshooting Guide](./troubleshooting.md) - Detailed problem-solution reference\n- [Error Catalog](./error-catalog.md) - Common error messages explained\n- [GitHub Issues](https://github.com/a5c-ai/babysitter/issues) - Report bugs\n- [GitHub Discussions](https://github.com/a5c-ai/babysitter/discussions) - Ask questions\n\n---\n\n**Document Status:** Complete\n**Last Updated:** 2026-01-25\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-reference",
      "to": "page:docs-user-guide-reference-faq",
      "kind": "contains_page"
    }
  ]
}