boid

command module
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 4 Imported by: 0

README

boid

A personal AI orchestrator (Linux only). Built to keep the human from becoming the bottleneck when several AI coding agents run in parallel. Agents are given room to make progress autonomously; a sandbox with a configurable write scope keeps them from doing damage; and every in-flight task is visible at a glance through a Web UI.

日本語 README

Features

  • Give agents room to run on their own. The task lifecycle — request → execute → verify → fix → done — and the data captured at each step are predefined, so you don't have to re-feed context on every revision cycle. Hand the agent your local Claude Code, Codex, git, gh, editors, and language toolchains; it uses the tools you already have.
  • Autonomy and safety, reconciled by the sandbox. Agents read your real directories directly, but writes are confined to a scope you choose (typically a git worktree). A runaway agent can't reach your home directory or other projects. Give each task its own worktree and several requests run on separate branches in separate directories without colliding.
  • See every task at a glance. Every task lives in a single list with its current state, viewable from CLI or Web UI. Expose the Web UI through Cloudflare Tunnel and you can check or steer progress from your phone.
  • Stays on your own machine. go install, then boid start. No config file, no server provisioning, no signup. Unlike cloud-side sandboxes, the agent can act on the real environment you actually work in.
  • Swappable extension packages. Pick which AI agent (Claude Code; Codex and opencode are also supported in experimental form), which CI integration, which PR / auto-merge flow — the building blocks live in separate packages such as boid-kits.

Install

go install github.com/novshi-tech/boid@latest

Quickstart

boid start              # start the daemon (auto-detached)
boid task list          # list tasks
boid task show <id>     # inspect a task
boid stop               # stop the daemon

A guided walkthrough lives in docs/en/getting-started/01-install.md.

Shell completion

cobra's built-in boid completion generates shell completion scripts. In addition to subcommand and flag completion, when the daemon is running it dynamically completes project refs (boid project show|remove|behaviors <ref>, boid exec -p <ref>) and boid exec command names.

# bash (current shell)
source <(boid completion bash)

# bash (system-wide, sudo required)
boid completion bash | sudo tee /etc/bash_completion.d/boid >/dev/null

# zsh
boid completion zsh > "${fpath[1]}/_boid"

# fish
boid completion fish | source

Documentation

The full doc index is at docs/en/. Japanese docs are at docs/ja/.

Status

Currently being evaluated within the scope the author can directly support. A wider public release will follow.

License

