What the agent does
The agent clones the repository into its own cloud sandbox and reads the router before it touches a platform file, because a link is only useful if the route it names survives startup. In an app like gskinnerTeam/flutter-wonderous-app, lib/router.dart defines ScreenPaths with /, /welcome, /home and /settings, builds wonder links as /home/wonder/<type>?t=<tab>, and appends video, search, maps, timeline, artifact and collection segments to the current path. The GoRouter has a redirect that, while appLogic.isBootstrapComplete is false, stores the requested URI in _initialDeeplink and sends every request to the splash route; lib/logic/app_logic.dart waits one millisecond "to give GoRouter time to catch the initial deeplink" and then calls appRouter.go(initialDeeplink ?? ScreenPaths.home), unless hasCompletedOnboarding is false, in which case it goes to the intro and the stored link is dropped. _parseWonderType falls back to WonderType.chichenItza for any unknown segment, so a mistyped link opens the wrong wonder rather than a not-found page.
The platform side is half done. ios/Runner/Info.plist already sets FlutterDeepLinkingEnabled to true, but ios/Runner/Runner.entitlements carries only aps-environment and the group.com.gskinner.flutter.wonders.widget app group, with no associated domains. android/app/src/main/AndroidManifest.xml has the MAIN and LAUNCHER intent filter and a PROCESS_TEXT query and nothing that handles VIEW; android/app/build.gradle.kts sets applicationId to com.gskinner.flutter.wonders. pubspec.yaml pins go_router ^17.0.1 on Flutter ^3.41.9 and lists no link package, and the web/ directory holds the site the build_and_deploy_web_* workflows publish. There is no test/ directory.
The agent adds an intent-filter with android:autoVerify="true", the VIEW action, DEFAULT and BROWSABLE categories, the https scheme, the site's host and a pathPrefix of /home/wonder, plus a second filter for a wonders:// custom scheme, to AndroidManifest.xml. On iOS it adds com.apple.developer.associated-domains with applinks:<host> to Runner.entitlements and a CFBundleURLTypes entry for the custom scheme to Info.plist. Under web/.well-known/ it writes assetlinks.json with the package name and a placeholder for the release signing certificate's SHA-256 fingerprint, and apple-app-site-association with the team id placeholder, the bundle id and the /home/wonder/* path, so the deployed site answers the verification requests. In router.dart it makes an unknown detailsType reach errorPageBuilder instead of the Chichén Itzá fallback, and in app_logic.dart it carries initialDeeplink through the intro so a first-time user who taps a link still lands on the wonder after onboarding.
Tests are new to this repository, so the agent creates test/router_test.dart with flutter_test: it navigates the real appRouter to /home/wonder/petra?t=1 and asserts the matched route and parameters, checks that an unknown type produces the not-found page, and checks the redirect stores the link while bootstrap is incomplete. It runs flutter analyze under the analysis_options.yaml rules (always_declare_return_types, always_use_package_imports, prefer_single_quotes), flutter test, flutter build apk --debug so the manifest merge is checked, and flutter build web so the .well-known files appear in build/web, on the Flutter 3.41.9 that build_web.yml pins.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add deep links to this Flutter app and open a pull request. Read pubspec.yaml, lib/main.dart, lib/router.dart, lib/logic/app_logic.dart, lib/logic/settings_logic.dart, android/app/src/main/AndroidManifest.xml, android/app/build.gradle.kts, ios/Runner/Info.plist, ios/Runner/Runner.entitlements, web/index.html and .github/workflows/build_web.yml first. Add an autoVerify https intent filter for the wonder details path and a custom scheme filter on Android, associated domains and a URL type on iOS, and assetlinks.json and apple-app-site-association files under web/.well-known with placeholders for the signing fingerprint and team id. Make an unknown wonder type in a link show the not-found page instead of the default wonder, and keep the initial deep link through onboarding. Add router tests under test/ for a wonder link, an unknown type and the bootstrap redirect. Run flutter analyze, flutter test, flutter build apk --debug and flutter build web, and put the output and the placeholders a person must fill in the pull request description.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 on its own branch. The diff edits AndroidManifest.xml, Info.plist and Runner.entitlements, adds web/.well-known/assetlinks.json and web/.well-known/apple-app-site-association, changes the type parsing and the onboarding branch in lib/router.dart and lib/logic/app_logic.dart, and adds test/router_test.dart. The description lists the two placeholders, the signing fingerprint and the Apple team id, that only the account owner can fill.
The run's record keeps the flutter analyze and flutter test output, the debug APK build with its manifest merge, and the web build showing the .well-known files in build/web, so a reviewer can see the configuration compile on both platforms before a device is involved.
Before merging, a reviewer checks that the host in the intent filter and the entitlement is the one the web workflows deploy to, that the association files are served without a redirect and with a JSON content type, and that the custom scheme is not one another installed app claims.
Run it on every new shareable screen
A repository webhook on your server can send this request whenever a pull request that adds a route to lib/router.dart is merged, with the prompt naming the new path. Each run extends the intent filter's path list, the site association's paths and the router test for that one screen, so links stay in step with the routes rather than being added in a batch later.
The key's webhook_url posts run.completed when the turn ends, with data.session_url for the pull request link; a request_id in each body makes a retry safe.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Deep links fail quietly: a link opens the browser instead of the app because a fingerprint is wrong, or opens the app and lands on the home screen because the router dropped the path during startup. In a Rush sandbox the agent installs the pinned Flutter SDK, runs the analyzer and the new router tests, and builds the Android and web targets, so the pull request shows the configuration is consistent before anyone taps a link on a phone.
The work crosses two platform manifests, an entitlements file, two JSON files on the website, the router and the bootstrap logic. One run returns all of it with its log, and the same prompt runs against several Flutter apps at once, each in its own sandbox reading its own router.dart.
Frequently asked questions
Does this need the app_links or uni_links package?
No. go_router reads the launching link through Flutter's built-in deep link support, which FlutterDeepLinkingEnabled already turns on for iOS and the Android embedding handles when the intent filter exists. The router's existing _initialDeeplink capture is kept and fixed rather than replaced.
Why are there placeholders in the association files?
assetlinks.json must carry the SHA-256 fingerprint of the certificate that signs the release build, and apple-app-site-association must carry the Apple team id. Neither is in the repository, and the agent must not invent them, so the pull request names both and where to find them.
What happens to a link with a wonder that does not exist?
Today _parseWonderType falls back to Chichén Itzá. After the change an unknown segment reaches the router's errorPageBuilder and shows PageNotFound with the requested path, and the new test asserts that.
Will a first-time user lose the link during onboarding?
Not after the change. bootstrap() used to go to the intro and discard initialDeeplink; now the intro completes into the stored link, falling back to /home when there is none. The test covers the redirect while bootstrap is incomplete.
More Flutter jobs
The same job on other stacks
- Add Deep Links to a React Native App (React Native)
- Add Deep Link Handling to a Tauri App (Tauri)
- Add Deep Link Handling to an Electron App from a Linear Issue (Electron)