boid

command module
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 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.
Package sigutil hosts the small signal-forwarding loop every harness adapter runs while its child process is alive.
api
apigateway
Package apigateway implements the authenticating reverse proxy that lets a sandboxed job reach arbitrary configured HTTP APIs without ever holding the credential itself — the generalization of internal/gitgateway from git smart HTTP alone to any HTTP API, per docs/plans/api-gateway.md ("汎用 API gateway (認証注入リバースプロキシ) + OAuth2 対応 計画").
Package apigateway implements the authenticating reverse proxy that lets a sandboxed job reach arbitrary configured HTTP APIs without ever holding the credential itself — the generalization of internal/gitgateway from git smart HTTP alone to any HTTP API, per docs/plans/api-gateway.md ("汎用 API gateway (認証注入リバースプロキシ) + OAuth2 対応 計画").
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 every on-first-boot "load or generate and persist" secret file in boid needs (docs/plans/volume-only-daemon.md §論点 d — secret material generated into a fresh, empty named volume at daemon boot).
Package atomicfile provides the write-temp + os.Link publish-if-absent primitive every on-first-boot "load or generate and persist" secret file in boid needs (docs/plans/volume-only-daemon.md §論点 d — secret material generated into a fresh, empty named volume at daemon boot).
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.
Package dockerres is the single source of truth for the names and labels boid puts on the docker resources it creates.
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).
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 (docs/plans/home-workspace-volume.md Phase 4 PR5: `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 (docs/plans/home-workspace-volume.md Phase 4 PR5: `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 (docs/plans/phase6-container-backend.md §PR6, §決定6).
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 (docs/plans/phase6-container-backend.md §PR6, §決定6).
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 introduced by docs/plans/phase6-container-backend.md §PR4 (§決定5: "gateway / broker / dockerproxy はサービス名 (DNS) + TCP (mTLS) で 到達する").
Package mtls provides a small per-daemon self-signed certificate authority used to secure the broker / git-gateway / dockerproxy TCP listeners introduced by docs/plans/phase6-container-backend.md §PR4 (§決定5: "gateway / broker / dockerproxy はサービス名 (DNS) + TCP (mTLS) で 到達する").
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/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 (docs/plans/cli-remote-connection.md, Phase 3 PR1 "profile 基盤").
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 (docs/plans/cli-remote-connection.md, Phase 3 PR1 "profile 基盤").
reap
Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go — docs/plans/phase6-container-backend.md §PR6, §決定6).
Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go — docs/plans/phase6-container-backend.md §PR6, §決定6).
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 (docs/plans/phase6-container-backend.md §PR3).
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 (docs/plans/phase6-container-backend.md §PR3).
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 implements the runtime half of "決定 1 の実装形" in docs/plans/release-onboarding.md: the arbitrary-uid image (build/container/Dockerfile) no longer bakes a fixed `useradd --uid ${BOID_UID}` entry, so a container started as an arbitrary `--user <uid>:0` (the OpenShift-style gid-0 convention) has no matching /etc/passwd row.
Package selfuser implements the runtime half of "決定 1 の実装形" in docs/plans/release-onboarding.md: the arbitrary-uid image (build/container/Dockerfile) no longer bakes a fixed `useradd --uid ${BOID_UID}` entry, so a container started as an arbitrary `--user <uid>:0` (the OpenShift-style gid-0 convention) has no matching /etc/passwd row.
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, per docs/plans/release-onboarding.md 穴2 ("バージョン identity が存在しない").
Package version resolves boid's own version identity, per docs/plans/release-onboarding.md 穴2 ("バージョン identity が存在しない").
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 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