Tauri Agent Dev

Tauri Agent Dev

Platform Support

• Use this skill on Windows only.
• Do not use it on macOS or Linux. WebView2 CDP is the mechanism here; the other Tauri webviews do not match this flow.

Start A Session

Run everything from the repo root with the Windows toolchain.

Use the PowerShell tool, not Bash + cmd.exe, for every command in this skill. agent:dev:start, agent:dev:probe, agent:dev:stop, and agent-browser connect are exactly the kind of background-spawning / long-running commands where Bash piped through cmd.exe reliably returns only the cmd.exe banner with no real output — the same failure mode root CLAUDE.md calls out for website:build-static, but it is not specific to that one script. If a command run this way returns nothing but the banner, that is the signature of this issue, not a sign the command failed — retry it through the PowerShell tool before concluding anything is wrong.

agent:dev:start does not return to you — always launch it with run_in_background: true. The script itself is written to exit once CDP is up (it spawns tauri dev, polls, prints Tauri dev running., and falls off the end of main()), but through this tool chain the call stays attached to the live process tree and is only reported as complete when you later run agent:dev:stop. Waiting on it in the foreground burns the entire tool timeout and teaches you nothing: a foreground call with a 400 s timeout will be force-backgrounded at 400 s even though the app window opened ~60 s in. Launch it backgrounded and use probe as the readiness signal:

# 1. Launch — run_in_background: true, do NOT wait on this call
bun run agent:dev:start

# 2. Readiness — this one DOES return, in well under a second
bun run agent:dev:probe

The same applies to agent-browser connect <port>: it does not return either. Launch it backgrounded (or simply issue it and move on) and treat the first successful agent-browser snapshot as proof the connection is live — snapshot returns normally.

Useful flags:

bun run agent:dev:start -- --port 9223
bun run agent:dev:start -- --timeout 180
bun run agent:dev:start -- --use-real-config

What start does:

• launches tauri dev
• enables WebView2 remote debugging
• defaults to a sandbox under .agent-dev/sandbox/
• seeds .agent-dev/sandbox/app/config.json on first run so the frontend auto-selects the sandbox journal
• isolates WebView storage under .agent-dev/sandbox/webview/ so localStorage does not leak across runs
• writes runtime state to .agent-dev/state.json
• writes logs to .agent-dev/dev.log

Detecting readiness: don't grep the raw start output for guessed keywords ("ready", "listening", etc.) — per the note above, start never hands its output back, so its stdout is not a readiness signal at all through this tool chain. agent:dev:probe is the purpose-built readiness check and returns structured JSON ({"running":true,...}) the moment the CDP target is live. Poll it directly instead of building an ad hoc log-watcher:

# Poll probe every few seconds until it reports running, instead of waiting on a fixed
# timer or grepping dev.log for inferred markers.
until bun run agent:dev:probe 2>&1 | grep -q '"running":true'; do sleep 3; done

Cold builds take 30-90 seconds; pass --timeout 180 if a Rust rebuild is expected. If the app window is already visibly open (the user can see it), trust that over a probe/log timeout — the window appearing means the session is up even if a polling loop hasn't caught up yet.

After start succeeds, connect the separate browser-driving layer:

agent-browser connect 9222

If you changed the port, connect to that port instead.

Drive The UI

After agent-browser connect, use the normal browser-driving loop:

1. agent-browser snapshot
2. click or fill controls
3. re-snapshot after meaningful UI transitions
4. use eval for DOM or localStorage reads
5. take screenshots when the user needs proof

PowerShell notes:

• Quote @eNNN refs. Use agent-browser click '@e5', not agent-browser click @e5.

• Pass every non-trivial eval script as a single-quoted here-string, never as an inline double-quoted argument. PowerShell eats backslash-escaped quotes inside a "…" argument, so JS containing quoted selectors arrives at the browser mangled. This call:

  agent-browser eval "(function(){ document.querySelectorAll('a[aria-label^=\"Open entry\"]') })()"

  fails with 'a[aria-label^= Open entry]' is not a valid selector — the inner quotes were stripped, not escaped. The failure looks like a bad selector, so it sends you rewriting correct JS. Use:

  $js = @'
  (function(){
    const rows = Array.from(document.querySelectorAll('li button'))
      .filter(b => (b.getAttribute('aria-label') || '').startsWith('Open entry'));
    return { count: rows.length };
  })()
  '@
  agent-browser eval $js

  The @'…'@ form is literal — no $, backtick, or quote interpretation — so the JS reaches the browser byte-for-byte. The closing '@ must be at column 0 on its own line. As a bonus, startsWith/includes filtering in JS avoids CSS attribute-selector quoting entirely.

Stale ref warning: @eNNN refs are assigned at snapshot time. Any DOM mutation (tab switch, scroll, dialog open/close) can reassign refs so an old ref silently targets a different element. For controls inside scrollable panels or dialogs, prefer CSS selectors or JS eval with label-text matching over bare @eNNN refs. Always re-snapshot after a meaningful transition before clicking a ref from a previous snapshot.