MIT.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
build
container
Package container also embeds compose.yml and Dockerfile (this file) so `boid`'s host-mode orchestration (cmd/host.go — now the unconditional default, docs/plans/release-onboarding.md 決定2/PR5; originally the PR-3 Option 4 host-mode redesign, docs/plans/volume-only-daemon.md §論点c) can extract them to a stable filesystem path and locate them even when invoked as a standalone-installed binary with no adjacent boid repo checkout (round-2 codex review Major 1: "host mode cannot autostart from an installed standalone CLI").
Package container also embeds compose.yml and Dockerfile (this file) so `boid`'s host-mode orchestration (cmd/host.go — now the unconditional default, docs/plans/release-onboarding.md 決定2/PR5; originally the PR-3 Option 4 host-mode redesign, docs/plans/volume-only-daemon.md §論点c) can extract them to a stable filesystem path and locate them even when invoked as a standalone-installed binary with no adjacent boid repo checkout (round-2 codex review Major 1: "host mode cannot autostart from an installed standalone CLI").
e2e
cmd/boid-e2e command
upstream
Package upstream provides a fixture git-over-HTTP server for boid's e2e tests.
Package upstream provides a fixture git-over-HTTP server for boid's e2e tests.
internal
adapters
Package adapters defines the HarnessAdapter interface and shared types for harness-specific agent protocol implementations.
Package adapters defines the HarnessAdapter interface and shared types for harness-specific agent protocol implementations.
adapters/claude
Package claude implements adapters.HarnessAdapter for Claude Code.
Package claude implements adapters.HarnessAdapter for Claude Code.
adapters/codex
Package codex implements adapters.HarnessAdapter for the Codex CLI.
Package codex implements adapters.HarnessAdapter for the Codex CLI.
adapters/opencode
Package opencode implements adapters.HarnessAdapter for the opencode CLI.
Package opencode implements adapters.HarnessAdapter for the opencode CLI.
adapters/registry
Package registry maps sandbox.HarnessType to a HarnessAdapter implementation.
Package registry maps sandbox.HarnessType to a HarnessAdapter implementation.
adapters/shell
Package shell implements adapters.HarnessAdapter for plain shell / exec jobs that do not embed an agent harness.
Package shell implements adapters.HarnessAdapter for plain shell / exec jobs that do not embed an agent harness.
adapters/sigutil
Package sigutil hosts the small signal-forwarding loop every harness adapter runs while its child process is alive, so the claude / codex / opencode / shell adapters do not all carry their own copy of the same select-loop boilerplate.
Package sigutil hosts the small signal-forwarding loop every harness adapter runs while its child process is alive, so the claude / codex / opencode / shell adapters do not all carry their own copy of the same select-loop boilerplate.
api
apigateway
Package apigateway implements the authenticating reverse proxy that lets a sandboxed job reach configured HTTP APIs without ever holding the credential itself.
Package apigateway implements the authenticating reverse proxy that lets a sandboxed job reach configured HTTP APIs without ever holding the credential itself.
apiwire
Package apiwire holds the daemon↔client wire contract: the request and response shapes both internal/api (server side) and internal/client + cmd (client side) encode and decode, plus the few validators that DEFINE a field's canonical form (NormalizePublicURL).
Package apiwire holds the daemon↔client wire contract: the request and response shapes both internal/api (server side) and internal/client + cmd (client side) encode and decode, plus the few validators that DEFINE a field's canonical form (NormalizePublicURL).
atomicfile
Package atomicfile provides the write-temp + os.Link publish-if-absent primitive used by boid's "load or generate and persist" secret files, so two daemon instances racing to boot against the same fresh data dir can never clobber each other's write (see docs/plans/volume-only-daemon.md §論点 d).
Package atomicfile provides the write-temp + os.Link publish-if-absent primitive used by boid's "load or generate and persist" secret files, so two daemon instances racing to boot against the same fresh data dir can never clobber each other's write (see docs/plans/volume-only-daemon.md §論点 d).
daemon
Package daemon provides helpers for daemonizing the boid server process.
Package daemon provides helpers for daemonizing the boid server process.
db
dockerres
Package dockerres is the single source of truth for the names and labels boid puts on the docker resources it creates, shared by internal/reap, internal/dispatcher, and internal/sandbox/dockerproxy so their naming and containment rules cannot drift apart (see docs/plans/workspace-home-volume-persistence.md 論点 a).
Package dockerres is the single source of truth for the names and labels boid puts on the docker resources it creates, shared by internal/reap, internal/dispatcher, and internal/sandbox/dockerproxy so their naming and containment rules cannot drift apart (see docs/plans/workspace-home-volume-persistence.md 論点 a).
gitgateway
Package gitgateway implements the authenticating reverse proxy that sits between a sandbox's credential-less git and the real upstream forge (GitHub / Bitbucket).
Package gitgateway implements the authenticating reverse proxy that sits between a sandbox's credential-less git and the real upstream forge (GitHub / Bitbucket).
gwtransport
Package gwtransport builds the outbound (gateway → upstream) http.Transport shared by internal/gitgateway and internal/apigateway.
Package gwtransport builds the outbound (gateway → upstream) http.Transport shared by internal/gitgateway and internal/apigateway.
humanize
Package humanize renders byte counts as human-readable strings and sums a directory tree's apparent (logical) size, for boid's workspace-home size reporting (`boid workspace show`, `boid gc`'s workspace_homes listing, and the confirmation prompt on `boid workspace remove`).
Package humanize renders byte counts as human-readable strings and sums a directory tree's apparent (logical) size, for boid's workspace-home size reporting (`boid workspace show`, `boid gc`'s workspace_homes listing, and the confirmation prompt on `boid workspace remove`).
install
Package install provides the daemon's install identity: a plain UUID persisted once per boid installation and stamped as the boid.install_id label on every container/network/volume the daemon creates.
Package install provides the daemon's install identity: a plain UUID persisted once per boid installation and stamped as the boid.install_id label on every container/network/volume the daemon creates.
integrationpack
Package integrationpack implements the Integration Pack manifest schema, loader, and "脱糖" (desugaring) that turns a services.<name>.uses reference into the apigateway.ServiceConfig the API gateway already understands.
Package integrationpack implements the Integration Pack manifest schema, loader, and "脱糖" (desugaring) that turns a services.<name>.uses reference into the apigateway.ServiceConfig the API gateway already understands.
logrotate
Package logrotate provides a size-based rotating log writer.
Package logrotate provides a size-based rotating log writer.
mtls
Package mtls provides a small per-daemon self-signed certificate authority used to secure the broker / git-gateway / dockerproxy TCP listeners (docs/plans/phase6-container-backend.md §決定5).
Package mtls provides a small per-daemon self-signed certificate authority used to secure the broker / git-gateway / dockerproxy TCP listeners (docs/plans/phase6-container-backend.md §決定5).
notify
Package notify exec's a user-configured command for agent-driven notifications.
Package notify exec's a user-configured command for agent-driven notifications.
orchestrator
Package orchestrator's state-machine layer is split into TWO machines — NewExecutionMachine and NewCardMachine (machine_execution.go / machine_card.go) — because the pending/executing/awaiting statuses and the parked/working/done/dropped card statuses share only their terminal statuses and never reach each other.
Package orchestrator's state-machine layer is split into TWO machines — NewExecutionMachine and NewCardMachine (machine_execution.go / machine_card.go) — because the pending/executing/awaiting statuses and the parked/working/done/dropped card statuses share only their terminal statuses and never reach each other.
orchestrator/refname
Package refname generates random "adjective_noun" style names for task refs.
Package refname generates random "adjective_noun" style names for task refs.
profiles
Package profiles resolves which boid daemon a CLI invocation should talk to: the local UNIX socket (today's sole, and still default, behavior) or a remote daemon over HTTPS + Bearer auth, per a named "profile" in ~/.config/boid/config.yaml.
Package profiles resolves which boid daemon a CLI invocation should talk to: the local UNIX socket (today's sole, and still default, behavior) or a remote daemon over HTTPS + Bearer auth, per a named "profile" in ~/.config/boid/config.yaml.
reap
Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go): it talks to the docker engine directly, never through boid's own daemon API, so it can stop/destroy every sibling job container an install created even when the daemon itself is down or unreachable.
Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go): it talks to the docker engine directly, never through boid's own daemon API, so it can stop/destroy every sibling job container an install created even when the daemon itself is down or unreachable.
sandbox/backend
Package backend defines the SandboxBackend/SandboxSession seam that separates "how a sandboxed agent process is launched and attached to" from the dispatcher's job orchestration.
Package backend defines the SandboxBackend/SandboxSession seam that separates "how a sandboxed agent process is launched and attached to" from the dispatcher's job orchestration.
sandbox/brokerclient
Package brokerclient holds the low-level transport for talking to the boid broker over its UNIX socket or its TCP(mTLS) listener, plus a self-contained JobDone helper.
Package brokerclient holds the low-level transport for talking to the boid broker over its UNIX socket or its TCP(mTLS) listener, plus a self-contained JobDone helper.
sandbox/realization
Package realization translates a backend-neutral sandbox.Spec into the intermediate representation a container backend needs to build a `docker create` call: volumes/binds, tmpfs mounts, environment, working directory and argv.
Package realization translates a backend-neutral sandbox.Spec into the intermediate representation a container backend needs to build a `docker create` call: volumes/binds, tmpfs mounts, environment, working directory and argv.
sandbox/runner
Package runner is the container-backend sandbox runner entry point (`boid runner-container`, runner_container_linux.go's RunContainer).
Package runner is the container-backend sandbox runner entry point (`boid runner-container`, runner_container_linux.go's RunContainer).
selfuser
Package selfuser registers a synthetic /etc/passwd entry for the container's runtime uid: the arbitrary-uid image no longer bakes a fixed `useradd` entry, so a container started as an arbitrary `--user <uid>:0` (the OpenShift-style gid-0 convention) has no matching /etc/passwd row, which breaks any tooling that does an os/user-style lookup (ssh, some git credential helpers, `id`, coreutils' `whoami`).
Package selfuser registers a synthetic /etc/passwd entry for the container's runtime uid: the arbitrary-uid image no longer bakes a fixed `useradd` entry, so a container started as an arbitrary `--user <uid>:0` (the OpenShift-style gid-0 convention) has no matching /etc/passwd row, which breaks any tooling that does an os/user-style lookup (ssh, some git credential helpers, `id`, coreutils' `whoami`).
terminaltitle
Package terminaltitle extracts window titles from a streaming UTF-8 PTY.
Package terminaltitle extracts window titles from a streaming UTF-8 PTY.
timeline
Package timeline builds the unified task-detail timeline consumed by both the TUI and the Web UI.
Package timeline builds the unified task-detail timeline consumed by both the TUI and the Web UI.
version
Package version resolves boid's own version identity.
Package version resolves boid's own version identity.
vtsnapshot
Package vtsnapshot resolves a recorded PTY byte stream into the screen it would have painted, so a client attaching mid-session can be handed the current screen instead of the whole recording.
Package vtsnapshot resolves a recorded PTY byte stream into the screen it would have painted, so a client attaching mid-session can be handed the current screen instead of the whole recording.
yamlutil
Package yamlutil holds small, dependency-free helpers shared between packages that decode agent/hook-authored YAML into Go values destined for json.Marshal.
Package yamlutil holds small, dependency-free helpers shared between packages that decode agent/hook-authored YAML into Go values destined for json.Marshal.
Package packconformance implements the Pack contract v1 conformance test framework: a Pack author, official or custom, can run the same machine-checkable requirements against their Pack directory that CI runs against the official Packs.
Package packconformance implements the Pack contract v1 conformance test framework: a Pack author, official or custom, can run the same machine-checkable requirements against their Pack directory that CI runs against the official Packs.
Package scripts embeds deploy-container.sh (this directory's own deployment script) so `boid`'s host-mode orchestration (cmd/host.go — now the unconditional default, docs/plans/release-onboarding.md 決定2/PR5; originally the PR-3 Option 4 host-mode redesign of #835, docs/plans/volume-only-daemon.md §論点c) can extract and invoke it even when running as a standalone-installed binary with no adjacent boid repo checkout (round-2 codex review Major 1: "host mode cannot autostart from an installed standalone CLI").
Package scripts embeds deploy-container.sh (this directory's own deployment script) so `boid`'s host-mode orchestration (cmd/host.go — now the unconditional default, docs/plans/release-onboarding.md 決定2/PR5; originally the PR-3 Option 4 host-mode redesign of #835, docs/plans/volume-only-daemon.md §論点c) can extract and invoke it even when running as a standalone-installed binary with no adjacent boid repo checkout (round-2 codex review Major 1: "host mode cannot autostart from an installed standalone CLI").
homeenv
Package homeenv isolates a test binary from the real developer machine's persistent boid state — $HOME, the XDG base directories, and the docker engine — and lets a test assert that the isolation is actually in place.
Package homeenv isolates a test binary from the real developer machine's persistent boid state — $HOME, the XDG base directories, and the docker engine — and lets a test assert that the isolation is actually in place.
web
templates
templ: version: v0.3.1001
templ: version: v0.3.1001
templates/components
templ: version: v0.3.1001
templ: version: v0.3.1001

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL