run-wenlan-app
Skill351 starsChanged 4 months agoApache-2.0View on GitHub
Build, launch, screenshot, and drive the wenlan-app Tauri desktop app in dev mode on macOS (WKWebView) or Windows (WebView2). Use when asked to run or start the app, verify a UI change in the real running app (not just tests), or take a screenshot of it.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- 7xuanlu/wenlanword for word, first seen Jul 14, 2026
Other versions1 project uses a version of this.
Word for word · 1
- 7xuanlu/wenlan★ 358100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- app/AGENTS.mdAGENTS.md
- e2e/AGENTS.mdAGENTS.md
- preview/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- src/AGENTS.mdAGENTS.md
- app/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- preview/CLAUDE.mdCLAUDE.md
- scripts/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- proveSkill
- run-wenlanSkill
- verifySkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
No sibling checkout needed: the monorepo checkout is the backend, and scripts/resolve-backend-dir.sh probes the repo root first (an …
- Very specific: line 32
Never launch target/debug/wenlan-app from there: it is whichever checkout built last.
- Very specific: line 50
Look at the screenshot: after shot — a blank frame means the frontend did not load.
- Distinctive: line 138
Start your own isolated daemon first anyway.
- Very specific: line 177
Create the session with the Tauri capability.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Run wenlan-app (dev)
Tauri 2 desktop app (Rust app/ + React/Vite frontend on :1420). Drive it
with .claude/skills/run-wenlan-app/driver.sh — all paths below are relative
to the unit root (repo or worktree root).
Prerequisites, both Run sections, Gotchas, and Troubleshooting below are
macOS only (driver.sh, vite, ScreenCaptureKit). On Windows the webview is
WebView2 and the recipe is different — jump to
Windows (WebView2).
A debug build refuses to start without a complete isolated runtime identity
(validate_debug_runtime_isolation in app/src/lib.rs), so launch takes the
worktree-scoped config from scripts/dev-runtime.sh and starts its own
daemon on the worktree port. The user's live wenlan-server on :7878 is
never the daemon under test and must never be killed; stop only ends the
daemon this worktree recorded.
Prerequisites
pnpm installdone in the unit root (worktrees start withoutnode_modules).- No sibling checkout needed: the monorepo checkout is the backend, and
scripts/resolve-backend-dir.shprobes the repo root first (an explicitWENLAN_BACKEND_DIRoverrides it; a sibling checkout is only a legacy fallback). Cargo builds in the main checkout's warm, shared target (CARGO_TARGET_DIRdefaults to it viagit rev-parse --git-common-dir). Never launchtarget/debug/wenlan-appfrom there: it is whichever checkout built last.buildclones it and its sidecars into this checkout'starget/wenlan-dev-app/(APFScp -c: shares blocks until the shared target is rebuilt, ~370 MB per worktree at most) andlaunchruns only that clone. Do not give a worktree its ownCARGO_TARGET_DIR: that costs ~14 GB per worktree. - Terminal needs macOS Screen Recording permission (for
shot).
Run (agent path)
.claude/skills/run-wenlan-app/driver.sh build # clean workspace crates, force sidecars, cargo build with this worktree's devUrl/app id baked in
.claude/skills/run-wenlan-app/driver.sh launch # isolated daemon + this worktree's vite + launch target/wenlan-dev-app/wenlan-app directly → "APP UP"
.claude/skills/run-wenlan-app/driver.sh shot /tmp/shot.png # window PNG, works while occluded
.claude/skills/run-wenlan-app/driver.sh stop # kills only this checkout's dev app, vite, and daemon; never :7878 or another session'sLogs land in $TMPDIR/wenlan-app.log and $TMPDIR/wenlan-vite.log.
Look at the screenshot after shot — a blank frame means the frontend
did not load.
Driving UI state
Synthetic events (CGEvent.postToPid) are not handled by Tauri's
WKWebView, and global coordinate clicks are forbidden here (other live agent
sessions share this desktop; a stray click once hit the updater's Install
button and it consumed target/debug/wenlan-app). Instead, drive UI state
through vite HMR: make a temporary import.meta.env.DEV-guarded edit
(e.g. force a section expanded, early-return a toast), wait ~3s, shot,
revert the edit. Mark such edits // TEMP (do not commit).
Run (human path)
pnpm dev:all — the supported entry point: an isolated worktree daemon plus
pnpm tauri dev with a dev bundle identifier and the worktree UI port. Agents
use driver.sh instead because tauri dev dies on cold caches (see Gotchas).
Ctrl-C to stop.
Windows (WebView2)
driver.sh, vite, and wincap.swift are macOS-only. On Windows the app hosts
WebView2, is driven over WebDriver, and is captured with PrintWindow. There
is no committed Windows driver script yet; the recipe below is what a live run
on Windows 11 actually required.
1. Build
export CARGO_TARGET_DIR=C:/wl-target # warm cache; keeps target/ off the worktree
export PATH="/c/Strawberry/perl/bin:$PATH" # see gotcha: openssl-sys needs a real perl
cargo build -p wenlan-app --features tauri/custom-protocol--features tauri/custom-protocol is the important part: it flips
tauri-macros' dev flag off, so the binary embeds dist/ instead of
loading devUrl. That removes vite and :1420 from the picture entirely — a
plain cargo build -p wenlan-app gives you the macOS-style dev binary that
needs a vite server on :1420. Run pnpm build first so dist/ is current.
wenlan-app depends on wenlan-types, not wenlan-core, so the app
builds even on a host where the daemon crates cannot (see the Vulkan gotcha).
2. Isolated runtime identity
A debug build refuses to start without one (validate_debug_runtime_isolation,
app/src/lib.rs). Take the worktree-scoped values from
bash scripts/dev-runtime.sh print-config and export WENLAN_PORT,
WENLAN_DEV_UI_PORT, WENLAN_DEV_REMOTE_PORT_START, WENLAN_DEV_APP_ID,
WENLAN_DEV_STATE_DIR, WENLAN_DATA_DIR, WENLAN_DEV_TAURI_MCP_SOCKET, plus
WENLAN_NO_AUTOSTART=1.
Two things that are easy to miss:
- The bundle identifier must be overridden at build time, not runtime.
tauri_plugin_single_instancekeys on it, so a debug build carrying the productioncom.wenlan.desktopwill hand its argv to the user's real running app instead of starting. The only lever without the tauri CLI isTAURI_CONFIG(json_patch-merged by bothtauri-buildandtauri-codegen):
Set it for the build and confirm it landed:export TAURI_CONFIG='{"identifier":"com.wenlan.desktop.dev.<worktree-hash>"}'stringsthe binary for the id. knowledge_pathmust be written explicitly into$WENLAN_DATA_DIR/config.json. It defaults to.wenlan/pagesunder the OS user home — not underWENLAN_DATA_DIR— so without it an "isolated" run writes pages into the developer's real memory.
3. Daemon
The app does spawn a sidecar daemon on Windows, and it is the
cfg!(target_os = "macos") flag that makes it do so: app/src/lib.rs:1118
reads if !launch_agent_startup { … spawn_daemon_sidecar(…) }, so the branch
always fires off macOS. The macOS path hands ownership to a launchd LaunchAgent
instead. On Windows the app tries to bind the sidecar into a kill-on-close job
object (app/src/daemon_start.rs:356). That is best-effort, not a guarantee:
the bind can fail (a restricted token, an assignment the OS refuses), and
startup deliberately continues on failure rather than leaving the user with no
daemon. The outcome is recorded on the handle as JobBinding::Bound /
Unbound { reason } / NotSupported and read back through
sidecar_job_binding() — ask it, never assume. So: a bound sidecar dies
with the app, hard kill included. An unbound one is ended only by the exit
paths that run app code (tray Quit, SIGTERM, the quit-path kill verified against
the recorded pid and process start time); a hard kill of the app runs no app
code, so an unbound sidecar survives it and holds the port. Confirm the binding
before reporting a clean teardown, and kill by image path either way.
Start your own isolated daemon first anyway. Not because the app cannot, but
because you need one whose port, data dir and pid you recorded: the app's
sidecar, finding yours already healthy on the port, logs
[daemon] Existing healthy daemon on port <n> — exiting cleanly and forgets the
child (app/src/daemon_start.rs:371), which is the state the ownership records
in WENLAN_DEV_STATE_DIR describe.
scripts/dev-runtime.sh start is the supported way and it runs
cargo build -p wenlan-server. That needs the Vulkan SDK, a build-time
prerequisite wenlan-core pulls in through llama-cpp-2's vulkan feature;
without it llama-cpp-sys-2's build script panics and no daemon crate can be
rebuilt. Install it exactly as CI does — scripts/setup-vulkan-sdk-windows.ps1,
which pins LunarG 1.4.350.0 by SHA-256 and installs copy-only under
%LOCALAPPDATA%\wenlan-build — then export VULKAN_SDK in the build shell.
See docs/windows-vulkan.md. The installer ships the loader, and the published
ZIP and NSIS channels are measured starting and answering /api/health on a
driverless hosted runner (first-run-gauntlet.yml). What no gate has ever done
is load a GGUF on a machine with no vendor ICD — the CPU plan sits downstream of
LlamaBackend::init() (crates/wenlan-core/src/engine.rs:33), so end-user
impact is unproven in both directions. Do not repeat "end users are unaffected"
as fact; docs/windows-vulkan.md names the driverless-VM gate that would settle
it.
Falling back to a prebuilt wenlan-server.exe is a last resort: stage it and
write the same ownership records (wenlan-server.{pid,path,port,data-dir} in
WENLAN_DEV_STATE_DIR) so dev-runtime.sh stop still recognizes it — and say
plainly in any report that the daemon was prebuilt, not built by that run.
4. Launch and drive (WebDriver)
tauri-driver --port 17942 --native-port 17943 --native-driver /path/to/msedgedriver.exemsedgedriver.exe must match the installed WebView2 runtime exactly
(151.0.4129.107 ↔ 151.0.4129.107). Check the runtime with the version of
C:\Program Files (x86)\Microsoft\EdgeWebView\Application\<version>\; a
mismatched driver fails the session with a version error, not a useful one.
Create the session with the Tauri capability; msedgedriver launches the app,
so the app inherits the driver's environment — export the isolated identity
in the shell that starts tauri-driver.
{"capabilities":{"alwaysMatch":{"tauri:options":{"application":"C:/wl-target/debug/wenlan-app.exe"}}}}The app exposes three window handles — main (location.hash === ""),
#quick-capture, and #toast. Enumerate handles and pick by hash; do not
assume the first. A capture → search round-trip is: switch to main → click
button[title^='Quick Capture'] → switch to the #quick-capture handle → type
into its textarea → click Save → switch back to main → type into
[data-wenlan-search-input].
5. Screenshot
WebDriver /screenshot captures the webview only. For the real Win32 window
(frame included, and it works while occluded — the analogue of macOS
ScreenCaptureKit) use PrintWindow with PW_RENDERFULLCONTENT (0x2):
enumerate top-level windows with EnumWindows, keep the visible ones whose
GetWindowThreadProcessId matches the app pid, and take the largest by
area — the app owns secondary windows, same rule as wincap.swift. To
photograph a secondary window (the quick-capture composer, say), select it by
title instead; largest-by-area would silently hand back the main window.
Declare per-monitor DPI awareness first, or the capture crops.
powershell.exe is DPI-unaware, so on a scaled display Windows virtualizes its
coordinates: at 125% scaling GetWindowRect on the 1600x900 main window returns
1294x758, PrintWindow renders into a DC built from those numbers, and the
bottom-right fifth of the window — window controls, account chip, Save button —
is cropped away. It reads as an app layout bug and is not one. Call
SetThreadDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)
(-4) before reading any geometry, and treat a NULL return as fatal. That
fatal NULL check is the only thing that catches virtualization, because a
DPI-unaware process is self-consistent: it reads a virtualized GetWindowRect,
renders into a DC built from those same shrunken numbers, and every measurement
it can take of itself agrees at the wrong size. Nothing downstream can tell.
The separate cross-check — that the bitmap you got is the rectangle you asked
for — is against measured geometry, never against the other PNG. The two
captures photograph different rectangles and are supposed to differ:
WebDriver /screenshot returns the client surface; PrintWindow returns the
outer window, frame included. So:
| PNG | must equal (DPI-aware) |
WebDriver /screenshot | GetClientRect |
PrintWindow | GetWindowRect |
Comparing the two PNGs to each other is not a valid check in either direction. Requiring them to match rejects correct captures: this app's real ones are 500x200 client against 518x210 outer for the undecorated quick-capture window, and 1600x900 against 1618x947 for the decorated main window. Those deltas are the frame — 18x10 with no title bar, 18x47 with one — and they are what a correct capture looks like. A frame difference is not a crop; do not "fix" it.
And requiring them to match would never have caught the original bug either.
Virtualization scales every rect a DPI-unaware process reads by the same
factor, so at 125% the client rect and the window rect shrink together and the
frame delta between them shrinks with them: both PNGs come out wrong, in the
same proportion, and a PNG-to-PNG comparison — equality, ratio, or delta —
passes on the cropped capture. No arrangement of the two bitmaps detects it.
The fatal NULL check on SetThreadDpiAwarenessContext is the only guard, which
is why the cross-check is against DPI-aware measured geometry and never against
the other PNG.
wincap.ps1 enforces the PrintWindow half itself: it re-reads the DPI-aware
GetWindowRect after the capture and exits 8 if the PNG's pixel dimensions
disagree, and prints the GetClientRect dimensions beside it so a caller can
check the WebDriver half. A rect it cannot read is COULD-NOT-MEASURE (exit
9) — never a pass. Measure the PNG from its own IHDR bytes, not from the
in-memory Bitmap: re-reporting the object you just encoded checks nothing.
Distinct exit codes only survive if the script never uses Write-Error to
report them. Under $ErrorActionPreference = 'Stop', Write-Error is
terminating: it unwinds the script before the exit N on the next line ever
runs, and powershell.exe reports 1. Every outcome — cropped capture,
unreadable rect, no such window, DPI awareness refused — then arrives at the
caller as the same anonymous 1, which is the "failed measurement that looks
like every other failure" defect wearing a different hat. Write the message
with [Console]::Error.WriteLine($msg) and then exit the code you mean.
Then check the frame is not near-uniform and report a flat frame as unmeasured rather than as a blank UI.
6. Teardown
Kill by ExecutablePath, never by image name — msedgedriver.exe and
wenlan-server.exe may also belong to the developer's real session. Deleting
the WebDriver session closes the app gracefully; then stop the drivers and the
daemon, and measure the result: no process per image path, and no LISTENING
socket on the isolated ports. Stop-Process is not synchronous — poll for
actual exit rather than asserting it.
Filter in PowerShell, not in WQL. Get-CimInstance Win32_Process -Filter
"Name='x'" needs single quotes around the value, and inside a bash
single-quoted -Command block every '' collapses to nothing, so the query
arrives as Name=x — invalid. The error goes to stderr and the empty result
then reads as "that process is not running": the teardown reports a clean kill
it never performed, and the "is it gone?" check answers NONE because the query
failed. Use Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object {
$_.ExecutablePath -ieq $want }, which needs no quoting the shell can eat, and
print the row count beside a negative so an unreadable table is distinguishable
from an empty one.
Windows gotchas
- A search miss contains the query. The empty state renders
main.search.noResults=0 results for "<query>", so assertingmain.innerText.includes(sentinel)passes on a miss. Assert on the hit header instead (main.search.memories_*→N memories for "<query>", only rendered whenmemoryResults.length > 0) plus a result card containing the sentinel. - Search is debounced. Reading the DOM immediately after typing measures the pre-request state. Poll for the result, don't assert once.
GET /api/searchreturns 405 withallow: POST. It isPOST {"query": "..."}.openssl-sysvendored build fails withCan't locate Locale/Maketext/Simple.pm— Git Bash putsC:\Program Files\Git\usr\bin\perl.exeahead of Strawberry Perl in the PATH thatCreateProcesssearches. Prepend/c/Strawberry/perl/binonly; adding Strawberry'sc/binshadows MSVC's cmake.llama-cpp-sys-2build script panics withPlease install Vulkan SDK and ensure that VULKAN_SDK env variable is set.wenlan-corepullsllama-cpp-2with thevulkanfeature on Windows, so without the SDK no daemon crate can be rebuilt —-p wenlan-serveralone is no exception.C:\Windows\System32\vulkan-1.dllis only the loader, not the SDK. A panicking build script never writes itsoutput/stderrfiles, so a stale-but-present artifact is not evidence of a cache hit — read cargo's actual output, and never through a pipe (| tailgives you tail's exit code, not cargo's).
Test
pnpm test (Vitest), cd app && cargo test.
Gotchas (macOS)
launchmust run unsandboxed. The app inherits the shell's seatbelt sandbox, which denies the mach lookup for the ViewBridge XPC service behindNSOpenPanel. The app starts fine and then hard-crashes on the first file/folder picker —+[NSOpenPanel openPanel]returns NULL and objc2 panics — hours after launch, looking exactly like a product bug. It is not: the same call returns a panel normally outside the sandbox.launchnow refuses when it detects a sandboxed shell (canary:pbpaste).tauri devcompiles sidecars insidebeforeDevCommand, then waits only 180s for vite — on a cold cache it dies withError Could not connect tohttp://localhost:1420/` after 180s. The driver decouples: sidecars → vite →cargo build` → direct launch.- A dev app loads whatever frontend answers on its baked-in
devUrl.app/Cargo.tomlhasdefault = [](nocustom-protocol), so a debug build loadsdevUrlat runtime, and no env var overrides it. A plaincargo buildbakes inapp/tauri.conf.json's:1420, which every checkout shares: a launch once loaded another checkout's vite from :1420 and verified the wrong code with no warning.driver.sh buildpassesTAURI_CONFIG='{"identifier":"<WENLAN_DEV_APP_ID>","build":{"devUrl":"http://localhost:<WENLAN_DEV_UI_PORT>"}}'(whatpnpm dev:allgives the tauri CLI;tauri-builddeclaresrerun-if-env-changed=TAURI_CONFIG, so only the app crate rebuilds), clones the result intotarget/wenlan-dev-app/, greps the clone for both values, and writestarget/wenlan-dev-app/stamp;launchrebuilds when the stamp does not match this checkout and port. - A shared target can hand you another checkout's build, silently. Cargo
names a workspace crate's artifacts by its path relative to the workspace
root, so the same crate from two worktrees lands on the same files, and it
decides freshness by mtime. A checkout whose sources are older than another
checkout's last build gets "Finished" and the other checkout's code (proven
with two toy worktrees: B's build printed A's string until
cargo clean -p).scripts/prepare-sidecars.shalso reuses any sidecar binary already in the target unless given--force-build. Sobuildfirst touches every file of this checkout's workspace packages (newer than any build in the target, so they recompile from these sources) and then runsprepare-sidecars.sh --force-build. Never skip either step to save time, and do not swap the touch forcargo clean -p: that deletes every checkout's artifacts for those packages, test binaries and incremental caches included (70 GiB in one run). Sources: Cargobuild.build-dirand build-cache docs (doc.rust-lang.org/cargo/reference/config.html#buildbuild-dir, …/build-cache.html), rust-lang/cargo#16804 (parallel agents) and #16147 (per-workspace build dirs). - Never reuse or kill a vite or app another checkout started. The driver
uses the tri-state probes in
scripts/lib/host-process.sh, so a probe that cannot run refuses instead of reading as "free" or "not ours".vitechecks the UI-port listener's cwd and refuses withREFUSING: :<port> is served by pid … from <other checkout>. The app is tracked by the pidlaunchrecorded intarget/wenlan-dev-app/app.pid, andstopkills it only whilepsstill shows this checkout's exact binary path; never apgrep/pkillname search, which matches every checkout's dev app. If something foreign holds this worktree's UI port, ask its owner; do not kill it. - Changing the driver? Run
bash .claude/skills/run-wenlan-app/driver.test.sh(unsandboxed, no cargo or GUI). Stand-in processes play another session's vite and app; it fails if the driver reuses or kills either. psis denied in the sandbox, solaunch,stopand the test must run unsandboxed; a sandboxedstopprintswarning: dev app NOT stoppedand exits 1 rather than claiming success. Withsccacheas the rustc wrapper,buildmust run unsandboxed too (a sandboxed build dies withexit status: 254on some crate).- The dev updater toast covers the lower-left sidebar and its Install button
is live. Never click it. Suppress during verification with a TEMP
if (import.meta.env.DEV) return null;at the top ofsrc/components/UpdaterDialog.tsx. - The app owns a secondary ~500×500 window;
wincap.swiftsorts by area to capture the main one. - Full-screen
screencaptureshows whatever is frontmost — on a desktop with a live user this races window focus.shotuses ScreenCaptureKit's desktop-independent window capture instead.
Troubleshooting (macOS)
initializing rolling file appender failed ... PermissionDeniedin the app log → the binary was spawned through a sandboxed pnpm/tauri chain; launch the binary directly (whatdriver.sh launchdoes).could not create image from window/could not create image from rectfromscreencapture -l/-R→ usedriver.sh shot.Assertion failed: (did_initialize), function CGS_REQUIRE_INITfrom a Swift capture script → touchNSApplication.sharedbefore creating anSCContentFilter(already done inwincap.swift).failed to restart app: No such file or directoryafter an updater Install → the updater consumed the dev binary; rebuild withdriver.sh build.vitest: command not foundin a fresh worktree →pnpm install.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

