budgie

Budgie exposes Kiro sub-agents as MCP tools, allowing KiRo CLI to orchestrate individual agents through a unified MCP interface. It auto-discovers agents from the local directory ~/.kiro/agents/*.json and filters those with a description prefix sub-agent:. Each recognized agent becomes a separate MCP tool that can be invoked within KiRo CLI sessions. Budgie also provides session-scoped workspaces and multi-turn conversation support via a sessionId with the --resume option. For security, you can run sub-agents in Sandbox mode, where each session executes inside an isolated Docker container. This setup yields filesystem isolation, restricted host credential access, and controlled execution boundaries while preserving conversation history in the session volume.

Prerequisites:

• Go toolchain (Go 1.16+)
• Optional: Docker if you plan to use Sandbox mode

Install and build:

1. Ensure your Go workspace is set up and GOPATH/bin is in your PATH.
2. Build the Budgie binary:

go build -o budgie ./cmd/server

Run the server (in the foreground):

./budgie

Configuration notes:

• Agents should be placed as JSON files under ~/.kiro/agents/ (the server auto-discovers these).
• For Sandbox mode, you’ll need Docker installed and a sandbox image built as described in the README (budgie-sandbox:latest).

Tips and common considerations:

• If you enable Sandbox mode, ensure Docker is running and that you have built the sandbox image first: docker build -t budgie-sandbox:latest .
• The server writes agent responses to the session directory, decoupling from the working directory to simplify session management.
• When using --resume, KiRo CLI stores conversation context by the current working directory path; in container scenarios this maps to /root/.local/share/kiro-cli, so keep session volumes properly mounted.
• The server discovers agents with the description starting with sub-agent:, so ensure your agent JSONs include that tag in the description to be picked up as sub-agents.