bambu-ai

The CLI glue between your Bambu Lab A1 / A1 mini and your AI coding agent.

Any coding agent with shell access (Claude Code, Cursor, Codex, GPT-CLI, …) can now drive your printer. Status, control, AI failure detection, notifications — all via composable subcommands designed to be machine-parseable, self-documenting, and 100% LAN-only.

---

What this is

A single Python package shipping three console scripts (bambu, bambu-watch, bambu-poll) plus a vision subsystem. It talks directly to the printer's local MQTT broker (port 8883, TLS) plus FTP and the chamber camera — no Bambu cloud, no Home Assistant, no Bambu account, no third-party service except optional ntfy.sh for phone push.

Written to be readable by both humans and AI agents. See AGENTS.md — that's the contributor handbook for any LLM-driven agent that clones this repo with a task.

Why this exists

3D printers and AI coding agents live in parallel universes. The printer has its own app, its own cloud, its own dashboards. Your agent (Claude Code, Cursor, whatever) sits in your terminal and can run any command. Until now there's been no clean bridge.

bambu-ai is that bridge. Once installed, anytime you want your agent to:

• check on a print mid-conversation
• pause / cancel / resume from chat
• watch the chamber camera with a vision model and auto-pause spaghetti
• ping your phone when a print finishes or fails
• design a part → slice → upload → print → monitor end-to-end

…it just calls the right bambu subcommand. The CLI is the API.

Quick start (5 commands)

git clone https://github.com/abe238/bambu-ai && cd bambu-ai
make setup                         # venv + package + dev deps + pre-commit hook
cp .env.example .env && $EDITOR .env   # fill in your printer's IP/code/serial + ntfy topic
make test                          # 51 unit tests pass without a real printer
bambu status                       # live snapshot from your printer

Required Python: 3.10+ (3.14 recommended). macOS or Linux.

Where to find each .env value

Key	Where to find it
IP	Printer screen → Settings ⚙ → WLAN → tap connected network
ACCESS_CODE	Same WLAN screen, under "Access Code"
SERIAL	Settings → Device → Device Info (or the sticker on the printer)
NTFY_TOPIC	Pick a long, hard-to-guess random string (why)
ANTHROPIC_API_KEY	Optional — for vision. See vision auth below.

What you can do today

# State & control
bambu status                              # one-shot: state, temps, layer, ETA
bambu pause | resume | cancel --yes       # destructive commands need --yes
bambu home                                # home the print head
bambu light on | off                      # chamber LED
bambu doctor                              # firmware + library + known-bug report

# AI failure detection
bambu vision watch                        # long-running daemon, adaptive sampling, auto-pause
bambu vision classify <frame.jpg> [--json]   # one-off (machine-parseable with --json)

# Camera capture + timelapse
bambu snap <out.jpg>                      # one frame from the chamber camera
bambu stream --out-dir ./tl --interval 30 # periodic capture
bambu timelapse stitch ./tl --out out.mp4 # ffmpeg-stitch into MP4

# Upload + start + queue
bambu print <file.3mf>                    # upload via FTP and start
bambu queue add <file.3mf>                # add to persistent queue
bambu queue list | clear | start          # daemon dispatches on IDLE/FINISH

# Scheduling, quiet hours, auto-off
bambu schedule <name> --at 07:00          # start an existing print at HH:MM
bambu quiet --from 23:00 --to 09:00       # cap aux fan during the window
bambu auto-off --webhook URL [--exec CMD] # fire hooks on FINISH/FAILED

# Calibration tracking
bambu cal log <spool> --pa 0.042 --flow 0.98 --filament "PLA Basic"
bambu cal list | show <spool> | remove <spool> --yes

# Notifications + live tail
bambu-watch [--heartbeat] [--notify-bed-temp C] [--notify-nozzle-temp C]
bambu-poll                                # live MQTT state tail

Every subcommand has --help. All long-running daemons are Ctrl-C-able. See docs/ for per-feature deep dives.

What this looks like with an agent

Open Claude Code (or any shell-running agent) in this repo with .env populated, and conversations like these just work:

You: "How's my print doing?" Agent runs bambu status, reads the percentage and ETA, replies.

You: "Watch the print and pause it if it looks like spaghetti." Agent runs bambu vision watch --dry-run to confirm setup, then bambu vision watch in the background. Notifies you on failure detection.

You: "Capture a frame and tell me what you see." Agent runs bambu vision classify <frame> --json, parses the JSON, summarizes.

You: "When the print is done, turn off the lights." Agent starts bambu-watch to detect FINISH, then bambu light off.

The CLI is intentionally tiny, predictable, and self-documenting via bambu --help / bambu <cmd> --help. Easy for an LLM to discover, compose, and reason about.

