Forem: Pawel Piecuch

padb: A TUI for Android Debugging That Lives in Your Terminal

Pawel Piecuch — Mon, 04 May 2026 08:19:08 +0000

If you've spent any time doing Android development from the command line, you know the rhythm: adb devices, adb logcat, adb shell, repeat. It works, but it's friction — switching between windows, retyping device serials, manually grep-ing through logcat noise.

padb is a Python-based terminal UI that wraps all of that into one interactive session. No GUI required, no Android Studio open in the background.

What it is

padb runs in your terminal and gives you three things at once:

An interactive shell for ADB commands with history and autocompletion
Live logcat with regex filtering and color-coded log levels, running in the bottom half of your screen
A two-panel file commander (Norton Commander-style) for pushing and pulling files between your machine and the device

It handles both USB and wireless devices, including Android 11+ wireless pairing.

Getting started

git clone https://github.com/yourusername/padb
cd padb
pip3 install -r requirements.txt
python3 main.py

Requirements: Python 3.11+, adb in PATH (or Android SDK installed).

On launch, padb auto-detects connected devices. One device → connects immediately. Multiple devices → shows a selection menu. No devices → waiting screen with background auto-reconnect.

The shell

The top half of the screen is an interactive ADB shell. Type any shell command and it runs on the device:

> ls /sdcard/Download
> pm list packages | grep com.example
> dumpsys battery

There's command history (persisted to .padbrc between sessions) and context-aware suggestions.

The real time-saver is meta commands — prefixed with @, they run common operations without leaving the shell:

Command	What it does
`@install app.apk`	Install APK from local path
`@pull /sdcard/file.txt`	Pull file to current directory
`@push ./local.txt /sdcard/`	Push local file to device
`@screenshot`	Take screenshot, save locally
`@reboot`	Reboot the device
`@connect 192.168.1.100`	Connect to a wireless device
`@pair 192.168.1.100:12345`	Pair with Android 11+ pairing code
`@discover`	Auto-discover devices via mDNS
`@saved`	List remembered wireless IPs
`@forget 192.168.1.100`	Remove a saved wireless IP

Live logcat

The bottom panel streams logcat in real time. You can filter by regex without stopping the stream — the filter applies to all incoming lines immediately.

Log levels get distinct colors: verbose is dim, debug is cyan, info is green, warning is yellow, error is red. On a busy app this makes a real difference when you're scanning for a specific error.

File commander

Press F to open the file commander. Left panel shows your local filesystem, right panel shows the device filesystem. Navigate with arrow keys, Enter to descend, Backspace to go up. Tab switches between panels.

C copies the selected file across panels (local→device or device→local). That's the main workflow: browse to what you need, copy it over.

Wireless workflow

For wireless debugging, padb stores connected device IPs in ~/.padb_wireless.json and tries to reconnect them automatically every time it starts. If the device is on the same network, you typically don't need to do anything — it just connects.

For first-time wireless setup:

Android 11+ (recommended):

Enable wireless debugging in developer options
Tap "Pair device with pairing code" — note the IP:port and 6-digit code
In padb shell: @pair 192.168.1.100:12345 then enter the code
After pairing: @connect 192.168.1.100

Legacy tcpip mode:

Connect USB, then: @tcpip (enables TCP on port 5555 and prints the device IP)
Disconnect USB, then: @connect 192.168.1.100

After either method, the IP is saved and auto-reconnected on future launches.

mDNS discovery (@discover or press D from the waiting screen) works when your device advertises itself on the local network — useful for Android 11+ wireless debugging without knowing the IP.

Why terminal

The short answer: it stays out of the way. No IDE startup time, no separate window to manage. If you're already working in the terminal — running builds, checking git — padb fits into that flow without switching context.

The longer answer: logcat + shell in a split view changes how you debug. You trigger something in the shell and watch the log response in the same window, without alt-tabbing. It sounds small, but the tight feedback loop adds up over a day of debugging.

Current state

padb is actively developed. The core features — shell, logcat, file commander, wireless — are solid for daily use. The project is MIT licensed and contributions are welcome.

Source: github.com/yourusername/padb

Built with Python, curses, and adbutils. Tested on macOS and Linux.

I put Claude inside Blender's Text Editor

