bubbaloop: Instructions file for Claude Code

🦐 Bubbaloop

Physical AI orchestration built on Zenoh. Single binary: CLI + daemon + MCP server.

Living Documents (update these as architecture evolves)

• ARCHITECTURE.md — Layer model, node contract, security, open-core boundary
• ROADMAP.md — Implementation phases (YAML skills, agent, SQLite memory, scheduling)
• CONTRIBUTING.md — Agentic workflows, agent tiers, validation, two-critic loop
• docs/concepts/dataflow.md — Provenance envelope, manifest queryable, bubbaloop dataflow CLI + MCP tool (how the SDK answers "what's wired, what's flowing")

Structure

crates/bubbaloop/           # Main binary (CLI + daemon + MCP server)
crates/bubbaloop-node/      # Node SDK (standalone, NOT in workspace — batteries-included framework)
crates/bubbaloop-node-build/ # Build helper for nodes (wraps prost-build, standalone)
crates/bubbaloop-schemas/   # Protobuf schemas (standalone, NOT in workspace — never add to workspace)
dashboard/                  # React + Vite + TypeScript

Key source files in crates/bubbaloop/src/:

• cli/login.rs — login/logout/status + has_claude_credentials() (env var → OAuth → key file)
• cli/agent_setup.rs — bubbaloop agent setup: interactive provider/model/identity wizard (no daemon needed)
• cli/agent_client.rs — Thin Zenoh CLI client for agent chat/list (pub/sub, no LLM)
• agent/mod.rs — Agent core: EventSink trait, run_agent_turn(), AgentTurnInput (soul_path triggers onboarding)
• agent/gateway.rs — Zenoh gateway wire format (AgentMessage, AgentEvent, topic builders)
• agent/runtime.rs — Multi-agent runtime: AgentsConfig, AgentRuntime, ZenohSink, agent_loop; agent_directory() (pub)
• agent/prompt.rs — System prompt builder; build_system_prompt_with_soul_path() injects onboarding prompt for new agents
• agent/soul.rs — Soul struct, first-run onboarding, notify hot-reload (~/.bubbaloop/soul/)
• agent/provider/mod.rs — ModelProvider trait, Message, ContentBlock (incl. Image), ToolDefinition, StreamEvent
• agent/provider/gemini.rs — Gemini API client (recommended default — free tier, vision-capable)
• agent/provider/claude.rs — Claude API client with dual auth (API key + OAuth bearer token)
• agent/provider/ollama.rs — Ollama local LLM client with tool calling (/api/chat)
• agent/camera.rs — grab_frame implementation: Zenoh query for one JPEG frame + JSON metadata attachment, emits ContentBlock::Image
• agent/gateway.rs — Zenoh + HTTP+SSE agent gateway; per-agent cancel topic bubbaloop/global/{machine_id}/agent/{agent_id}/cancel
• agent/memory/ — 4-tier: world state (live SQLite) + short-term (RAM) + episodic (NDJSON) + semantic (SQLite)
• agent/heartbeat.rs — Adaptive heartbeat: arousal + decay + state collection
• agent/dispatch.rs — Internal tool dispatch (47 public MCP tools + ~43 agent-internal tools incl. grab_frame, telemetry, beliefs, constraints, missions)
• cli/node/mod.rs — node CRUD, validation, list/add/remove
• cli/node/install.rs — install, precompiled binary download, GitHub clone
• cli/node/lifecycle.rs — start, stop, restart, logs
• cli/node/build.rs — build node
• daemon/mod.rs — skill runtime: registry + lifecycle + health + MCP + telemetry watchdog
• daemon/telemetry/ — Resource watchdog: sampler (sysinfo), circuit breaker, SQLite storage, hot-reload config
• daemon/node_manager.rs (57KB) — node lifecycle, build queue, health
• daemon/systemd.rs (38KB) — D-Bus/zbus integration
• daemon/registry.rs — ~/.bubbaloop/nodes.json management
• registry.rs — marketplace fetch/parse/cache, find_curl()
• marketplace.rs — shared precompiled binary download logic (used by CLI and MCP)
• mcp/mod.rs — MCP tools, BubbaLoopMcpServer, ServerHandler impl
• mcp/platform.rs — PlatformOperations trait, DaemonPlatform, MockPlatform