From zero to first task in five steps.
Recipe time. You'll need Codex installed locally and a Poke account — everything else is below.
Check the pantry
Make sure Codex is installed and configured on your machine, and that you have a Poke account. Pokedex drives your existing Codex install — it doesn't replace it.
codex --version
Install the local agent
The agent runs on your computer and connects outbound to the relay over WebSocket — no inbound ports, no firewall changes.
npx pokedex-agent connect
Authorize your workspaces
Expose local projects through safe aliases. Poke will only ever see the alias and its sandbox level — never the real path. Everything is read_only unless you say otherwise.
workspaces:
pokedex:
path: /home/user/projects/pokedex
sandbox: read_only
Add the recipe in Poke
Connect the Pokedex recipe from Poke and point it at the relay's MCP endpoint. The relay validates your auth and pairs Poke with your connected agent.
Send your first task
That's it. Talk to your codebase from any Poke surface. Start with a setup check if you want to be sure everything's wired up.
poke ▸ codex_setup_check ✓ all good
you ▸ In workspace pokedex, analyze the project
and tell me what it does.
Stuck on a step?
The tool reference covers every command, and the FAQ covers the sharp edges.