Pawel Piecuch — Sat, 02 May 2026 15:17:46 +0000

I got tired of the alt-tab loop. Write a Blender script. Hit an error. Switch to a browser. Paste the traceback to Claude. Copy the fix back. Re-run. Repeat.

So I built Claude Code for Blender, an extension that puts Claude in the Text Editor's sidebar with the active script as automatic context, scene-aware tools, and the ability to actually run the Python it generates. Here's what I learned building it.

The shape of the thing

The extension is pure Python — no native dependencies, no build step. About 5,200 lines across 12 files, packaged as a Blender 4.2+ extension manifest. You drop the folder into your extensions directory, enable it in preferences, hit N in the Text Editor, and Claude shows up next to your code.

Two things made it more than a chat wrapper:

Claude can run code in your Blender session — with undo support, and if the code raises an exception, the traceback gets sent back automatically and Claude tries again.
Claude can edit your text blocks as if they were files on disk — not by generating diffs you copy-paste, but by actually opening and writing them.

The second part is where the interesting engineering lives.

Two backends, one UI

I shipped with two backends and a toggle to switch between them:

CLI backend — shells out to claude -p (the Claude Code CLI in headless mode). Uses your existing Pro/Max/Team subscription. No API key required.
API backend — direct calls to the Messages API with prepaid credits. Implements its own agentic tool-use loop with Blender-specific tools.

Why both? Because the constraints are different. With the CLI, you're piggybacking on a subscription you might already pay for, and you get all of Claude Code's built-in tools (Read, Edit, Write, Glob, Grep, Bash) for free. With the API, you can give Claude tools that talk directly to bpy — create_object, add_modifier, setup_camera, set_render_settings — instead of going through generated Python every time.

The CLI route turned out trickier than the API route, which surprised me. More on that below.

The main-thread problem

Blender has one rule that shapes everything: bpy.* calls only work on the main thread. If you call them from anywhere else you either get garbage state or a segfault.

That's a problem when your AI assistant streams responses for thirty seconds and you don't want the UI to freeze. So the extension runs the request on a background thread and uses Blender's bpy.app.timers to dispatch back to the main thread.

The bridge is small but it earns its place:

class MainThreadBridge:
    def __init__(self):
        self._queue = queue.Queue()
        self._lock = threading.Lock()
        self._streaming_text = ""

    def execute_on_main(self, fn, *args, **kwargs):
        """Run fn on main thread, block bg thread until done, return result."""
        holder = _ResultHolder()

        def _wrapper():
            try:
                holder.set(fn(*args, **kwargs))
            except Exception as e:
                holder.set_error(e)

        self._queue.put(_wrapper)
        return holder  # caller does holder.wait()

A timer drains the queue every tick. Streaming text deltas use a separate lock-protected string so the UI redraw can read the latest chunk without serializing through the queue. Tool calls use the blocking variant — the background thread parks on _event.wait() while Blender executes the tool and returns the result.

One subtle gotcha: bpy.context inside a timer callback has no window, screen, or area. If the tool needs UI context (switching the active text block, redrawing a region), you have to wrap it in temp_override(). I lost an afternoon to that one.

The text-block VFS

Here's the part I'm proud of.

Blender's Text Editor stores scripts as in-memory bpy.types.Text datablocks. They're not files. They have no path. Claude Code CLI, on the other hand, expects to operate on files — that's what its Read/Edit/Write tools do.

So I wrote a small virtual filesystem that mirrors text blocks to disk:

On request, every text block in the .blend gets written to /tmp/blender_claude/<blend_name>/<block_name>.py.
The CLI runs with cwd set to that directory, so when Claude says "read my_script.py", the file is right there.
After the response completes, the workspace is scanned and changes are synced back to Blender's text blocks.
A background poll fires every two seconds to catch external edits and keep the two sides in sync.

The trick is that Claude doesn't need to know it's not editing real files. From its perspective the workspace looks like any other project directory. It uses Glob to find scripts, Edit to do find-and-replace, Write to create new ones. All of that just works, and the extension translates it back to Blender state on the way out.

A few text-block names are reserved and excluded from the sync:

