Poki Agent

Poki Agent accepts tasks from the terminal, or one configured iMessage sender. Telegram is coming soon. It uses pi and the MCP server in this repository. Poki App is not required.

Install

Use macOS, Node.js 24 or later, and the prerequisites in the Poki MCP README.

./bin/setup
npm ci --prefix agent

Run these commands from the repository root. bin/setup checks the required macOS tools, fetches the pinned idevice dependency, builds its command-line tools, installs the MCP dependencies and builds the native bridges. Running npm run build:native alone does not prepare idevice in a new checkout.

Start an MCP server in a separate terminal. Choose its state directory explicitly when you need an isolated instance.

export POKI_MCP_STATE_DIR="$PWD/agent/.runtime/mcp"
node src/daemon.mjs --port 0

Set the same POKI_MCP_STATE_DIR in the terminal that starts Poki Agent. Select a device UUID explicitly. The initial acceptance uses a dedicated simulator.

Configure OpenAI access

Choose one access method. The agent uses pi's existing OpenAI providers and credential handling.

For ChatGPT, run the installed pi CLI, use /login, and choose OpenAI with ChatGPT sign-in. Existing pi openai-codex OAuth credentials are also supported.

cd agent
npx pi

The default is GPT-6.1 Terra (gpt-6.1-terra), low reasoning, with Fast requested. Select ChatGPT access:

export POKI_AGENT_AUTH=chatgpt
export POKI_AGENT_MODEL=gpt-6.1-terra

For API access, set the key in your environment. Never put it in the configuration file or a committed shell script.

export POKI_AGENT_AUTH=api-key
export OPENAI_API_KEY='<your API key>'
export POKI_AGENT_MODEL='<OpenAI API model>'

The defaults are gpt-6.1-terra, reasoning low, and Fast (serviceTier: "priority", sent as service_tier=priority). Execution, result verification and route answers all use low reasoning, including turn/start; callers cannot raise it. Override the model with POKI_AGENT_MODEL or the channel configuration. To request standard service explicitly, use POKI_AGENT_SERVICE_TIER=default. The priority spelling is the supported Fast wire value. Omitted or undefined tier options retain this default.

A requested tier is not proof of the tier served. Each response records the actual outgoing effort, requested tier and raw servedServiceTier; request records retain rejected attempts. If Fast is rejected, that request retries once with explicit default; later requests retain Fast. A response reporting default produces a warning and keeps the configured tier for subsequent execution, verification and readout requests. Shared configuration is never downgraded. This warning stays in the terminal log even when iMessage suppresses progress messages. In local acceptance the ChatGPT account returned default, including when Fast was requested, so Fast has not been verified.

For local protocol development, API-key mode accepts OPENAI_BASE_URL pointing to a loopback HTTP server. Other remote providers are not supported.

Send a terminal task

Run from the repository root.

node agent/cli.mjs --device '<device UUID>' 'Open Settings and read the iOS version.'

The terminal shows progress and the final result. Enter /stop to stop or enter task corrections while it runs. If it cannot complete the task, it reports the completed work, blocker and attempted approaches.

Each step has a 60-second deadline including model and tool time. Set POKI_AGENT_STEP_TIMEOUT or pass --step-timeout <seconds> to the CLI or a channel worker. Individual device tool calls still have a 30-second timeout. There is no whole-task deadline. A forward report_plan.currentStep or a changed screen fingerprint after a successful action resets the step clock, including pages without headings or a bundle ID. Scrolling, swiping, text-field edits without submission, same-page actions and repeated/backward step numbers do not. A pending model request is cancelled when the deadline expires. Task records include metrics.steps with page fingerprint, step, elapsed time and reset reason. Alert/dialog/sheet changes do not count as a new page. Tool errors are returned to the model while the step clock keeps running. Submitting a final answer suspends the step clock. A separate 45-second limit covers the final model response and independent verification. On verification timeout the candidate answer is retained and returned as unverified, never as confirmed success. Each attempt and its reason are retained in execution.verifications. Failed verification resumes the remaining step time and asks the model to continue collecting evidence; it does not grant a fresh deadline. Failure conclusions also undergo independent verification. Claims that an entry or content cannot be found require evidence of scrolling down the current page until content stops changing; scrolling up or reaching the bottom of another page does not suffice. An unsupported failure is returned for further search at most once. Failure review and further search keep the current step clock running. Evidence-backed capability or information blockers remain failures, not successes.

Task records and learned routes are stored under agent/.runtime. Use --state to select another private directory. A verified route repeats the navigation it learned. Missing or ambiguous evidence cannot complete the task. Previous answers are never replayed. A changed navigation page hands execution back to pi from the current screen. Routes older than version 5 must be learned again.

Use --context 'Read only. Do not sign in or register.' to supply initial restrictions without changing the task text. Routes match both the task and its exact initial context. Changing or omitting that context requires exploration again. Instructions entered while a task is running prevent that run from becoming a reusable route.

Channels

Use iMessage or the terminal. Telegram is coming soon.

Validation boundary

Real iMessage and Telegram receipt and delivery, and physical iPhone operation, need a separate authorized run. Fake transport results do not prove either. The local acceptance evidence distinguishes those paths. Source revisions and future synchronization points are in SOURCES.md.

Startup checks and app lookup

Before a channel announces readiness, it checks that idevice-tools exists and is executable at IDEVICE_TOOLS or .deps/idevice/target/release/idevice-tools. The self-chat supervisor also checks the native bridge and OCR executable. Missing tools produce an installation instruction instead of ready; run ./bin/setup in the actual checkout. If the tool disappears later, the task reports that the phone tools need setup. These checks inspect files and do not operate a phone.

The agent's list_apps requires a name or bundle query and returns at most ten matching names and bundle identifiers. Large app metadata and the full directory are never forwarded to the model or verification trace. Call app lookup separately, outside batch_commands. When a target name is known, prefer launch_app by name. The underlying MCP tool API is unchanged.

Each phone tool call has a 30-second deadline. A timeout cancels the request; an in-flight action may already have run, so inspect its result before retrying. The separate step deadline counts cumulative model and tool time on the same page.

License

Poki Agent is part of Poki and uses the AGPL-3.0-only license. Dependencies retain their own licenses; see third-party notices.