All jobs

Add a Single-Instance Lock to a Tauri App

Yes. An agent registers Tauri's single-instance plugin first in the builder, so a second launch focuses the open window instead of starting again, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads the desktop side before it changes anything. In a Tauri 2 app like Uninen/tauri-vue-template, src-tauri/Cargo.toml depends on tauri = { version = "2", features = [] }, tauri-plugin-shell and tauri-plugin-prevent-default, with Cargo.lock resolving tauri to 2.10.3; src-tauri/tauri.conf.json names the product tauri-app, the identifier com.tauri-app.my and one 800 by 600 window; and src-tauri/src/lib.rs builds the app with a setup hook that opens devtools in debug builds, registers the two plugins and exposes a greet command. src-tauri/src/main.rs only calls tauri_app_lib::run(). Nothing stops a user from double-clicking the launcher twice and getting two windows with two separate app states.

It adds the plugin the way its documentation asks. cargo add tauri-plugin-single-instance --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))' in src-tauri/ puts the crate under a desktop-only target table in Cargo.toml (the mobile entry point in lib.rs never sees it) and updates Cargo.lock. In lib.rs the agent registers it before tauri_plugin_shell and tauri_plugin_prevent_default, because the plugin must be the first one registered: the builder is made mutable, and under #[cfg(desktop)] it gets tauri_plugin_single_instance::init(|app, args, cwd| { ... }). The closure runs in the instance that already owns the lock, with the arguments and working directory the second launch was given; the agent's handler fetches the main webview window through tauri::Manager, unminimizes it, shows it and calls set_focus, and logs args and cwd so a later feature can act on them. The plugin has no JavaScript API, so no capability file is needed and the Vue frontend under src/ is untouched.

Platform notes go in the pull request rather than a follow-up. On Linux the plugin claims a DBus name derived from the identifier, org.com_tauri_app_my.SingleInstance, so the description says what a Snap or Flatpak manifest would need to allow if the app is ever packaged that way; the plain AppImage and .deb builds the release workflow produces need nothing. The plugin asks for Rust 1.90 or later, and rust-toolchain.toml pins stable, so the agent checks rustc --version in its sandbox and notes the floor in the description. The three workflows under .github/workflows/ already install libwebkit2gtk-4.1-dev, libappindicator3-dev, librsvg2-dev and patchelf on ubuntu-24.04, which is enough for the new crate, so they are left alone.

Before opening anything it proves the change compiles. It installs the same Linux packages in its sandbox, runs cargo check --manifest-path src-tauri/Cargo.toml (what the repository's pnpm check script wraps), then cargo build --manifest-path src-tauri/Cargo.toml so the plugin is linked rather than only type-checked, and cargo clippy on the crate. It runs pnpm test once as well, since vitest is the existing frontend check and tests/unit/example.test.ts should still pass. The command output goes into the pull request description.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Make this Tauri 2 app single-instance. Read src-tauri/Cargo.toml, src-tauri/Cargo.lock, src-tauri/tauri.conf.json, src-tauri/src/lib.rs, src-tauri/src/main.rs, rust-toolchain.toml, package.json and the workflows under .github/workflows first, and confirm no single-instance handling exists today. Add tauri-plugin-single-instance under a desktop-only target in Cargo.toml and register it as the first plugin in the builder, under cfg(desktop). In its callback, unminimize, show and focus the main window and log the second launch's arguments and working directory. Do not change the Vue frontend. In the pull request description note the Rust version the plugin needs, the DBus name it claims on Linux for this app's identifier, and whether any workflow needed a change. In your sandbox install the Linux build packages the workflows install, run cargo check, cargo build and cargo clippy on src-tauri, run pnpm test, and open a pull request that lists the files changed and the command output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request touching src-tauri/Cargo.toml, src-tauri/Cargo.lock and src-tauri/src/lib.rs. The description explains the behaviour in a few lines: the first launch keeps running, a second launch hands its arguments to the first and exits, and the first window is brought to the front. It names the Rust floor the plugin requires, the DBus service name on Linux, and says the workflows did not change.

The run's record holds the cargo check, cargo build, cargo clippy and pnpm test output from the sandbox, so a reviewer can see the crate compiled on Linux with the new plugin without building it locally, and every file the agent read before deciding there was nothing to merge with.

Before merging, a reviewer runs pnpm tauri dev or a built bundle on their own machine and launches it twice, which a headless sandbox cannot show, and decides one product question the pull request raises but does not settle: whether a second launch with a file argument should open that file, which is where the logged args would be used.

Run it on every Linear issue labelled desktop

A team that tracks desktop work in Linear starts one run per issue from an automation with a linear trigger on the desktop label, in the Project that holds the Tauri repository. The trigger adds the issue after this prompt and fills in no placeholder, so an issue that also asks for the forwarded arguments to open a file, or for the window to be restored on a second launch only when it was minimized, is what the agent reads.

Each run checks the app out in its own sandbox, installs the Linux build packages, makes the change and opens its own pull request linking the issue. An automation run has its own max_runs_per_hour cap, and two issues labelled in the same hour get two sandboxes and two pull requests.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

A single-instance lock is a small diff with an order-sensitive detail: the plugin has to be registered before every other plugin, it is desktop-only, and on Linux it depends on DBus. The agent reads the plugin's own instructions and the app's lib.rs in the same run, so the pull request arrives with the registration in the right place and the Linux note already written, instead of a first review round spent on either.

The sandbox is a clean Linux machine where the agent installs exactly the packages the repository's own workflows install, so the cargo build in the record is the same build CI will do. The same request runs against every Tauri app an organisation ships, each in its own sandbox, and each pull request keeps the full command record for the reviewer.

Frequently asked questions

Why does the plugin have to be registered first?

The lock is taken when the plugin initialises. If another plugin ran first, the second instance would do that plugin's work, which can include opening windows or touching state, before finding out it should exit. Registering it first means the second process stops before anything else starts.

Does it need a capabilities file?

No. The plugin has no JavaScript API, so there is no permission for the webview to be granted. The template ships no src-tauri/capabilities/ directory today, and this change does not add one.

What happens to the second launch's arguments?

They arrive in the running instance through the callback as args, with the working directory as cwd. This pull request logs them and focuses the window; a later change, such as opening a file passed on the command line, reads them from the same place.

Does it work on mobile builds?

The dependency sits under a desktop-only target table and the registration is behind cfg(desktop), so iOS and Android builds compile without the crate. A mobile OS already runs one instance of an app, so nothing is lost there.

Will the GitHub Actions workflows still pass?

The build and release workflows already install the webkit2gtk, appindicator, rsvg and patchelf packages on Ubuntu, and the new crate needs nothing beyond those. The agent installs the same packages in its sandbox before building, so the log shows the exact command that worked.

More Tauri jobs

The same job on other stacks

More jobs like this: Turn a Linear label into a PR

Keep reading