agentic-debug-mode

name	agentic-debug-mode
description	Use when a bug, regression, race condition, or unexpected behavior has no proven root cause and you must confirm the cause with runtime evidence instead of guessing from source code.

Debugging with Runtime Evidence

Core rule

Source code creates hypotheses. Runtime evidence confirms or rejects them.

Do not implement a bug fix before collecting runtime evidence that identifies the cause. Reading code tells you what could happen; only observations from a real run tell you what did happen.

debug-mode is a small CLI that collects and queries that evidence for you. It manages its own background service; you never manage processes, ports, or state files. Every command prints readable text by default — read that text, do not scrape it.

Do the work yourself

Do not ask the user to perform an action you can execute with available tools. Run available CLI commands, tests, and HTTP requests yourself, including installation, session setup, resetting evidence, reproduction, and evidence collection.

Ask the user only for inaccessible interactions: a physical device or on-screen tap you cannot drive, an external system or account you have no credentials for, or subjective confirmation that the observed behavior now looks correct. Before asking, complete every accessible prerequisite — insert observations, reset the session, rebuild — and request only the smallest remaining step.

Vocabulary

Terms used throughout, defined once:

• Session — one debugging investigation, identified by a random UUID. It owns one evidence record. Every session-scoped command needs --session <id>.
• Hypothesis label — your own name for one falsifiable guess, such as H1. You invent and track these; the CLI never registers, declares, or validates them. It only groups and filters the labels it sees in evidence.
• Helper template — a block of code, inserted once per runtime, that owns transport, envelope construction, size limits, and failure suppression. Treat it as opaque. Its declared placement says where it must go: at file start for C and C++ (their includes must precede declarations), at module or file scope for every other language.
• Call template — a small block copied once per observation, always in statement position. You replace only its placeholders. Most languages take a native value in __DATA_EXPRESSION__ and serialize it for you; Rust, C++, and C instead take __DATA_JSON_EXPRESSION__, an expression that already evaluates to one complete serialized JSON value (use the application's serializer, or the helper's json_string(text) fallback for plain text — never hand-concatenate raw JSON).
• Observation — one agent log region emitting one event that tests one hypothesis.
• Ingest URL — the loopback address an HTTP helper posts to. The session is in the URL path; it is not a secret and needs no header.
• Append path — the file a file helper appends newline-terminated JSON records to.
• Reset cycle — everything between one reset and the next. Resetting restarts sequence numbering at 1 and invalidates old log/query cursors.
• Runtime evidence — the validated events the CLI returns from logs, query, and status.

Resolve the CLI

Run debug-mode --version. If it is missing, install it with the first channel the host's package policy allows, then verify again:

1. npm: npm install --global agentic-debug-mode@latest
2. Bun: bun install --global agentic-debug-mode@latest
3. Homebrew only when the project documents its official tap coordinate.
4. Zero-install fallback: prefix every command with npx --yes agentic-debug-mode@latest.

Never use an unverified curl | sh, never request elevated privileges, and never edit shell startup files. If no supported channel works, stop and report the exact error.

If a command reports The optional package agentic-debug-mode-<platform> is missing, the launcher installed but its platform binary did not. This is almost always npm skipping the platform optionalDependencies on an upgrade, or a just-published version whose platform tarballs have not finished propagating to the registry CDN yet. Recover by reinstalling: npm uninstall --global agentic-debug-mode then npm install --global agentic-debug-mode@latest. If it still reports the missing package immediately after a release, wait a minute for CDN propagation and reinstall; do not switch install channels or disable optional dependencies.

Workflow

For one investigation, repeat this loop with one session:

1. Create a session.
2. Get a language template and insert folded observation regions.
3. Reset the session, then reproduce.
4. Read evidence with logs, query, and status.
5. Classify each hypothesis in your own reasoning.
6. Change code or observations.
7. Reset and reproduce again.
8. Compare evidence until it proves the fix.
9. Remove observations, then stop.

1. Create a session

debug-mode create

The output returns a Session ID, an Ingest URL, and an Append Path. Keep the Session ID and pass --session <id> to every later command. Reuse this one session for the whole investigation — do not create a fresh session per attempt.

Never guess a session. If you lose the ID, recover it (newest first):

debug-mode sessions

sessions lists sessions; it never selects one for you. sessions --all includes older sessions.

2. Get a template and instrument

State expected behavior, actual behavior, and the shortest reproduction. Form three to five precise, falsifiable hypotheses and label them H1, H2, and so on. Then request the template for the runtime you are instrumenting.

debug-mode template --language typescript --ingest http
debug-mode template --language python --ingest file

Transport follows runtime reachability. Use HTTP for JavaScript and TypeScript (one shape across browser and server) with the Ingest URL. Use file append for local CLIs and services with the Append Path. Advertised combinations, each verified end-to-end:

Language	Ingest	Language	Ingest
JavaScript	http	Ruby	file
TypeScript	http	PHP	file
Python	file	PowerShell	file
Go	file	C#	file
Swift	file	Rust	file
C++	file	C	file
Java	file	Kotlin	file

The output has four sections: HELPER TEMPLATE, CALL TEMPLATE, PLACEHOLDERS, and EVENT SCHEMA.

Insert the helper template once per runtime boundary. Copy the call template once per observation. Replace only the listed placeholders — for HTTP replace the ingest placeholder with the Ingest URL; for file replace the append placeholder with the Append Path; then fill hypothesis, location, message, and data.

Keep every observation inside its own region, and keep the exact markers so the block stays foldable and mechanically removable:

