Skip to content

Known limits

See also ROADMAP.md for planned work and open questions.

  • Relies on Claude Code internals that are not a public API, all read and written in lib/claude_state.py: transcript custom-title entries in ~/.claude/projects/ (name resolution), ~/.claude/sessions/<pid>.json (status, version, statusUpdatedAt), folder trust in ~/.claude.json, and the error fields of failed requests and claude auth status --json (login detection, verified on 2.1.304). Last run from a clean install on Claude Code 2.1.308, and bosun asks for 2.1.283 or newer. If a Claude Code update changes them, tests/smoke.sh still passes (it uses fixtures), so check with bosun refresh --dry-run and bosun doctor after major updates, and with tests/sandbox.sh mac live claude if you can.
  • Relies on Codex internals that are not a public API either, all in lib/codex_state.py: the session files in ~/.codex/sessions/, [projects] in ~/.codex/config.toml, the JSON of its notify= program and the screens lib/pane_input.py reads. Verified on Codex 0.166.0. After a Codex update, check with bosun doctor, and with tests/sandbox.sh mac live codex if you can.
  • Codex windows do not have everything a Claude Code window has, and the orchestrator needs Claude Code: see the list.
  • Whether Remote Control reconnects after a long sleep without a restart is not verified. Sessions that refresh restarts get a fresh connection.
  • Static AWS credential variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), for example from a local cloud emulator or test credentials, override SSO profiles: tools and SDKs that read the default credentials then fail as if the SSO session had expired, while aws --profile X still works. tmux windows inherit the environment of whatever started the tmux server, which is why bosun runs on its own server (BOSUN_TMUX_SOCKET, default bosun). bosun doctor warns when the session's tmux environment has them, and delegated tasks include the workaround.
  • The Mac must be logged in (asleep is fine; logged out is not), on AC and with the lid open (or an external display).
  • When the Identity Center session itself expires, ensure_aws_sso runs aws sso login, which opens the browser, and posts a macOS notification. It logs in once per [sso-session] (aws sso login --sso-session <name>), which covers every profile of that session; the session's other profiles only check their credentials, and if the login failed they fail at once instead of opening the browser again. If the browser is still signed in to the AWS access portal, the login can complete on its own: on the first real run it finished in 20 seconds with nobody at the Mac. Otherwise it needs a click: a login still waiting after BOSUN_AWS_SSO_ALERT_AFTER seconds (60) alerts you (bosun alert: a notification and, with BOSUN_ALERT_SLACK_USER, a Slack DM) with the time it gives up, so you can approve it at the Mac. The step times out after BOSUN_LOGIN_TIMEOUT seconds, its failure names the command to run later, and the rest of the morning run continues. The login's authorization URL is masked in the log.
  • Orchestrator cost: a morning chores rehearsal took about 4.5 minutes and $1.60 (30 turns). Check-ins only process what is new since the last run. bosun chores --dry-run prints the cost of a run.
  • Every delegated task starts work in a repo window. bosun send --new and --start each start an agent's session, so the orchestrator proposes them for approval rather than running them itself. A session you have open in your own terminal cannot be started in tmux at the same time; --start then fails with "already running", and the orchestrator tells you rather than opening another window.
  • bosun update has no command to go back: a failed update puts everything back by itself, and going back later is by hand, to the version the update came from, and never past a kg forget (Going back). It updates only to the head of the branch the install follows. Its unit and smoke tests run on stand-ins (fake windows and launchd), and its prompts have been tried with the headless Claude of tests/llm/ only: the runs in the macOS VM (a working day updated mid-afternoon, the first update of an older install, the freeze on a year of data, the real agents in their windows) are still to come.