# 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
ZhehanZhang

The great co-creator of Poki.

### Core contributors
makirqi-alt
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
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
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
igc110

Found why taps on a physical iPhone were slow in #10; the fix that followed made them about a third faster.
carrotciallo
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
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
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
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
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
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
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
scy7796

Fixed taps that failed every time over RemotePairing from a Windows host in #39; 5 of 5 taps then worked.
foshanfm
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
xiaweiyi713

Recorded demo videos of Poki driving a real iPhone, so new visitors can see what it does before installing anything.
f*******
f*******

Added OpenCode Go as a model account in the iPhone app in #68, with its own Keychain credential and independent model choice.
owensn951954688
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
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
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
heyallencao

Fixed screen reads that ran past their call deadline in #139, with a regression test for consistently slow runner responses.
Ryanwu316
Ryanwu316

Brought two-app workspaces to iPhone Duo in #354, so a task waits through rotation and resumes on the same app pair.
soloface
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
whiteluw

Contributed #326 to avoid a 3D bear startup crash on iPhone.
cs50Mu
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
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.
### Special contributors
yulunRyanw
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.
### Thanks Thanks to everyone who opened an issue or pull request. Your feedback and fixes make Poki better.
ZhehanZhang
ZhehanZhang
carrotciallo
carrotciallo
cs50Mu
cs50Mu
Dreaminmaster
Dreaminmaster
edge369
edge369
foshanfm
foshanfm
f*******
f*******
guangtouge82
guangtouge82
heyallencao
heyallencao
htx996
htx996
igc110
igc110
iTry
iTry
jiahuipaung
jiahuipaung
kilingzhang
kilingzhang
kira-ariaki
kira-ariaki
lunar-me
lunar-me
makirqi-alt
makirqi-alt
mawenhao1028
mawenhao1028
mgkvibez
mgkvibez
oasis979559-alt
oasis979559-alt
owensn951954688
owensn951954688
PeterKingXu1s
PeterKingXu1s
Purelite
Purelite
Ryanwu316
Ryanwu316
ScottH1122
ScottH1122
scy7796
scy7796
soloface
soloface
wanghao-SunSky
wanghao-SunSky
whiteluw
whiteluw
windywendyday
windywendyday
xiaweiyi713
xiaweiyi713
yulunRyanw
yulunRyanw
zcyoung2000
zcyoung2000
Zeno6898
Zeno6898
zqy5608
zqy5608
### Star History Star History chart ## AI assistance You are welcome to use AI tools. The pull request template asks you to include one line: > AI assistance: None, Claude Code, Codex, or Other. I have reviewed and understand these changes. List the tool you used, and confirm that you have read and understood the entire change. Be ready to explain any line during review. ## How to open a pull request You do not have write access to `JosssphZhou/poki`, so `git push` to it fails with `permission denied`. That is expected. Push to your own fork and open the pull request from there. With the GitHub CLI, from your clone with the branch already made: ```sh gh repo fork --remote # creates your fork, adds it as origin, renames the old origin to upstream git push -u origin gh pr create --base main ``` Without it: click **Fork** on GitHub, then ```sh git remote add fork https://github.com//poki.git git push -u fork ``` and open a pull request from that branch into `main` of `JosssphZhou/poki` on the website. Before you open it, run `npm test` and fill in the [pull request template](.github/PULL_REQUEST_TEMPLATE.md): what changes and how you tested it. The `PR checks` workflow must pass. By submitting a contribution, you release it under the [AGPL-3.0-only license](LICENSE). You confirm this once: on your first pull request, Poki Repo Bot asks you to agree to the [Poki Contributor Agreement](CONTRIBUTOR_AGREEMENT.md) by commenting `I agree to the Poki Contributor Agreement` from your own account. That covers your later pull requests too, and the `Contributor agreement` status on the pull request turns green. Use third-party code only if its license is compatible with AGPL-3.0-only. Keep the original copyright notice and list the code in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Do not commit device screenshots, clipboard contents, pairing records, passcodes, or tokens.