Agent Debugging Guide

Use Auditaur data before asking a developer to paste logs, screenshots, browser console output, or terminal output.

Agents can discover this workflow directly from the CLI:

auditaur agent guide
auditaur agent guide --json

Use the JSON form when an agent needs a compact machine-readable contract for no-config observe, configured start/drill/inspect/stop, attach mode, pinned follow-up selectors, and readiness rules.

Agent mental model

Auditaur observes the app. It does not replace the app’s normal dev command. For agent-owned workflows, use the repo’s .auditaur/config.json plus the simple command contract: auditaur start, auditaur drill, auditaur inspect, and auditaur stop.

User phrase	Do this
”observe the app”	Attach to the already-running app and watch readiness.
”start with Auditaur”	Run auditaur start, or use auditaur observe --app <name> -- <normal command> when no config exists yet.
”Auditaur start the app”	Treat this as “start the app under observation”; preserve the normal startup command from config.
”debug with Auditaur”	Check readiness first, then inspect logs, errors, timeline, traces, IPC, and events.
”drive the app”	Require the Tauri-native drive bridge, then use auditaur drive.
”run a confidence drill”	Run auditaur drill for the configured default drill, or auditaur drill <name> for a named drill.
”approve sign-in” / “manual approval”	Use a drill human gate; do not synthesize or bypass the human step.

Install the agent skill

In a repo that uses Auditaur, scaffold the shared debugging skill so agents know the readiness, Tauri-native drive bridge, telemetry, screenshot/snapshot, and cleanup workflow:

auditaur init skill

To scaffold into another repository path:

auditaur init skill --path D:\projects\my-tauri-app

For agents that scan .agents/skills instead of .github/skills, install the same skill into that path:

auditaur init skill --agents-path

After the skill is present on the Auditaur repository’s default branch or published by maintainers, agents/users with GitHub CLI skill support can install it directly:

gh skill install sethjuarez/auditaur auditaur-debug

From the Auditaur repository, maintainers can validate the publishable skill without creating a release:

gh skill publish .github --dry-run

gh skill preview reads from GitHub, so previewing sethjuarez/auditaur will only find auditaur-debug after the branch containing .github/skills/auditaur-debug/SKILL.md is pushed/merged.

Install the manual gate canvas extension

If the repo uses Copilot app canvases, install the Auditaur manual-gate canvas extension alongside the skill:

auditaur init extension

This writes .github/extensions/auditaur-gate/extension.mjs in the consuming repo. During a drill human gate, agents can open the auditaur-human-gate canvas so the tester sees the instructions, evidence context, choices, and inputs in a first-class action card. The terminal and MCP response paths still work when no canvas client is available.

Simplest agent workflow

For first-run agent UX, keep startup and drills in one repo-local config:

{
  "app": "my-tauri-app",
  "start": "npm run tauri dev",
  "readiness": {
    "frontend": true,
    "driveBridge": true,
    "timeoutSeconds": 180
  },
  "ports": {
    "web": {
      "env": "AUDITAUR_WEB_PORT"
    }
  },
  "defaultDrill": "smoke",
  "drills": {
    "smoke": {
      "selector": "#ready",
      "expectText": "Ready"
    }
  }
}

Then agents only need:

auditaur start
auditaur drill
auditaur inspect
auditaur stop

start writes .auditaur/session.json with exact session, instance, pid, database, and selector information. drill uses that session file when present; if no session file exists, it can run an owned drill using the configured start command and clean up like drill run.

When the app supports configurable dev ports, declare named ports and reference them in start with {{port:name}}. auditaur start reserves a random local port for each name, sets the configured environment variable, expands the placeholders in the start command, and records the chosen ports in .auditaur/session.json. This keeps concurrent agent sessions from fighting over one fixed Vite/Tauri dev port.

Startup mode choice

Use attach mode as the default: start the app through the developer’s normal workflow, then have Auditaur observe it.

npm run tauri dev
auditaur debug --app my-app --active --json watch --until-ready

Default readiness means the Auditaur session, telemetry database, window records, and backend/plugin telemetry are ready. Add --require-frontend only when frontend telemetry is part of the check; Tauri WebViews may need a user interaction before frontend telemetry appears. Add --require-drive-bridge when selector actions must be ready.

Use no-config observe mode when an agent or smoke script should own a repeatable validation run without requiring .auditaur/config.json:

auditaur observe --app my-app -- npm run tauri dev

Observe mode starts the same app command you would have run manually; Auditaur does not replace Tauri startup. It watches core readiness, writes .auditaur/session.json with pinned selectors, prints status/tail/logs/drive/stop follow-up commands, and leaves the app running after readiness so the agent can drive, inspect, or clean it up. Use --session-file .auditaur/session.json for read commands such as logs, ipc, timeline, explain, and tail, including postmortem reads after the app exits or crashes. Commands such as npm, pnpm, yarn, and cargo tauri are launched directly across platforms; wrap in PowerShell/bash only when you need shell syntax.

