# Contributing For details on branches, checks, and how releases work, see [AGENTS.md](AGENTS.md#contribute-code) and [docs/release-channels.md](docs/release-channels.md). Run `npm test` before you submit, and say in the pull request whether you also tested on a Simulator or a physical iPhone. ## When to open an issue first To fix a typo, a small bug, or a documentation gap, feel free to open a pull request right away. To add a feature or make a large change, open an issue first and wait for a maintainer to confirm that it is welcome before writing the code. A large change is any of the following: - A new feature - A change to how Poki operates the phone, including input, taps, screen reading, stopping a task, or keeping a task alive in the background - A change to the first-time setup flow - A change to the main flow of the interface - A change that touches 10 or more files If you are not sure whether your change counts as large, open an issue and ask. A pull request for an unapproved large change may be closed without review, no matter how good the code is. ## Contributor levels There are four contributor levels. Everyone starts at the first level, and you do not need anyone to vouch for you before opening a pull request. | Level | How you get there | What you can do | | --- | --- | --- | | Contributor | Anyone. Fork the repository and open a pull request. | Open issues and pull requests. Until your first pull request is merged, please keep only one pull request open at a time. | | Invited contributor | Have three or more pull requests merged, and receive an invitation from a maintainer. | Triage access to add labels and close issues. You cannot merge pull requests. | | Core contributor | Make sustained contributions over time, and receive an invitation from a maintainer. | Listed in [CODEOWNERS](.github/CODEOWNERS) and in the Core contributors section of [Contributors](#core-contributors). | | Maintainer | Repository owner. | Approve releases and change repository settings. | Only maintainers can merge pull requests into `main`. Moving up a level is decided by maintainers based on the quality and consistency of your work. ## Contributors ### Co-creator
ZhehanZhang
The great co-creator of Poki.
makirqi-alt Filed Poki's first issue, #1, on iOS 18.6.2: screenshots worked, accessibility and touch did not, and the clear split made it easy to follow. |
edge369 Made Poki run on a router in #14, so Telegram can drive the iPhone with the Mac powered off; #15, #17 and #19 followed. |
mawenhao1028 Reported in #6 that usbmuxd listed no iPhone on macOS 27.2; Poki now says so plainly and why a helper stops early (#59). |
igc110 Found why taps on a physical iPhone were slow in #10; the fix that followed made them about a third faster. |
carrotciallo Ported Poki to Linux and tested it on a physical iPhone over USB, LAN and Tailscale in #16; the README now points to it. |
guangtouge82 Traced failing touches on a physical iPhone to a missing display service in #18; Poki now says nothing was sent and points to prepare-device. |
Dreaminmaster Fixed a corrupt cached route that aborted unrelated Agent tasks (#21, #22), then let the Agent reuse its post-action screen read in #37. |
PeterKingXu1s Reported in #25 that a natural-language stop request did not interrupt an iMessage task; Poki now replies to mid-task messages and points to /stop. |
ScottH1122 Reproduced two Agent bugs in #27 and #28, then merged seven fixes and test repairs, from cancelled input locks (#102) to invalid touch coordinates (#136). |
jiahuipaung Fixed in #34 a RemotePairing connection that died when the iPhone's LAN address changed (#30); a real iPhone reconnected in 768 ms. |
Zeno6898 Field-tested the iPhone app over cellular and from Windows in #35 and #40, which led to the Wi-Fi setup note (#138); reported #162. |
scy7796 Fixed taps that failed every time over RemotePairing from a Windows host in #39; 5 of 5 taps then worked. |
foshanfm Ran an insurance-terms check on a real iPhone over Tailscale in #42; the report shaped clearer USB errors and a per-session transport switch. |
xiaweiyi713 Recorded demo videos of Poki driving a real iPhone, so new visitors can see what it does before installing anything. |
f******* Added OpenCode Go as a model account in the iPhone app in #68, with its own Keychain credential and independent model choice. |
owensn951954688 Shared a full timeline of Runner pairing failing after 25 idle minutes in #69; Poki Setup now points to Loopback and Pairing (#70). |
kira-ariaki Made batch calls report an ambiguous device instead of crashing (#74), added POKI_MCP_DEVICE (#75) and an optional per-task approval gate (#77). |
Purelite Fixed pairing setup sending people to the wrong Settings page, so the Developer Mode and UI Automation steps now open the right one (#137). |
heyallencao Fixed screen reads that ran past their call deadline in #139, with a regression test for consistently slow runner responses. |
Ryanwu316 Brought two-app workspaces to iPhone Duo in #354, so a task waits through rotation and resumes on the same app pair. |
soloface Traced MCP 503 errors on a phone that showed online to a relay reconnect bug in #311, with a reproducing test and a patch. |
whiteluw Contributed #326 to avoid a 3D bear startup crash on iPhone. |
cs50Mu Found in #362 that the Poki Setup macOS download only ran on Apple silicon; the universal build that followed also runs on Intel Macs. |
mgkvibez Added a test in #380 that keeps payment checks ahead of message sending, so a Send money button in Mail still asks for approval. |
yulunRyanw Sent a full set of interface designs for the 0.4.0 redesign, from the chat and Live Activity to Settings and a first run (#250, #256 to #268); they shaped the direction of the new interface. |