Crate bamboo_agent 

Bamboo - A fully self-contained AI agent backend framework

Bamboo provides a complete backend system for AI agents, including:

• Built-in HTTP/HTTPS server (Actix-web)
• Agent execution loop with tool support
• LLM provider integrations (OpenAI, Anthropic, Google Gemini, GitHub Copilot)
• Session management and persistence
• Workflow and slash command systems
• Process management for external tools

Features

• Dual mode: Binary (standalone server) or library (embedded)
• Unified directory: All data in the Bamboo data directory (default ${HOME}/.bamboo)
• Production-ready: Built-in CORS, rate limiting, security headers

Quick Start

Binary Mode

bamboo serve --port 9562 --data-dir "$HOME/.bamboo"

Library Mode

use bamboo_agent::{BambooServer, Config};

#[tokio::main]
async fn main() {
    let config = Config::new();
    let server = BambooServer::new(config);
    server.start().await.unwrap();
}

Re-exports

pub use error::BambooError;

pub use error::Result;

pub use bamboo_server as server;

pub use bamboo_tools as tools;

pub use bamboo_infrastructure as infrastructure;

pub use bamboo_config as config;

Modules

actor_cli

The bamboo actor run CLI: drive an actor from the terminal. bamboo actor … / bamboo -p — drive actors from the terminal.

admin_cli

The bamboo health|status|sessions|session|stop|respond|schedules admin CLI: a thin HTTP client over a running bamboo serve for operators (health probe, session list/inspect/stop/respond, schedule management). The bamboo health | status | sessions | session | stop | respond | schedules admin CLI.

agent

Ergonomic top-level Agent SDK.

broker_agent

The bamboo broker-agent serve worker: connect to a central broker and answer Ask/Task (query/steer) for its mailbox; deployable local/Docker/remote. bamboo broker-agent serve: a long-lived agent that connects to a central message broker and answers Ask/Task for its own mailbox (query/steer modes).

claude_code_executor

ClaudeCodeExecutor: drives the official Claude Code CLI as a ChildExecutor (ExecutorSpec::ClaudeCode), sibling of subagent_worker. ClaudeCodeExecutor: a [ChildExecutor] that drives the official Claude Code CLI (claude) as an external sub-agent engine over its stream-json wire protocol. See docs/claude-code-executor.md for the full protocol reference (spawn flags, NDJSON frame table, permission relay, shutdown) this implementation follows.

codex_app_server_executor

Long-lived codex app-server executor with interactive approval relay. Long-lived Codex app-server executor with Bamboo approval relay.

codex_cli_executor

CodexExecutor: drives codex exec --json as a one-shot ChildExecutor (ExecutorSpec::Codex). CodexExecutor: a [ChildExecutor] that drives the official OpenAI Codex CLI through codex exec --json.

commands

Command and workflow management

core

error

Error types for Bamboo

headless

The bamboo -p headless server mode: full AppState, one-shot, resumable. bamboo -p — a COMPLETE bamboo server, headless: boots the full AppState (root tool surface incl. SubAgent → can spawn actor children), runs the prompt on a root session through the same execute path the HTTP API uses, streams events to the terminal, and exits when the whole tree is finished (parent + children, including suspend/resume coordination).

model_spec

Shared -m/--model CLI-flag grammar (provider:model / bare model id), used by -p -m, actor run|serve -m, and broker-agent spawn --model so all three parse and validate the same string the same way (#246). Shared -m/--model CLI-flag grammar.

plugin_cli

The bamboo plugin install|list|remove|update CLI: a thin HTTP client over a running bamboo serve instance’s /api/v1/plugins routes. The bamboo plugin install|list|remove|update CLI — a thin HTTP client over a running bamboo serve instance’s /api/v1/plugins routes.

project_worktree

Project-scoped Git worktree lifecycle.

read_cli

The bamboo skills list / mcp list read CLI: inspect the configured skill and MCP surfaces offline (straight from <data_dir>), no running server. The bamboo skills list / bamboo mcp list read CLI.

setup_cli

The bamboo init / doctor / config set onboarding CLI: configure a provider + API key and self-diagnose without the web UI (server-less). bamboo init / bamboo doctor / bamboo config set — first-run onboarding.

subagent_worker

The bamboo subagent-worker actor worker (provision via stdin, serve over WS). bamboo subagent-worker — the real actor worker.

Structs

Agent

Stable, ergonomic entry point for agent execution.

AgentBuilder

Ergonomic builder for Agent.

BambooBuilder

Builder pattern for creating BambooServer

BambooServer

Main Bamboo server instance

Config

Runtime configuration facade. Phase-1 sidecar domains are typed modules; the remaining values keep field-access compatibility through Deref.

HookRunner

Engine adapter around the standalone hook dispatcher.

HookToolOutcome

Engine-independent view of a tool execution outcome.

LifecycleHookTestOutput

Raw handler result returned by the settings dry-run endpoint.

ScriptHook

One config-driven lifecycle script executed by an installed system runtime.

ServerConfig

HTTP server configuration

ShellCommandHook

One config-driven lifecycle shell command.

Enums

AgentHookPoint

Lifecycle phases where hooks can be attached.

HookPayload

Point-specific data supplied to an AgentHookPoint callback.

HookResult

Result of running a hook.

LifecycleHookEvent

User-facing lifecycle events that currently map to engine hook seams.

LifecycleScriptRunner

Runtime used to execute a lifecycle script.

Traits

AgentHook

Trait for agent lifecycle hooks.

Type Aliases

ShellHookEvent

Backward-compatible name retained for SDK consumers.