Skip to content

README.md

Latest commit

 

History

History
209 lines (149 loc) · 8.5 KB

README.md

File metadata and controls

209 lines (149 loc) · 8.5 KB

Baudbot

CI Integration License: MIT Last commit Security Policy

Always-on, multiplayer coding agent infrastructure for engineering teams.

Baudbot runs a persistent AI control agent on Linux, connected to Slack, with worker agents that take tasks from request to PR. It works on real repositories with real tools (git, test runners, Docker wrapper, cloud browser automation), keeps persistent memory, and reports progress back in-thread.

Built for teams that want autonomous execution speed without giving up operational control.

⚠️ WARNING: Baudbot is in alpha/early testing. If you use this, prepare to fix things. It might burn tokens. Be careful!

What Baudbot does

  • Shared Slack interface for the whole team. Anyone in allowed channels can hand work to the same agent system.
  • Always-on response and fast handoffs. The control agent stays live, triages work instantly, and spins up task-scoped coding agents.
  • End-to-end coding loop. Branch, code, run tests, open PR, watch CI, push fixes, report status.
  • Linux-native execution. Agents can run the same project commands your engineers run (including guarded container workflows).
  • Persistent team memory. The system learns repo quirks, recurring fixes, and collaboration preferences across restarts.
  • Self-improving operations. Agents can update non-security skills/extensions and propose upstream improvements via PRs.

Team agent, not a personal copilot

Baudbot is designed as shared engineering infrastructure, not a single-user desktop assistant:

  • multiplayer by default (Slack threads, shared todos, multiple sessions)
  • persistent service, not one-shot chat
  • autonomous task execution with humans in review loops
  • admin-managed runtime with deployment + rollback controls

How work flows (example)

  1. A developer asks in Slack: "Fix flaky auth tests in myapp."
  2. Baudbot acknowledges immediately in the same thread.
  3. Control agent creates a todo and spawns a dev-agent in a fresh git worktree.
  4. Dev agent fixes code, runs tests, opens a PR, and monitors CI.
  5. If CI fails, the dev agent iterates and pushes fixes automatically.
  6. Baudbot posts the PR link, CI status, and preview URL back to the original Slack thread.

Requirements

Minimum Recommended
OS Ubuntu 24.04 or Arch Linux Any systemd-based Linux
RAM 4 GB (3 agents) 8 GB (6 agents + builds/tests)
CPU 2 vCPU 4 vCPU
Disk 20 GB 40 GB+ (repos, dependencies, Docker images)

System package dependencies (installed by baudbot install): git, curl, tmux, iptables, docker, gh, jq, sudo.

Quick Start

curl -fsSL https://raw.githubusercontent.com/modem-dev/baudbot/main/bootstrap.sh | bash
baudbot install

baudbot install includes a guided config flow: pick an LLM provider, choose Slack integration mode (managed broker vs custom app), then opt into optional integrations (Kernel/Sentry). Email capabilities are disabled by default and only available in experimental mode (baudbot setup --experimental / install.sh --experimental). If gum is installed, prompts use richer TUI widgets; otherwise installer falls back to standard bash prompts.

After install:

# deploy latest source/config to runtime
sudo baudbot deploy

# start the service
sudo baudbot start

# check health (includes deployed version + broker connection/health status)
sudo baudbot status
sudo baudbot doctor

Upgrade later:

sudo baudbot update

Install with a specific pi version (optional):

BAUDBOT_PI_VERSION=0.52.12 baudbot install

Slack broker registration (after OAuth callback). When SLACK_BROKER_* variables are present, the runtime starts broker pull mode (no inbound callback port required):

sudo baudbot broker register \
  --broker-url https://your-broker.example.com \
  --workspace-id T0123ABCD \
  --registration-token <token-from-dashboard-callback>

Broker pull mode uses long-polling by default (SLACK_BROKER_WAIT_SECONDS=20, max 25; set 0 for immediate short-poll behavior). When broker agent-token auth is enabled server-side, baudbot broker register stores broker token fields in env and broker-mode outbound requests include Authorization: Bearer ... automatically.

Need to rotate/update a key later?

sudo baudbot env set ANTHROPIC_API_KEY
# or: sudo baudbot env set OPENAI_API_KEY sk-... --restart

Want to move source-of-truth off ~/.baudbot/.env later?

sudo baudbot env backend set-command 'your-secret-tool export baudbot-prod'
sudo baudbot env sync --restart

See CONFIGURATION.md for required environment variables and secret setup.

Core agents

Role Purpose
control-agent Owns intake, triage, delegation, Slack comms, and lifecycle supervision
dev-agent Ephemeral coding worker that executes branch → code → PR → CI loops
sentry-agent On-demand incident investigator for Sentry alerts and triage support

Architecture at a glance

Slack
   ↓
control-agent (always-on)
   ├─ todo + routing
   ├─ dev-agent(s) in isolated worktrees
   └─ sentry-agent for incident triage
        ↓
git commits, PRs, CI feedback, thread updates

Baudbot uses source/runtime separation: admin-managed source and immutable releases are deployed into an unprivileged agent runtime.

Security as an enabling layer

Baudbot is built for utility and containment:

  • isolated baudbot_agent Unix user (no general sudo)
  • per-UID firewall controls + process isolation
  • source/runtime separation with deploy manifests
  • read-only protection for security-critical files
  • session log hygiene (startup redaction + retention pruning)
  • layered tool and shell guardrails (policy/guidance layer, not sole containment)

See SECURITY.md for full threat model, trust boundaries, and known risks. In particular: tool/shell guards are defense-in-depth policy layers; hard containment comes from OS/runtime boundaries.

Documentation

Shell script architecture

Operational shell scripts under bin/ follow a shared module pattern to keep command entrypoints thin and behavior consistent:

  • shared safety/logging/error helpers in bin/lib/shell-common.sh
  • release lifecycle helpers in bin/lib/release-common.sh
  • deploy-specific helpers in bin/lib/deploy-common.sh
  • doctor output/counter helpers in bin/lib/doctor-common.sh
  • JSON parsing helpers in bin/lib/json-common.sh

Conventions:

  • source shared modules near the top of each script
  • call bb_enable_strict_mode (strict bash mode)
  • prefer shared bb_log/bb_die helpers instead of ad-hoc logging/error code
  • keep heavy logic in bin/lib/* and keep CLI-facing scripts focused on orchestration

Tests

# All tests (unified Vitest runner)
npm test

# JS/TS suites only
npm run test:js

# Shell/security script suites only
npm run test:shell

# JS/TS coverage
npm run test:coverage

# Lint (Biome + ShellCheck) + typecheck
npm run lint && npm run typecheck

# ShellCheck only
npm run lint:shell

License

MIT