Unified transports
USB adb, Wi-Fi adb, on-board sshd, UART serial — and a hybrid router that auto-picks the right one. One command, five ways onto the device.
See the methods tableLet LLM agents debug real Android devices. 让 LLM Agent 在线调试真实安卓设备。
One CLI, one MCP server, one Web API — across USB adb, Wi-Fi adb, on-board sshd, and UART serial. Structured outputs, built-in permissions, workspace artifacts. Ready for Claude Code, Cursor, and any agent that speaks tools. 一套 CLI、一个 MCP server、一个 Web API —— 打通 USB adb / Wi-Fi adb / 板子 sshd / UART 串口。结构化输出、内置权限系统、产物落盘。开箱适配 Claude Code、Cursor 以及任何懂 tool call 的 agent。
A debugging suite, not just a wrapper.
Traditional adb and ssh were built for humans. alb is built for agents — every command returns structured data, every risky action passes a permission gate, every long log flows to a per-device workspace.
LLM-first API
Every response is {ok, data, error, artifacts}. Five-category error codes. Self-describing tool specs for MCP. Long logs flow to workspace, not context.
Three ways to plug in
Use it from the terminal (alb), from any MCP-capable agent (Claude Code, Cursor), or from a Web API (FastAPI, WebSocket streaming). Same business layer underneath.
Permission gate
Dangerous commands (rm -rf, reboot bootloader) are blocked by default, overridable by allow / ask / deny policy.
Workspace artifacts
logcat, ANR traces, bugreports, perf dumps — all land under workspace/devices/<serial>/…, organized and searchable.
Streaming agent loop
ReAct-lite loop with tool calls, max-turn circuit breaker, token streaming over WebSocket, JSONL session persistence.
Four ways onto the device.
Every physical link has a failure mode. alb supports four today (A · B · C · G) and reserves three (D · E · F) for later. Pick by scenario, or let hybrid pick for you.
| Method | Channel | Boot log | U-Boot | No network | Kernel panic | Best for |
|---|---|---|---|---|---|---|
| A · adb USB | adb protocol | — | — | ✓ | — | Baseline; works in recovery |
| B · adb Wi-Fi | TCP | — | — | — | — | Cable-free, multi-device CI |
| C · on-board sshd | SSH | — | — | — | — | rsync / long sessions / tmux |
| G · UART serial | serial (TCP bridge on Windows) | ✓ | ✓ | ✓ | ✓ | Last resort · bring-up · panic |
D USB-tethered IP · E scrcpy mirroring · F frp public relay — reserved for later milestones.
Three integration tiers, one business layer.
MCP for chat-based agents. CLI for humans and shell scripts. Web API (POST + WebSocket) for the browser UI we're building. All share the same capability functions, transports, and permission system.
Three steps to your first agent turn.
Install, pick a model, attach a device. That's it.
Install
git clone https://github.com/TbusOS/android-llm-bridge
cd android-llm-bridge
uv syncPoint to a model
# local Ollama
export ALB_OLLAMA_URL=http://host:11434
export ALB_OLLAMA_MODEL=gemma4:26b
# or any OpenAI-compatible
# vLLM · LM Studio · OpenRouterChat with your device
uv run alb chat \
"grab a logcat and tell me \
why WebView is crashing"Where we are, and where we're going.
M1 transports are stable. M2 agent loop is shipping. M3 unlocks perf and UI. M4+ takes us to on-device agents — the part that changes the game for field debugging.
Available now
M1 · M2 step 3
- 5 transportsadb USB · adb Wi-Fi · ssh · UART · hybrid router
- 6 capabilitiesshell · logging (with UART) · filesync · diagnose · power · app
- 21 MCP tools + 234 testsstructured errors, permission gate, workspace artifacts
- Agent loop (M2)ReAct-lite · alb chat REPL · POST /chat · WebSocket /chat/ws streaming
- Ollama backendthink-field parser · 5-category error mapping · tool calls · streaming
- Config and env~/.config/alb/config.toml · .env.local · cross-project MCP export
In progress
M2 step 4 · M3 opening
- OpenAI-compatible backendone backend for GPT · Claude via OpenRouter · vLLM · LM Studio · MLX · DeepSeek
- Web Tier 1 — chat UIbrowser chat with streaming, device dashboard, live logcat pane, HITL confirms, artifact panel
- Long-task frameworkSSE / BackgroundTask for perf captures, bugreports, multi-minute agent jobs
- perf · benchmark · network · uifresh capability families on top of M1 transports
- Undo & snapshotsroll back file pushes, app installs, permission changes
Roadmap
M3 late · M4+ vision
- 🌟 On-device agentalb-mobile Android app + Gemini Nano / AICore. Host brain, device reflex — jump to the deep dive below.
- Web Tier 2embedded scrcpy · perf curves · ANR timeline · session replay · file browser
- More backendsllama.cpp native · Anthropic SDK · session auto-summary · known-issues memory
- Web Tier 3multi-user collaboration · workflow builder · webhooks · Slack / Discord bot
- Plugins & bindingsthird-party capability plugins · multi-language bindings · multi-vendor SoC adapters
Vision · M4+
An agent on the device itself.
adb round-trips add 50–200 ms each. Boot-time hangs happen before adb exists. ANR triggers fire faster than a host LLM can react. A small agent on the device — Gemini Nano via AICore, or Gemma 4 via LiteRT — closes that loop.
The host still owns heavy reasoning, cross-session memory, and code edits. The device owns reflex: per-thread signals, perfetto traces, local triage, offline autonomy. A WebSocket channel keeps them in lockstep.
Open source. Neutral. Built in the open.
No vendor lock-in. No brand-specific hooks. The whole codebase is readable, scriptable, and extensible — issues, PRs, and ideas welcome.