type requires the selector and text in the same call: agent-browser type <sel> <text> takes both arguments together — e.g. agent-browser type '@e15' 'some text'. Calling click '@e15' and then type with only the text string (no selector) is a silent no-op: it returns success but nothing is typed, and there is no error to signal the mistake. If eval'd editor/input content comes back empty after a type call, check this first before assuming a focus or timing problem.

Don't burn a full wakeup/turn-cycle on a sub-second wait: known short timers (e.g. the 500ms autosave debounce) don't need ScheduleWakeup or a minute-long pause — that wastes a conversation turn per check. Use a short shell-level wait (sleep 1-2 inline before the next command, or a tight Monitor poll loop) so the verification stays in the same turn.

Stable Selectors

Prefer the app's documented data-testid hooks where they exist. Do not invent new ones.

The canonical list is the data-testid table in src/CLAUDE.md — read it there rather than trusting a copy. It is maintained as E2E contract and grows whenever a new testid ships; a duplicated list here goes stale silently and sends you hunting by text for controls that already have a stable hook. The ones you reach for most in this workflow:

Preferences has no data-testids, but it does have stable id attributes — use those, not visible text (text matching breaks under a non-English language preference):

• Tabs: #pref-tab-general, #pref-tab-writing, #pref-tab-security, #pref-tab-data, #pref-tab-advanced. Note writing and security render only while unlocked (PreferencesOverlay.tsx), so unlock before reaching for them.
• Controls: e.g. #pref-first-day, #pref-timeline-date-format, #show-timeline-preview, #hide-titles, #allow-future, #enable-spellcheck, #editor-font-size.

Common Recipes

Create Or Unlock A Journal

For a fresh sandbox:

1. fill password-create-input
2. fill password-repeat-input
3. click create-journal-button

For an existing sandbox journal:

1. fill password-unlock-input
2. click unlock-journal-button

Dismiss The Onboarding Tour (do this immediately after creating a journal)

A fresh sandbox always lands in the onboarding tour, and its overlay swallows clicks aimed at the header. This is not an occasional annoyance — it fires on every first run, and the symptom is misleading: agent-browser click '[data-testid=header-more-menu-trigger]' reports ✓ Done, the menu never opens, and the follow-up click on a menu item fails with Element not found. It reads like a broken menu or a stale ref. Check for onboarding-next-btn in the DOM before believing that.

Don't step through the tour by hand and don't try to pre-seed its localStorage key — the key is onboarding-shown-{activeJournalId} (src/state/onboarding.ts), and the journal id does not exist until after creation. Click through to the end in one eval instead; the loop is id-agnostic and survives the tour gaining or losing steps:

$js = @'
(function(){
  let clicks = 0;
  for (let i = 0; i < 12; i++) {
    const b = document.querySelector('[data-testid=onboarding-next-btn]');
    if (!b) break;
    b.click(); clicks++;
  }
  return { clicks, stillThere: !!document.querySelector('[data-testid=onboarding-next-btn]') };
})()
'@
agent-browser eval $js

Expect stillThere: false. The final click calls dismissOnboarding(), which persists the key, so the tour stays gone for the rest of the sandbox's life — including across reloads.

Read Or Verify Preferences

Open Preferences via header-more-menu-trigger → header-more-menu-preferences-item (dismiss the onboarding tour first — see above, or the trigger click silently does nothing), then click the tab by id (#pref-tab-writing, etc.).

To inspect saved preferences directly:

JSON.parse(localStorage.getItem('preferences') ?? '{}');

Typical checks:

• autoLockEnabled
• autoLockTimeout
• language
• editorFontFamily

Auto-lock timer interference: If autoLockTimeout is short (< 30 s), the journal will lock between CDP roundtrips — eval calls do not dispatch DOM activity events and therefore do not reset the idle timer.

A bare localStorage.setItem('preferences', ...) write does not fix this — confirmed empirically, not just by reading the source. preferences (src/state/preferences.ts) is a Solid signal created once at module load (createSignal(loadPreferences())); the running app never re-reads localStorage on its own, so writing to it directly changes only what a future page load will pick up, not the live in-memory value the idle timer effect (App.tsx) actually reads. A session that patches localStorage this way and keeps driving the UI will still hit the original timeout and lock mid-session, which looks like a flaky app rather than a stale-write bug.

Two ways to actually change the live value:

1. Drive the real Preferences → Security UI (reliable, no reload needed): open Preferences, click #pref-tab-security, toggle the "Lock after inactivity" checkbox and/or set the timeout input via the native-setter + input/blur-event pattern (see "Compound Eval for Atomic UI Chains"). This calls the app's own setPreferences(), so the live signal updates immediately.
2. Write localStorage then reload the page (agent-browser reload or eval location.reload()): the fresh module load re-reads the patched value. Necessary when the app is on the lock screen and the Security tab isn't reachable yet.

// Extend timeout so the journal stays unlocked during the session — pairs with either method above
(function() {
  const p = JSON.parse(localStorage.getItem('preferences') ?? '{}');
  p.autoLockTimeout = 600;
  localStorage.setItem('preferences', JSON.stringify(p));
})();

Run this eval immediately after unlocking, before taking the first snapshot, and reload afterward if you used method 2. Restore the original value when done if needed.