AI Debug Bridge

The AI Debug Bridge is a way to let the AI read the inner values (variable values, etc.) of a running program directly.

Debugging usually repeats “the AI guesses → I run it → I copy and paste the error → the AI guesses again”. With the debug bridge, the person drops out of the middle. If you put a log line of a set shape (@BLYCK@ …) in your code, Blyck collects that line when it’s printed in a Blyck terminal or the web preview, and the AI reads it to find the cause. Usually the AI adds those lines itself and removes them itself when it’s done.

1. Log line added to the code — @BLYCK@ {"label":…, "vals":…, "level":…} (usually the AI adds and removes it)
2. Run it in a Blyck terminal — Blyck collects the @BLYCK@ lines from the output
3. 🐞 Debug Bridge window (Ctrl+Shift+D) — shows the collected records by step, name and value; the AI reads them with debug_read

Feature	Free	Pro
Viewing logs in the debug window (Ctrl+Shift+D)	✓	✓
The AI adding, reading and removing log lines	—	✓
AI auto-investigation (the AI investigates on its own when an error occurs)	—	✓

When to use it

• When you want to hand “why is this value weird?” to the AI
• When you don’t want to copy and paste terminal output
• When debugging a phone app (Flutter, etc.) — if you run flutter run, adb logcat (Android) or idevicesyslog (iOS) in a Blyck terminal, that output is collected too.

How to use it — just ask the AI

1. Put the AI chat in ⚡ Act or 🚀 Auto mode and say something like “Add debug output to this function and find the cause.”
2. The AI adds log lines to the code or creates a logging helper function (an approval card may appear when it adds lines to your code).
3. You (or the AI) run the program in a Blyck terminal or the web preview.
4. The AI reads the collected logs and fixes the problem. If needed, it runs again to check.
5. When you’re done, say “Clean up the debug lines” — the AI finds the remaining log lines and removes them.

What a log line looks like

@BLYCK@ {"label":"after-add","vals":{"qty":3,"total":null},"level":"debug","loc":"cart.js:42"}

Field	Meaning
label	Name
vals	The values you want to see
level	One of debug, info, warn, error, assert (unknown values become debug)
loc	Location file:line (optional)

• Lines with broken JSON aren’t thrown away; they’re kept with the name (malformed) and level warn.
• If you add lines yourself, make sure only JSON follows @BLYCK@.

Where printed lines are collected from

Output	Collected
Blyck terminal (local · SSH) output	Yes
Web preview console	Yes
Output the AI ran on a remote server	Yes
The editor’s ▶ Run output window	No
Outside Blyck (browser F12 console, other terminal programs)	No

If you ran the program but no logs were collected, first check that you ran it in a Blyck terminal panel.

Debug window — Ctrl+Shift+D

1. Filters — label · loc boxes, level · source pickers / 🔕 auto AI investigation · ⏸ Pause · 🗑 Clear · ✕ Close
2. One record — [step] name value · source (terminal / preview)

A small window that shows collected logs in real time (bottom right of the screen, titled 🐞 Debug Bridge). Press the shortcut again to close it. It shows the same logs the AI reads, so you can see what the AI is looking at while it fixes things, side by side with the conversation. It’s free.

Part	What it does
label / loc boxes	Filter by name or location (partial text)
level picker	debug / info / warn / error / assert
source picker	terminal / preview
🔔 / 🔕	Turn AI auto-investigation on/off
⏸ / ▶	Pause / resume
🗑	Clear — also empties the logs the AI reads
✕	Close

It keeps up to 1,000 lines; beyond that, the oldest are removed first.

AI auto-investigation (Pro, off by default)

When it’s on, whenever an error or assert log appears, the AI starts investigating the cause on its own without being asked. It makes sure you don’t miss the moment a problem happens while the program is running.

• Where to turn it on: 🔔 in the debug window, or AI chat ⋯ → Chat settings → Display → 🖥 Display / Streaming → 🔔 Auto debug investigation (AI auto on assert/error — incurs cost). Both are the same setting.
• The investigation is sent to the AI chat you’re currently using, and only happens when that chat is open and idle.
• To prevent overuse, it runs at most 3 times per 60 seconds, and the same log isn’t investigated again for 120 seconds.

Caution

Auto-investigation calls the AI, so it uses up usage. Turn it on only when you need it.

Tools the AI uses

Tool	What it does	Approval
debug_read	Reads collected logs (filter by name, location, level, source, time)	Not needed
debug_shim	Creates logging helper code for each language (blyckDbg / blyckAssert) — 11 languages	Not needed
debug_probe	Inserts a log line in exactly the right shape at the line you want in a file — JS/TS, Python, Dart, Bash	Needed in ⚡ Act mode
debug_release_check	Finds leftover @BLYCK@ before release	Not needed
debug_strip	Removes only @BLYCK@ output lines (keeps comments, string constants and helper files)	Needed in ⚡ Act mode

• debug_probe and debug_strip are blocked in 💬 Chat and 📋 Plan modes. They also work on remote (SFTP) project files.
• For other languages (Go, Rust, Java, C#, etc.), the AI adds the debug_shim helper directly.

When you release

There are two ways to keep log lines out of your release build.

① Helper code turns itself off in release builds

Language	In release builds
JavaScript	Off when NODE_ENV=production (always on if used directly in the browser without a bundler)
Python	Off when run with python -O
Go	Left out when built without the blyckdebug build tag
Rust · C# · Dart	Off in release builds
Java	Off only if you change DEBUG=true in the code to false yourself
Bash	Prints only when the BLYCK_DEBUG environment variable is set
Kotlin · Swift · C/C++	Based on each language’s debug flag (DEBUG / #if DEBUG / NDEBUG)

② Remove them before release — Tell the AI “Clean up the debug lines” and it finds what’s left (debug_release_check) and removes only the output lines (debug_strip). Folders like node_modules, .git, dist and build, as well as image and archive files, aren’t checked.

FAQ

Do I have to copy console output and give it to the AI? No. That’s exactly why you use this feature. Add log lines, run the program in a Blyck terminal, and the AI reads them directly.

I ran it, but the AI can’t read the logs The output has to appear in a Blyck terminal panel or the web preview. The editor’s ▶ Run output window, terminals outside Blyck and the browser F12 console aren’t collected. Check whether the logs show up in the debug window (Ctrl+Shift+D).

Do I have to remove them when I release? In most languages, the helper turns itself off in release builds. Java has to be turned off by hand. To keep things clean, remove them with “Clean up the debug lines”.

Does the AI jump in on its own when the app throws an error? It does if you turn on AI auto-investigation. It’s off by default, and it uses up usage when on.

Does it work for phone apps (Flutter) too? Yes. If you run logs like flutter run, adb logcat or idevicesyslog in a Blyck terminal, the device app’s logs are collected too.