Important
PickForge IDE was retired on September 3, 2026. It is replaced by the new Pickforge. v0.2.1 is the final release. Existing installs keep working offline, but receive no further updates. This repository is archived and read-only.
An agent IDE for mobile developers. PickForge is a local desktop app that runs your app, lets you pick the on-screen element you care about, and forges its context — source location (or best-effort hints), ancestor/accessibility chain, screenshots — straight into an AI coding CLI (Claude Code, Codex, OpenCode) in an embedded terminal. The agent makes a surgical edit; you hot-reload or re-run; repeat.
It works across Flutter, React Native (Android), native Android, iOS, and web — but not all equally. Support is honest and tiered: Flutter is deep (exact element→source mapping), React Native, native Android, and iOS are useful (run, inspect, logs, best-effort source hints), web is experimental (partial CDP inspection). See Framework support for exactly what each tier means.
PickForge builds the app. PickLab lets agents see, run, and test it. PickArena measures the results.
Local-first. Open source. Built for people who ship. You bring your own agent credentials, and your source stays on your machine — the only things that leave are a startup update check against GitHub Releases (version metadata), anonymous crash reports unless you turn them off, and the context you explicitly forge into a third-party agent CLI, which then runs under your own credentials.
Release builds send anonymous crash and error reports by default so we can fix real failures. Reports can include crash stack traces, error messages, OS details, app version, and loaded system libraries; hostnames and breadcrumbs are stripped. PickForge never intentionally adds file contents, terminal data, prompts, screenshots, or forged context, but native crash dumps include a process-memory snapshot that may contain fragments of data in memory at crash time, including terminal or prompt text. Error messages can occasionally reference file paths. Turn this off in Settings → Crash reports; the change applies after restart. Dev builds keep crash reporting disabled unless PICKFORGE_SENTRY_DEBUG=1 is set.
Quick install (Linux rootless AppImage with FUSE fallback; macOS .app on Apple Silicon):
curl -fsSL https://pickforge.dev/pickforge/install.sh | shPins to the latest release. On Linux the curl installer stays rootless by default and falls back automatically when FUSE cannot be used; set PICKFORGE_INSTALL_KIND=deb or PICKFORGE_INSTALL_KIND=rpm to install a native package when the release publishes one. Intel macOS and Windows aren't built yet — download the installer from Releases.
Download from Releases — .deb/.rpm/.AppImage (Linux), .dmg (macOS), .msi (Windows).
Or build from source:
git clone https://github.com/pickforge/pickforge
cd pickforge
bun install
bun run tauri dev # Rust shell + SolidJS UI, hot-reloaded
# bun run tauri build # produce release bundles (.deb/.rpm/.AppImage / .dmg / .msi)Requires a Rust toolchain and Bun 1.2+. PickForge is built
on Tauri v2 — a Rust core (crates/pickforge-core) behind a
Tauri shell (src-tauri/) with a SolidJS frontend (src/).
The window uses custom chrome (decorations: false) on Windows/Linux — one
draggable title bar with the brand, nav, status, and min/maximize/close
controls. macOS is decorated instead (src-tauri/tauri.macos.conf.json: overlay
title bar, hidden title), so the system draws the rounded corners, shadow, and
traffic lights over the same title bar content. On Linux/Wayland,
the window app_id is forced to the bundle identifier dev.pickforge.app at
startup via gtk::glib::set_prgname in src-tauri/src/lib.rs (enableGTKAppId
alone doesn't set the xdg_toplevel app_id under WebKitGTK — GTK derives it from
g_get_prgname(), which otherwise defaults to the binary name).
Release bundles ship their own desktop entry + icon; for a bare dev binary the
window only shows the PickForge icon once a matching .desktop is installed:
node scripts/install-linux-desktop.mjs # dev binary (target/debug)
node scripts/install-linux-desktop.mjs --release # release binary
node scripts/install-linux-desktop.mjs --remove-stale # drop the old pickforge.desktopThen fully relaunch the window (compositors cache the app_id→icon mapping).
- Launch PickForge. On first run it asks you to Add your first project — pick the folder of a Flutter, React Native, native-Android, iOS, or web project. PickForge detects the framework and shows its support tier next to the run button.
- Inside the workbench, hit + New chat to spawn a persistent agent CLI session in the embedded terminal pane. Each chat keeps its own scrollback across app restarts.
- Run the detected target from the workbench (Flutter run, Metro/Gradle, xcodebuild, dev server). Pick the device when the target needs one — Android emulators and iOS simulators both boot from here.
- Open the inspector and pick an element: Flutter attaches the Dart VM-service widget inspector; React Native and native Android use the UIAutomator accessibility inspector; native iOS uses the
idbaccessibility inspector; web uses CDP/source-map inspection. - Click Forge it to dispatch the element's context as a prompt into the active chat.
Pick an element, forge its context to the agent, let it edit, hot-reload (Flutter) or re-run, pick the next one. The agent never gets a context dump — it gets exactly the element you pointed at, with its source location (or best-effort source hints), ancestor/accessibility chain, and screenshots.
Real capture of the workbench in the studio chrome (frameless bracket titlebar, unified status bar) — the same chrome now shared by every Pickforge Studio app via @pickforge/brand.
By default PickForge keeps each project's chats, runs, screenshots, and context
files in your PickForge home (~/.pickforge/projects/<projectId>/), outside
the repo — so a fresh clone has nothing extra to ignore. Per project you can
switch to project-local storage (a .pickforge/ folder in the repo) or a
custom folder, under Settings → Context storage.
When stored project-local, the layout at your project root is:
.pickforge/
.gitignore # auto-generated, contains "*"
skill-active.md # the current skill directive
widget-context.md # the selected widget's details
screenshot.png # Flutter render (when available)
device-screen.png # full device screen with highlight (Android + adb)
initial-prompt.md # what PickForge piped to your agent
run-log.json # session metadata
In home/custom mode the same files live under
~/.pickforge/projects/<projectId>/ (or your chosen folder) instead — so
transcripts are no longer always under .pickforge.
PickForge never modifies your CLAUDE.md, AGENTS.md, or any of your own
files. The repo-write .pickforge/ marker rule applies to project-local mode
only: if a .pickforge/ already exists there and wasn't created by PickForge,
it refuses to proceed. Switching storage modes offers to copy existing data
to the new location and always leaves the originals in place.
Detailed storage, retention, and migration-backup policy lives in docs/architecture/storage.md.
PickForge declares only the capabilities each framework adapter can actually back, and maps that capability set to a support tier — the same badge you see in the workbench next to the run button. The tiers are honest by design; depth that isn't wired isn't claimed.
| Tier | What it means |
|---|---|
| Deep | Run + exact element→source mapping. The inspector resolves your selection to the precise source location. |
| Useful | Run, logs, screenshot, and element inspection, with best-effort source hints (text / resource-id / test-id search) — not exact mapping. |
| Experimental | Detection plus some tooling, on a thin runtime. |
| Manual | Generic fallback: terminal, attachments, and prompts only — no live inspect. |
| Framework | Tier | What works today |
|---|---|---|
| Flutter | Deep | Run, hot reload, hot restart, stop. Dart VM-service widget inspector with exact selection→source mapping, screenshots, and forge-to-agent. |
| React Native (Android) | Useful | Metro/Gradle run on a device, UIAutomator accessibility inspector + screenshot, adb logcat stream, forge-to-agent with best-effort source hints (no exact source mapping). |
| Native Android | Useful | Gradle run, UIAutomator accessibility inspector + screenshot, adb logcat stream, forge-to-agent with best-effort source hints. |
| Web | Experimental | Dev-server run; CDP / source-map inspection (partial). |
| iOS | Useful | xcodebuild run on an iOS Simulator, idb accessibility inspector + simctl screenshot, os_log stream — proven live on a real simulator. Forge-to-agent with best-effort source hints (accessibility id / label / role — no exact source mapping). Requires idb on PATH (like Android needs adb). Flutter apps on an iOS simulator still get the full Deep VM-service inspector. |
Notes:
- Only Flutter declares exact
mapSelectionToSource. Every other adapter forges a confidence-ranked source-candidate hint and says so — it never pretends to know the exact line. - Detection, command building, and log/hierarchy parsing are fixture-tested (no device required); the live run/inspect paths above are what's wired end-to-end.
- Architecture and the full capability/tier vocabulary live in
docs/architecture/target-adapters.md.
These are tracked but not shipped — don't rely on them yet:
- A web CDP inspector that captures DOM/console/network from a live session.
- An MCP endpoint exposing PickForge's run/inspect/forge tools to agents.
| Category | Supported |
|---|---|
| Agents | Claude Code, Codex, OpenCode. More planned. |
| Devices | Android emulator / device via adb; iOS Simulator via simctl (boot, screenshot, launch) + idb (accessibility dump). Desktop targets are not wired yet. |
| Terminal | Embedded xterm + PTY — no external terminal apps required. Per-chat scrollback persists under the project's resolved context storage (project-local example: .pickforge/chats/<chatId>/transcript.log). |
Canonical PickForge brand assets live in assets/branding/. The set follows the Pickforge Studio v2 system: dark canvas, off-white selection bracket, and one ember accent.
PRs welcome. See SECURITY.md for vulnerability reporting and CODE_OF_CONDUCT.md for expectations.
Design spec: docs/superpowers/specs/2026-04-23-pickforge-design.md.
Implementation plan: docs/superpowers/plans/2026-04-23-pickforge-mvp.md.
MIT — see LICENSE.
PickForge bundles the scrcpy server binary
(src-tauri/resources/scrcpy-server-v3.3.3), © Genymobile / Romain Vimont, licensed
under the Apache License 2.0. It is
redistributed unmodified — see NOTICE for details.
