AI Debug Bridge

The AI is strong at reading the whole codebase and forming hypotheses, but it cannot observe the runtime directly. As a result, debugging becomes a slow relay of “AI guesses → human runs it → human copy-pastes the error → AI guesses again.”

AI Debug Bridge removes the human from that relay. Plant standard structured debug lines (@BLYCK@ {json}) in your code, and Blyck siphons the output streams of every target and feeds them to the AI in a unified format. Debugging becomes “the AI designs an experiment → runs it → observes the structured results directly → fixes.” This works across web, desktop, mobile, and console alike.

Why it’s needed

Problem with traditional log debugging	Details
Slow	AI guesses → human runs it → human copy-pastes the error → AI guesses again (a human stuck in the middle of the relay)
Lossy	Only part of the console gets copy-pasted; intermittent bugs miss the moment
Unstructured	The AI guess-parses raw stack traces / mixed logs
Platform-fragmented	Web console / logcat / os_log / stdout … every approach differs

The key insight is a single question — “Does that app’s output flow into a text stream that Blyck owns (PTY · terminal · SSH · logcat · log file)?” For most cases the answer is “yes,” and even the one exception, the browser console, is a channel Blyck already has.

Wire format — the structured debug line

Regardless of platform, it’s a marker + JSON on one line.

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

Field	Required	Description
label	✅	Probe name
vals		Values to observe (object). If not an object, it’s wrapped as {value:…}
level		debug · info · warn · error · assert (default debug)
loc		file:line (optional)

Blyck stamps at capture time

ts (timestamp) · source (terminal/preview) · sessionId are not put on the wire. Blyck attaches them the moment it captures the log (avoiding clock/environment differences). The @BLYCK@ marker distinguishes these from ordinary logs so the parser picks them out precisely, and even if the JSON is broken it’s preserved as level:warn + the raw text, preventing loss.

Helper API — two functions you plant in code

There are only two concepts.

• blyckDbg(label, vals) — spits out values (a probe).
• blyckAssert(cond, label, vals) — verifies an assumption and, if it breaks, emits a level:"assert" event.

The debug_shim(lang) tool returns a thin shim (about 5 lines each) for 11 languages — js/ts · python · bash · go · rust · java · csharp · dart(flutter) · kotlin · swift · c. All of them provide dbg + assert.

Automatically deactivated in release

