# babysit
[日本語版 README](README_JA.md)
Gives local terminal commands an API, so external AI agents (Claude
Code, Codex, …) can query their live output and exit state — the same
way they already query `gcloud` or `kubectl`.
**Your shell** — wrap the command you'd normally run. babysit prints a
session id, then runs the command transparently:
```console
$ babysit -- make local-ci
babysit session ab12: make local-ci
babysit log -s ab12 --tail 200
babysit status -s ab12
Running tests...
✓ test_a
✗ test_b: assertion failed
make: *** [local-ci] Error 1
```
**Your agent, in another terminal** — hand it the session id (`ab12`)
and it can pull state on demand:
```console
$ babysit status -s ab12
session: ab12
cmd: make local-ci
state: exit:2
exit: 2
$ babysit log -s ab12 --tail 3
✓ test_a
✗ test_b: assertion failed
make: *** [local-ci] Error 1
```
babysit does no monitoring of its own — it exposes the wrapped command
as a small CLI/file API; the agent decides when and how to use it.
## Example prompts
Once you've handed your agent the session id, the prompts that work
well are the kind you'd give a coworker keeping an eye on the run:
> Watch session `ab12` with the `babysit` CLI. Tell me when
> `make local-ci` finishes, and if it fails, summarize which tests
> broke and why.
> Keep an eye on session `ab12` using the `babysit` command. Ping me
> only if something goes wrong.
The agent polls `babysit status` / `babysit log` on its own loop —
babysit itself does not push notifications.
## Why
Remote execution platforms (`gcloud`, `kubectl`, CI providers, …) ship
APIs that let an AI agent pull logs and status on demand. Local
execution doesn't: a command running in your terminal is a black box to
any agent that isn't already attached to that TTY, so analyzing an
in-progress run usually means copy-pasting scrollback by hand.
babysit closes that gap. Wrap a command once, and its live output and
exit state become queryable through a small CLI an agent already knows
how to drive — no scraping, no screen sharing, no extra daemon.
## Install
```
Drops a checksum-verified binary at `~/.local/bin/babysit` (override
with `BABYSIT_INSTALL_DIR`, pin a version with `BABYSIT_VERSION=v0.2.4`).
macOS / Linux on x86_64 or aarch64.
Or grab a prebuilt binary directly from
[GitHub Releases](https://github.com/yusukeshib/babysit/releases), or
build from source:
```
cargo install --git https://github.com/yusukeshib/babysit
```
Once installed, `babysit upgrade` self-updates to the latest release.
## Subcommands
```
$ babysit help
Wrap a shell command in a PTY and expose it to external agents via subcommands
Usage: babysit <COMMAND>
Commands:
run Wrap a shell command in a PTY and expose it via the other subcommands
list List all babysit sessions
status Show status of a session
log Show recent output from the wrapped command
restart Restart the wrapped command
kill Terminate the wrapped command
send Send text to the wrapped command's stdin (newline appended)
prune Delete sessions whose wrapped command has finished or whose owner died
upgrade Self-update to the latest version
config Print shell integration (completions)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
Run `babysit help <command>` for flags and aliases. `babysit -- <cmd>`
is a short form for `babysit run <cmd>`.
By default a session gets an auto-generated id; pass `--id <id>` to
`run` to choose your own (e.g. `babysit run --id ci -- make local-ci`).
Ids must be unique and contain only letters, digits, `-`, `_`, `.`.
`-s <id>` is shorthand for `--session <id>` and accepts either the id
or the literal string `latest`. From inside the wrapped command itself
the session is implicit via `$BABYSIT_SESSION_ID`, so the flag can be
omitted.
## Detached mode
`babysit -d -- <cmd>` (or `babysit run -d -- <cmd>`) starts the command
in the background and returns immediately, leaving a detached babysit
worker supervising it:
```console
$ babysit -d --id ci -- make local-ci
babysit session ci: make local-ci
babysit log -s ci --tail 200
babysit status -s ci
$ # prompt returns right away; the agent polls `ci` on its own
```
The worker survives this shell exiting. Its live output isn't mirrored
to your terminal (there's no terminal attached), but it's still
captured to the session log, so `babysit log`/`status`/`send`/`kill`
work exactly as for an attached session.
`status` and `log` work even after babysit has exited — they fall back
to the on-disk state files. `restart`, `kill`, and `send` need the live
control socket and will fail if the babysit process is gone.
`babysit <unknown>` is treated as an unknown subcommand (with a
`did you mean …?` hint), not as a wrap attempt — use `babysit -- <cmd>`
or `babysit run <cmd>` to wrap.
## Shell integration
Add completions to your shell by eval'ing `babysit config`:
```sh
# zsh (~/.zshrc)
eval "$(babysit config zsh)"
# bash (~/.bashrc)
eval "$(babysit config bash)"
```
This completes subcommands and their aliases, per-command flags, and —
most usefully — live session ids for `-s` (read straight from
`~/.babysit/sessions`, plus the `latest` selector). `babysit run`
delegates to your shell's normal command completion.
## Session state on disk
Each session writes to `~/.babysit/sessions/<id>/`:
```
meta.json # static info (cmd, started_at, …)
status.json # live state (running / exited / killed, exit_code)
output.log # raw output from the wrapped command
control.sock # Unix socket the subcommands talk to
```
`babysit list` flags sessions whose owning babysit process has died as
`dead` (e.g. crash, kill -9, reboot before a clean exit could be
recorded). Run `babysit prune` to clear out anything that's no longer
running.
## Build from source
```
cargo build --release
# binary at target/release/babysit
```