Babysitter docs

Overview

Babysitter classifies each prompt with Jev, applies a small routing policy you can read, and runs that prompt on the right model.

It adds two new commands and leaves the official ones alone:

bbs-codex   # a routed Codex session
bbs-claude  # a routed Claude Code session

codex       # normal Codex
claude      # normal Claude Code

• It makes a new model decision for every prompt, not once per session.
• It keeps the conversation and avoids wasteful Claude model switches.
• Before each answer it shows a route card: tier, model, effort, reason, and Jev token use.
• The routing rules are plain code in src/policy.js.

YOU ❯ Fix the typo in README
╭─ ROUTE ◆ LUNA
│ Model       gpt-5.6-luna
│ Effort      low
│ Confidence  94%
│ Clarify     3% needs-user-decision probability
│ Why         complexity=0/3
│ Router      Jev · 143 input tokens
╰──────────────────────────────────────────────

╭─ CODEX
Updated README.md.
╰─ ✓ Complete · gpt-5.6-luna · 2.1s

Install

You need

• Node.js 20 or later
• A TypeSafe API key for Jev
• The official Codex CLI and/or Claude Code CLI
• You are signed in to each CLI you plan to use

Install Babysitter

git clone https://github.com/divyansharma001/babysitter.git
cd babysitter
cp .env.example .env
# add your own TYPESAFE_API_KEY to .env
npm install
npm link

npm link adds bbs-codex, bbs-claude, and bbs-update to your terminal. Your .env stays on your machine. Never commit it.

Start a session

bbs-codex
# or
bbs-claude

You can pass the first prompt straight away:

bbs-codex "Find and fix the race condition in the payment worker"
bbs-claude "Find and fix the race condition in the payment worker"

• This still opens the interactive routed session.
• If Claude asks a question or needs approval, answer in the same terminal and the turn continues.
• Type /exit or /quit to leave.

Attach images

Routed Claude and Codex sessions accept images:

/paste
# attaches the image on the macOS clipboard

/image ./screenshots/error.png
# attaches a PNG, JPEG, GIF, or WebP file

• After attaching, type the prompt that uses the image. That prompt is still routed normally.
• /status shows how many images are waiting for the next prompt.
• Clipboard captures are saved in the ignored .babysitter/attachments/ folder.

Why not the native image paste? Provider hooks cannot change the model for a prompt that was already submitted. So Babysitter uses Codex app-server and the Claude Agent SDK, which do allow a model choice on every turn.

How routing works

For every prompt, Jev returns scores for complexity, risk, and breadth, plus the task type and whether an important decision is missing. Babysitter turns those into one of four tiers:

The rules

• Complexity 0 → Luna, 1 → Terra, 2 → Sol.
• High-risk or repository-wide work goes to at least Sol.
• A research label or low confidence alone does not raise the tier.
• Astra needs complexity 3 plus high risk or broad scope. Otherwise complexity 3 stops at Sol.
• If Jev is down, the prompt runs on Terra with medium effort instead of blocking.

These are Babysitter's own rules, not limits set by Jev, OpenAI, or Anthropic. Read or change them in src/policy.js.

Model mappings

Codex

Override with JEV_AUTO_LUNA_MODEL, JEV_AUTO_TERRA_MODEL, JEV_AUTO_SOL_MODEL, or JEV_AUTO_ASTRA_MODEL.

Claude Code

• In routed Claude sessions the terminal shows only Claude names: Haiku, Sonnet, Opus, and Fable.
• bbs-claude runs turns through the official Claude Agent SDK and resumes the same session each turn.
• Effort is only sent to models that support it. Haiku uses Claude Code's default.
• bbs-claude --print still uses Claude Code's normal non-interactive mode.

Override with JEV_AUTO_CLAUDE_LUNA_MODEL, JEV_AUTO_CLAUDE_TERRA_MODEL, JEV_AUTO_CLAUDE_SOL_MODEL, or JEV_AUTO_CLAUDE_ASTRA_MODEL. Only use a model your Claude Code account can access.

Cache-aware Claude routing

Claude's prompt cache belongs to one model. A cache made for Sonnet cannot be reused by Haiku, Opus, or Fable. Changing effort can also reset it.

So switching models after every prompt can cost more than it saves. Babysitter keeps classifying separate from switching: Jev still scores every prompt, and a session policy decides if a switch is worth it.

Default policy

• Upgrades happen right away.
• Downgrades wait until the current model has handled at least 3 turns.
• Once the conversation reaches about 12,000 tokens, automatic downgrades stop.
• Lower effort is never applied inside a warm session, because it would reset the cache.
• A higher-effort upgrade can still happen when the tier needs it.

The route card says when a model was kept for the cache or changed for quality. After each answer, Babysitter shows the usage Claude Code reports:

Babysitter shows the provider's own numbers. It does not estimate savings. Tune the policy with JEV_AUTO_CLAUDE_CACHE_LOCK_TOKENS and JEV_AUTO_CLAUDE_MIN_TURNS_PER_MODEL.

What /compact does

In bbs-claude, /compact starts a fresh session instead of making another model load the whole old transcript:

1. The current model writes a short handoff: goal, decisions, limits, files, work done, test results, open issues, next steps.
2. Babysitter closes the routing context. The original Claude session stays saved.
3. Your next prompt is classified as usual.
4. The chosen model starts a new session with the handoff plus your prompt.

You can say what to keep:

/compact preserve the database migration decisions and remaining test failures

This trades a perfect transcript for a much smaller context. Use /native if you want Claude Code's own compaction.

Resume saved sessions

Babysitter can pick up a saved session and keep routing each new prompt.

# Codex: list saved threads
bbs-codex sessions

# Codex: pick a thread interactively, or resume one by ID
bbs-codex resume
bbs-codex resume <thread-id>

# Claude: continue the latest session in this folder
bbs-claude continue      # same as -c or --continue

# Claude: resume by ID or name
bbs-claude resume <session-id-or-name>   # same as -r or --resume

• You can add a first prompt, for example bbs-claude -r auth-refactor "Finish this PR".
• bbs-claude prints its session ID after each answer so you can resume later.
• The first prompt after resuming may miss the cache if Jev picks a different model than last time.
• bbs-claude -r with no ID, or bbs-claude sessions, opens Claude Code's own session picker. Pass the ID you pick to bbs-claude -r to go back to a routed session.

Slash commands

Babysitter handles the commands that affect routing and context:

• For any other provider command, use /native. The same session is handed over, and routing pauses until you exit.
• Unknown slash commands are never sent to the model as text. Babysitter tells you and points you to /native.

Claude permissions

When Claude needs approval or asks a question, Babysitter pauses the turn, shows the request in the same terminal, takes your answer, and lets Claude continue.

• Routed turns start in Claude Code's acceptEdits mode. Normal file edits are approved automatically.
• Protected commands ask you: allow once, always allow (when Claude offers a safe rule), or deny.
• To deny with a reason, type n plus feedback, like n use the staging database instead.
• bypassPermissions is never offered as a routed mode.

/permissions acceptEdits  # default: edit files, guard bigger actions
/permissions plan         # read-only planning
/permissions dontAsk      # deny anything not already allowed
/permissions auto         # classifier-based approvals, if your account supports it

To change the default, set JEV_AUTO_CLAUDE_PERMISSION_MODE to acceptEdits, plan, dontAsk, or auto. Anything else falls back to acceptEdits.

One-shot Codex

Non-interactive Codex commands are routed too:

bbs-codex exec "Review the current changes for security problems"

Configuration

Copy .env.example to .env. Only one setting is required:

TYPESAFE_API_KEY=your_typesafe_key

Optional settings

The launcher reads the .env in your current folder first, then Babysitter's own .env.

Claude Code sign-in

Babysitter uses your own installed and signed-in Claude Code. It does not proxy or share credentials. Install and sign in with Anthropic's guide:

curl -fsSL https://claude.ai/install.sh | bash
claude auth login

Building a product for others on top of this? Use an Anthropic API key or a supported cloud provider. Subscription sign-in is meant for the unmodified Claude Code app.

Updates

When a routed session starts, Babysitter checks GitHub at most once a day. If your copy is behind main, you see:

↑ Babysitter update available · 3 new commits · run bbs-update

Update when you are ready:

bbs-update

• It runs git pull --ff-only, refreshes npm packages, and asks you to restart the session.
• It refuses to run if your copy has local changes, so it never overwrites your work.
• If the check fails, nothing happens. It never blocks startup.
• There are no silent background updates. Running new code without review is a supply-chain risk.

Limitations

• It only routes sessions started with bbs-codex or bbs-claude. It cannot reach into a session that is already running.
• Every prompt costs one small Jev call. Any saving depends on your work, the models you can use, and whether routing avoids retries.
• Models, effort controls, pricing, and sign-in are set by your Codex and Claude accounts, not by Babysitter.
• Claude Code support needs the official CLI installed and signed in on your machine.

Security

• Never commit .env or share API keys.
• Every person who installs it should use their own TypeSafe key and provider sign-in.
• If a key shows up in a commit, screenshot, issue, or chat, revoke it and make a new one right away.

Before publishing a fork, check:

git check-ignore .env
git status

Development

npm run check
npm test

• Tests use Node's built-in test runner.
• Interactive Claude turns use Anthropic's official Claude Agent SDK.
• Issues and pull requests are welcome. If you change routing, add a regression test and explain the cost and quality trade-off.