Each shim maps to that language’s native debug-only mechanism (JS if (BLYCK_DEBUG) DCE, Python if __debug__:, Go build tags, Rust cfg(debug_assertions), Swift #if DEBUG, Kotlin BuildConfig.DEBUG, etc.). In release builds it is automatically stripped/deactivated, for zero runtime cost. → See Deployment gate.

Capture — two pipes, one buffer

Pipe A — common parser for Blyck-owned streams

From every text stream Blyck launches or connects to — terminal PTY · SSH shell · adb logcat, etc. — it extracts and parses @BLYCK@ {json} lines into a structured ring buffer (cap 1000, FIFO). Non-probe ordinary output flows to the error-marker parsing of Run & Observe (separation of roles).

Pipe B — browser console

The browser console trapped inside the webview is received by the console collection of Live Preview and normalized into the same buffer. On the browser side too, a single console.log("@BLYCK@ …") line is enough.

→ Because both pipes merge into the same buffer, the format the AI sees is identical no matter the target.

Per-platform log streams

What looks like a “platform adapter” is really just flowing that platform’s logs into a Blyck terminal. Just keep the stream open in a terminal and @BLYCK@ is collected automatically.

Target	Logs into the Blyck stream via	Processing
Console / CLI / backend	Terminal stdout/stderr	Pipe A
Android	adb logcat	Pipe A
iOS	idevicesyslog / os_log	Pipe A
Flutter	flutter run or flutter logs (mobile + desktop unified)	Pipe A
Remote (SSH)	SSH shell output	Pipe A
Web server side (SSR · dev server)	Process stdout	Pipe A
Web browser-side console	webview console	Pipe B

AI tools (MCP) — five of them

Tool	Permission	Role
debug_read(filter?)	Read (automatic)	Reads structured debug events directly (zero human copy-paste). filter: label·level·loc·source·sessionId·paneId·sinceTs·sinceSeq (incremental polling)·limit
debug_shim(lang)	Read (automatic)	Returns the per-language blyckDbg/blyckAssert helper source (includes an automatic release no-op guard)
debug_probe(path, line, label, expr)	Confirm	Inserts a single format-guaranteed @BLYCK@ probe line at file:line (js/ts·python·dart·bash, local)
debug_release_check(path)	Read (automatic)	Recursively scans a directory → reports remaining @BLYCK@ locations (marks removable)
debug_strip(path)	Confirm	Bulk-removes only the @BLYCK@ output statements (local, triple safety net)

The value of debug_probe

The core of debug_probe is the format guarantee that prevents the accident of “the AI mis-escapes by hand and it never gets caught by debug_read.” It inserts a precise single line for quick one-off captures, even without a helper.

Two operating modes

Collection is fully real-time (buffered the moment a stream arrives). The AI reacts in one of two ways.

Mode A — Active debugging loop (while working)

Within a single turn: plant probes → run the app → live debug_read → judge → fix → re-run → re-observe. The human drops out of the error relay, and the AI runs the edit/run/observe/fix loop on its own. The key to killing trial-and-error.

Mode B — Auto-investigation (when the running app blows up)

When a level:error or assert @BLYCK@ arrives, the AI jumps into the active chat on its own — without being asked — and investigates the cause. It feels like “a breakpoint that calls the AI whenever a runtime invariant breaks.”

Mode B is OFF by default — automatic AI turns cost money

Auto-investigation incurs token cost, so it is wrapped in four safety layers and disabled by default.

1. OFF by default (opt-in) — Enabled only via the checkbox in the AI settings panel or the 🔔 button in the live debug panel (the setting persists)
2. Global rate limit — At most 3 per 60 seconds
3. Duplicate suppression — The same label+loc has a 120-second cooldown
4. Only when idle — Skipped while the AI is responding (the event stays in the buffer)

The AI doesn’t stare at the stream constantly

The AI doesn’t peek at the logs every moment. It reads them inside a work loop (Mode A) or when an event wakes it (Mode B). Not spending tokens on idle output is actually more efficient.

Live debug panel

Toggle it with Ctrl+Shift+D. It displays the structured @BLYCK@ stream in real time and provides label · loc · level · source filters, pause/clear, and the 🔔 auto-investigation toggle (Mode B).

Because the human sees the same buffer the AI reads, “what the AI is observing and fixing right now” is transparently visible next to the chat window.

Scenario — shopping cart total bug

1. User: “Fix the shopping cart total bug”
2. AI: Inserts blyckDbg('after-add', {qty, total}) · blyckAssert(total > 0, 'total-positive', …) at suspected points
3. AI: Runs the app (terminal or preview) → observes the flow with live debug_read
4. The assert breaks → the AI sees the values and location in full at that moment → fixes immediately → re-runs
5. The user watches in real time in the debug panel + chat window
6. Done → probes auto-deactivate at deploy time

Deployment gate — leave not a single probe behind

The principle: probes are dev-only, and at deploy time they automatically become no-ops/are removed. No manual cleanup.

1. Release flags (NODE_ENV=production · python -O · build-tag removal · NDEBUG …) → the shim compiles down to the native debug mechanism and auto-deactivates. Even if the marker remains, it doesn’t run in release — the most important safety net.
2. debug_release_check(path) — Recursively scans and reports remaining @BLYCK@ locations, marking each line as an output statement (removal target) or not.
3. debug_strip(path) — Runs the cleanup. Triple safety net:
   • Output statements only — Only lines where @BLYCK@ is inside a print/log/console call. Comments, string constants, docs, and helper calls are preserved
   • Shim definition files preserved — Removing the output lines inside a helper would break the file, so such files are skipped entirely
   • Truncate guard — Large files truncated past the read cap would lose data if rewritten, so they are skipped

Why no-op is the default

The default is a guarded no-op (deactivation), not debug_strip (removal). That’s because flipping a single flag lets you revive probes for production debugging.

Limitations

• debug_probe (auto-insertion) currently supports only local files + js/ts·python·dart·bash. For compiled languages (go·rust·java·c#, etc.) and remote (SFTP) files, attach the helper directly with debug_shim.
• Of the 11 shims, 8 (js·python·bash·go·rust·java·csharp·dart) were verified by actual compilation and execution; c·kotlin·swift only passed output inspection due to the absence of build toolchains.
• The AI does not stare at the stream constantly (only in Modes A and B). Mode B (auto-investigation) is OFF by default; consider the token cost when enabling it.
• To keep the marker intact, output only pure JSON after @BLYCK@ (e.g., quote residue mixed in from PowerShell is preserved with a malformed warning).

FAQ

Q. Do I have to copy the console output and give it to the AI? → No. That’s exactly the point of this feature. Plant a probe and run the app, and the AI reads the values directly with debug_read.

Q. I ran it, but it isn’t caught by debug_read. → The output must flow into a terminal/preview stream that Blyck launched. Output from paths not shown on screen, such as isolated execution, isn’t caught by Pipe A. Run it from a terminal panel, or for mobile keep an adb logcat / flutter logs stream open in a terminal.

Q. Do I have to remove the probes when deploying? → Just flip the release flag and the shim auto-deactivates so it never runs. To clean up the markers tidily too, check with debug_release_check and then use debug_strip.

Q. Does the AI jump in on its own when the app errors? → Yes, if you enable Mode B (auto-investigation). It’s OFF by default; enable it via the AI settings panel or the 🔔 button in the live debug panel (Ctrl+Shift+D).

Q. Does it work for mobile / Flutter? → Yes. Keep a log stream open in a Blyck terminal and the device app’s @BLYCK@ is collected automatically — Android adb logcat, iOS idevicesyslog, Flutter flutter run/flutter logs. (For web targets the browser console = Pipe B.)