For concurrent agent sessions, avoid fixed frontend/dev-server ports. Reserve a named port and wire it into the app command:

auditaur observe --app my-app --port web -- npm run dev -- --port {{port:web}}
auditaur observe --app my-app --port-env web=VITE_PORT -- npm run tauri dev
auditaur observe --app my-app --port web=5177 -- npm run dev -- --port {{port:web}}

Use random named ports (--port web or --port-env web=VITE_PORT) by default. Use explicit values like --port web=5177 only when the app or test requires a known port. The selected ports are written to .auditaur/session.json so later tools and agents can reuse them without guessing.

Use drill mode when the run should finish as a pass/fail confidence check and clean up the app automatically:

auditaur drill run --app my-app --require-drive-bridge --selector "#ready" --expect-text "Ready" -- npm run tauri dev

See Drill Confidence Runs for report, hook, and exit-code details.

Manual gates for human steps

When validation requires a real human decision, put that pause in a drill script instead of asking the agent to improvise. Human gates preserve the same pinned app session before and after the pause, so the final report can connect readiness, the manual step, frontend errors, IPC, traces, and explain output.

Use this for OAuth device-code approval, SSO consent, OS permission prompts, installer elevation, camera/mic permissions, external browser handoffs, and hardware security keys. Use the lower-level auditaur drill run --script <path> form for gate scripts; see Human-in-the-Loop Drills for complete scripts and the terminal/MCP/canvas response paths.

Drive the UI

Use the Tauri-native drive bridge for selector actions, screenshots, and snapshots. Enable it in exactly one debug/test WebView:

initAuditaur({ driveBridge: true });

Then wait for bridge readiness and inspect the available bridge target:

auditaur debug --app my-app --active --require-drive-bridge --json watch --until-ready
auditaur drive --app my-app --active --json inspect

Prefer read-only actions before mutating the UI:

auditaur drive --app my-app --active --json exists --selector "#ready" --visible-only
auditaur drive --app my-app --active --json text --selector "h1" --visible-only
auditaur drive --app my-app --active --json screenshot --selector ".card" --output card.png

Selector screenshots use native WebView capture first and crop to the requested selector when possible. Successful selector captures report screenshotBackend=tauri_native_webview_snapshot, screenshotScope=selector, and selectorRect.

Integration docs

• Integration Happy Path
• Add Auditaur to a Tauri App
• Migrate from tauri-plugin-log
• Tauri Plugin
• Frontend API
• Drill Confidence Runs
• Human-in-the-Loop Drills
• Architecture
• Troubleshooting
• CLI Recipes
• Compatibility
• CLI Reference
• MCP Tools

First checks

auditaur doctor
auditaur apps --json

If exactly one active readable session exists, Auditaur commands discover it automatically. If multiple sessions are active, copy databasePath from auditaur apps --json and pass it with --db.

When debugging restarts, inspect auditaur apps --json before assuming Auditaur restarted the app. Stale entries can include supersededBySessionId, secondsUntilNextStart, and churnHint when a newer session for the same app appears, which often points to an app restart or Tauri dev watcher rebuild.

Fast failure triage

auditaur errors --json
auditaur exceptions --json
auditaur traces --failed --json
auditaur ipc --failed --json
auditaur events --json

Start with frontend errors, failed traces, failed IPC calls, and recent events. Prefer JSON when another tool or model will inspect the output.

For production-style exception triage, use auditaur exceptions --json to group repeated frontend exceptions, Rust panic-hook records, and failed IPC calls by fingerprint. Use auditaur exceptions --fingerprint <id> --markdown --output issue.md when you need a GitHub issue-ready draft, and redact it before sharing outside the machine.

Follow causality

When a failing trace or IPC call includes a traceId, inspect the full trace:

auditaur trace <traceId> --json
auditaur timeline --trace <traceId> --json
auditaur explain --trace <traceId>

Use the trace detail to connect frontend actions, Tauri invokes, Rust logs/spans, Tauri events, and frontend listeners.

Live debugging

auditaur tail

Use tail while the app is running to watch new logs, errors, spans, IPC calls, and events.

Shareable context

auditaur bundle --redacted --output auditaur-bundle.json

Use a redacted bundle when a bug report or handoff needs a bounded snapshot of the local session.

MCP equivalent

The MCP server exposes the same data for agents that support MCP:

auditaur mcp

Prefer the CLI for quick scripted checks and use MCP when the agent can call tools directly.