// #region agent log
__agentDebugEmit({
  hypothesisId: "H1",
  location: "src/cart.ts:84",
  message: "Before discount calculation",
  data: { itemCount: items.length, subtotal },
});
// #endregion

Python and Ruby use # region agent log / # endregion; Rust, C, C++, Go, Java, Kotlin, C#, and Swift use the // #region agent log / // #endregion line-comment form. Keep whichever markers the template prints. Never put production behavior inside a region, never await an observation, and never instrument a generated file whose syntax cannot hold the markers.

Event schema

Every observation carries exactly five fields:

• hypothesisId — your label for the one hypothesis this observation tests.
• location — stable source location, preferably path:line.
• message — a constant description of the observation; changing values go in data, never here.
• data — bounded JSON holding the values that change between runs.
• timestamp — observation time in Unix epoch milliseconds. The helper sets it for you.

Stored evidence adds id, sequence (order within the reset cycle), and receivedAt (receipt time, also Unix epoch milliseconds). When timestamps tie, sequence breaks the tie.

Keep message constant and put changing values in data. Keep data small and bounded — choose the smallest diagnostic value that tests the hypothesis. Excluding secrets is your responsibility: never record passwords, cookies, authorization headers, private keys, full request bodies, or unrelated personal data. Redaction before stored evidence is a safety net, not permission to send secrets — and the Rust, C++, and C helpers do no client-side redaction at all, so whatever the call site passes is what leaves the process. A failed observation must never change application control flow; the helper isolates transport failures, so missing events mean an unexecuted path or a failed run, never a crash.

3. Reset and reproduce

Clear the previous evidence for this session, then reproduce:

debug-mode reset --session <id>

Reset preserves the session ID, the append path, and your inserted observations; it only clears evidence and restarts sequence numbering. Reproduce yourself whenever the runtime is accessible (run the test, script, or request). If reproduction needs the currently valid Ingest URL, take it from the reset output before running.

4. Read evidence

Use only debug-mode logs, debug-mode query, and debug-mode status to read runtime evidence. Never use native file-reading tools, shell commands, tail, sed, awk, a direct jq/jaq, or ad hoc scripts against the evidence — those bypass validation and session isolation.

Start with a bounded read:

debug-mode logs --session <id> --limit 100

Filter or transform with an embedded jaq program:

debug-mode query --session <id> 'select(.message | test("timeout|deadline"; "i"))'
debug-mode query --session <id> 'select(.hypothesisId == "H1" and .data.durationMs >= 100)'
debug-mode query --session <id> '{seq: .sequence, loc: .location, ms: .data.durationMs}'

Streaming is the default and stays memory-bounded. Collection operations — sort_by, group_by, whole-run aggregation — need explicit --slurp:

debug-mode query --session <id> --slurp \
  'group_by(.hypothesisId) | map({hypothesisId: .[0].hypothesisId, count: length})'

Every result is ordered: warnings first, then the session scope, then statistics, then the records or results, then actionable hints. Read them in that order — check warnings, confirm the session, weigh completeness, then follow the printed continuation commands to page. Those commands carry the query scope; reuse them instead of inventing offsets.

If logs or query reports malformed records, inspect all of them:

debug-mode status --session <id>

status lists every malformed record and evidence-health summary. Fix the emitting observation each diagnostic identifies, reset the session, and reproduce. Never edit stored evidence.

5. Classify each hypothesis

In your own reasoning, mark every hypothesis and cite event IDs or sequence numbers:

• CONFIRMED — events directly demonstrate the causal path.
• REJECTED — events contradict the hypothesis.
• INCONCLUSIVE — expected evidence is absent or ambiguous.

Missing events can mean an unexecuted path, a failed run, or stale code — not proof of absence. Add a control observation before rejecting on silence. If nothing is confirmed, form new hypotheses in other subsystems and repeat. Remove speculative edits for rejected hypotheses; implement only the smallest fix the confirmed evidence supports.

6. Verify the fix

Keep every observation in place through verification. Record your baseline conclusions from the first run in your own notes, apply the fix, then reset and reproduce again and re-run the same queries. The post-fix evidence must show both that the wrong path or state no longer occurs and that the expected path or invariant now does. Baseline and post-fix both live in this one session across reset cycles; nothing persists two separate runs for you.

Remove the complete agent log regions only after post-fix evidence succeeds and the user confirms the behavior looks correct.

7. Clean up

• debug-mode reset --session <id> reuses the same session — it clears evidence but keeps the session and your observations for the next attempt. This is the normal per-attempt command.
• debug-mode clean --session <id> permanently deletes the session and all its evidence. Use it only when the user explicitly asks to delete the investigation.
• debug-mode stop ends the background service without deleting any evidence. The next command restarts it transparently.

Common mistakes

• Fixing before evidence confirms the cause. Collect first.
• Creating a new session per attempt. Reuse one; reset between attempts.
• Reading the evidence file directly. Use logs, query, status only.
• Rejecting a hypothesis on missing events without a control observation.
• Removing observations before post-fix evidence and user confirmation.
• Putting changing values in message instead of data.
• Asking the user to run something you can run yourself.

Quick reference

Step	Command
Create session	debug-mode create
Get template	debug-mode template --language <l> --ingest <t>
Reset evidence	debug-mode reset --session <id>
Read a page	debug-mode logs --session <id> --limit 100
Query evidence	debug-mode query --session <id> '<jaq>'
Diagnostics	debug-mode status --session <id>
Recover an ID	debug-mode sessions
Delete a session	debug-mode clean --session <id>
Stop the service	debug-mode stop

For the full command and jaq-query reference, see REFERENCE.md. For worked end-to-end investigations, see EXAMPLES.md.