Name	Purpose
`@Prompt@`	Multi-line prompt buffer
`@CLAUDE.md@`	Per-project instructions, prepended to the system prompt
`^...` (caret prefix)	Local scratch blocks, never synced

@CLAUDE.md@ is the one users seem to like most. You write project-specific rules ("always validate with compile() before exec()", "prefer modifiers to bmesh", "this scene is for a music video, keep things stylized"), and they ride along with every prompt for that .blend file.

The agentic loop on the API side

For the API backend, I wrote a simple tool-use loop:

1. Send messages to /v1/messages with stream=True and the tool catalog.
2. Read SSE deltas: text → push to UI, tool_use → buffer the input JSON.
3. On message_complete, if stop_reason == "tool_use":
     - Run each tool on the main thread via the bridge.
     - Append the assistant message + tool_result content to messages.
     - Loop back to step 1.
   Otherwise: done.

Streaming responses are the easy part — requests with stream=True, parse SSE lines, push text deltas to the UI immediately. The harder part is buffering partial tool input. Anthropic streams tool inputs as partial_json deltas, so you accumulate the string, parse it once on content_block_stop, and only then dispatch.

The tools themselves are scoped narrowly. I started with a single execute_python tool and let Claude write code for everything. That worked, but it was slower (extra round-trips for code generation), more error-prone (subtle bpy 4.0+ API changes broke things), and harder to undo. So I added dedicated tools for the boring 80%: create an object, add a modifier, assign a material, set up a camera. Claude reaches for those first and only falls back to execute_python for genuinely custom logic.

That single decision — preferring narrow tools over a code-execution sledgehammer — was the biggest quality win.

Error self-correction

When execute_python raises, the tool result includes the traceback. Claude reads it, sees what broke, and writes a fix. No human in the loop.

try:
    exec(compile(code, '<claude>', 'exec'), namespace)
    return {"status": "ok"}
except Exception:
    return {"status": "error", "traceback": traceback.format_exc()}

Two details matter here. First, compile() before exec() — this catches syntax errors with line numbers so Claude can see exactly where the problem is. Second, every execution wraps bpy.ops.ed.undo_push() so a single chat turn is one undo step. If Claude breaks your scene, one Ctrl+Z makes it whole again.

Blender 4.0+ API gotchas

Claude knows Python. Claude doesn't necessarily know that Blender 4.0 renamed half the Principled BSDF sockets, or that mat.blend_method became mat.surface_render_method, or that mesh.use_auto_smooth doesn't exist anymore. Without guidance, it confidently writes code that worked in 3.6 and fails on 4.2.

The fix is mundane: a chunk of API migration notes baked into the system prompt, plus runtime detection of the actual Blender/Python version so Claude knows what it's targeting:

Blender version: 4.2.3
Python version: 3.11.7
Critical 4.0+ migrations:
- Principled BSDF: "Subsurface" → "Subsurface Weight", "Specular" → "Specular IOR Level", ...
- Material: mat.blend_method → mat.surface_render_method
- Mesh: removed use_auto_smooth, use bpy.ops.object.shade_auto_smooth instead

Boring, but it cut the failure rate on first-attempt scripts dramatically.

What I'd do differently

The CLI backend is the most popular path with users (subscription + zero setup), but it's also where I've spent the most debugging time. Sessions go stale. The CLI's NDJSON event format isn't documented as a public interface, so I had to read it empirically and add fallbacks for unknown event types. Bidirectional file sync is racy at the edges — if the user edits a text block while Claude is also editing the mirrored file, last write wins, and "last" depends on the poll interval.

If I were starting again I'd probably build the API backend first, ship it, and add the CLI later as the second backend rather than the default. The API path is more constrained but more honest about what's happening, and the agentic loop with narrow tools is genuinely good.

Try it

Available on Gumroad for $10. Works with Blender 4.2+ and Bforartists 4.2+. You'll need a Claude subscription (CLI backend) or API credits (API backend). Licensed GPL-3.0; the repo is private for now, but the package ships with full source — once installed you can read everything in blender_claude/ and modify it under the GPL terms.

If you build something with it — a procedural environment, a rigging tool, a render queue helper — I'd love to see it. The whole point of putting an AI in your DCC is that the boring scripting layer disappears. What you do with the time you get back is where the actual work happens.