Vision credentials

The vision watcher needs Anthropic credentials. Tried in this order:

1. ANTHROPIC_API_KEY in .env (works everywhere)
2. ANTHROPIC_AUTH_TOKEN in .env (an OAuth bearer)
3. macOS only: Claude Code's stored OAuth token, read from the keychain on demand. If you've authenticated claude on this Mac, nothing else to set up.

The watcher logs which source it used on startup. Keychain tokens are read on demand via the security command, never written to disk, never logged.

⚠️ Using Claude Code's OAuth shares quota with your normal Claude Code sessions. For unattended long-running prints, a separate API key is the right call. See docs/vision.md.

How it works

┌──────────┐  TLS+MQTT   ┌──────────────┐                 ┌────────┐
│ printer  │ ◀────────▶  │  bambu-watch │ ───ntfy.sh────▶ │  phone │
└──────────┘             └──────────────┘                 └────────┘
     ▲                          ▲
     │ TLS+MQTT (one-shot)      │  vision verdicts (Claude API)
     │                          │
┌──────────┐                  ┌────────────┐
│  bambu   │                  │ bambu      │
│  (CLI)   │                  │ vision     │
└──────────┘                  │ watch      │
     ▲                        └────────────┘
     │
┌────────────────────┐
│  your AI agent     │
│  (Claude Code,     │
│  Cursor, Codex…)   │
└────────────────────┘

The A1 mini accepts at least 3 simultaneous MQTT clients on port 8883 (verified: Bambu Studio + two pollers, all clean). bambu-watch and bambu vision watch hold persistent connections; bambu <cmd> opens fire-and-forget per command and doesn't compete.

Repo layout

src/bambu_ai/   # the package
  ├─ cli.py            # bambu subcommands (status/pause/resume/cancel/home/light/vision)
  ├─ watcher.py        # bambu-watch: ntfy daemon
  ├─ poller.py         # bambu-poll: live state tail
  ├─ config.py         # shared .env loader
  ├─ notify.py         # ntfy.sh helper
  └─ vision/           # AI failure detection (issue #20)
       ├─ types.py     # Verdict + FailureClass
       ├─ base.py      # VisionProvider ABC
       ├─ claude.py    # cloud provider
       ├─ mock.py      # for tests + --dry-run
       ├─ sampler.py   # adaptive sampling policy
       ├─ watcher.py   # main loop
       ├─ credentials.py  # api_key / auth_token / keychain resolver
       └─ cli.py       # bambu vision subcommands

tests/          # pytest, mirrors src/bambu_ai/
docs/           # long-form per-feature docs
examples/       # copy-pasteable scripts
completions/    # zsh + bash tab completion
install.sh      # idempotent installer
Makefile        # setup / test / lint / format / secrets / check / demo / clean
pyproject.toml  # package + entry points + lint/test config
AGENTS.md       # contributor handbook for AI agents (and humans)
SECURITY.md     # secret-handling policy
LICENSE         # Apache-2.0
NOTICE          # third-party attributions

For agents picking this up

If you're an AI coding agent and the user pointed you at this repo with a task, read AGENTS.md first. It explains:

• Setup in 5 commands (works without a real printer — unit tests mock it)
• The three test tiers (unit / integration / real-printer) and when each runs
• How to add a new CLI subcommand or VisionProvider
• Where the active roadmap lives (GitHub Issues, tier-prefixed in titles)
• The strict no-secrets-in-commits rule + how the pre-commit hook enforces it
• Don'ts: no Bambu cloud, no Claude co-author trailers, no --no-verify

Roadmap

The original Tier 1–3 roadmap (distilled from a 30-day audit of r/BambuLab, the Bambu forum, ha-bambulab, and HN) is fully shipped — see closed issues. Follow-ups land as new issues; the high-leverage next steps are:

• Local-first vision provider (MLX-VLM) — slot into the existing VisionProvider interface so the same bambu vision watch runs offline.
• Auto-running calibration (parsing K from the printer's calibration print output, then bambu cal log-ing it without manual entry).
• MCP server wrapping these commands so Claude Desktop / ChatGPT can drive the printer alongside Claude Code.

Security

See SECURITY.md. TL;DR:

• Never commit .env. Gitignored; pre-commit blocks the common leak shapes.
• Access Code = password. Don't share screenshots, logs, or pastes that contain it.
• NTFY_TOPIC is a shared secret. ntfy.sh is unauthenticated by default; anyone who knows the topic can read and post. Use a long random string.

License

Apache 2.0. See NOTICE for third-party attributions.

Not affiliated with Bambu Lab. "Bambu Lab" and "A1 mini" are trademarks of Shenzhen Tuozhu Technology Co., Ltd.