Pokedex Documentation
Local MCP bridge for Poke: typed pokedex_* tools, workspace-scoped Codex runs, and prompt-based configuration.
Installation
Two steps. That's the whole install.
Add the recipe in Poke
One tap. The recipe gives Poke the pokedex_* MCP tools, not shell or filesystem access.
Run the bridge in your project
One command, inside the project Codex should see. Keep the terminal open while you use Poke.
Setup, workspaces & skills
Check bridge health, list workspace aliases, and discover local Codex skills.
pokedex_setup_check#Checks Codex login, the app-server command, relay pairing, and workspace visibility.
pokedex_list_workspaces#Returns configured workspace aliases, descriptions, and effective access labels. Arbitrary paths are not accepted.
pokedex_list_skills#Lists local Codex skills available to a workspace, including ~/.agents/skills and ~/.codex/skills.
pokedex_list_plugins#Discovers installed Codex plugins and marketplace plugin data when the local app-server exposes it.
Threads & discovery
Find Codex work that already exists on your machine before starting something new.
pokedex_list_tasks#Lists local Codex tasks from native app-server threads.
pokedex_list_sessions#Lists local Codex sessions from native app-server threads.
pokedex_list_threads#Lists native local Codex threads, optionally filtered by workspace, search term, cursor, limit, or archive state.
pokedex_read_thread#Reads a stored local Codex thread and includes turns by default.
Work tools
Start new Codex work or continue existing work. Start tools need a workspaceAlias and a prompt; follow-up tools need a threadId.
pokedex_start_task#Creates a local Codex task in a workspace alias and sends the first prompt.
pokedex_start_thread#Creates a native local Codex thread and sends the first prompt.
pokedex_continue_task#Sends a new turn to an existing local Codex task.
pokedex_send_turn#Sends a new turn to an existing native Codex thread.
pokedex_resume_task#Resumes a stored local Codex task and sends a new turn.
pokedex_resume_thread#Resumes a stored local Codex thread and sends a new turn.
pokedex_fork_thread#Forks a stored local Codex thread into a new thread.
pokedex_interrupt#Interrupts the active turn for a native local Codex thread.
Operations & progress
Track long-running Codex work without retrying the same request. Poll the operation until it is completed or failed.
pokedex_list_operations#Lists local long-running Codex operations with status, workspace alias, cwd, settings, last progress event, usage, and rate-limit state.
pokedex_read_operation#Reads one operation and can wait up to 30000ms for the next progress event using afterEventsSeen and waitMs. Running operations report active or stalled health.
Review, goals & diagnostics
Run reviews, manage long-running goals, read diffs, check git readiness, and inspect usage plus rate-limit data.
pokedex_review#Starts Codex review mode on an existing thread or on a new thread in the requested workspace.
pokedex_set_goal#Sets a Codex goal on a native local thread.
pokedex_clear_goal#Clears the Codex goal on a native local thread.
pokedex_get_diff#Reads git diff stat and changed file names from an allowed local workspace.
pokedex_get_usage#Returns latest observed token usage plus Codex account rate-limit data and reset timing when app-server exposes it.
pokedex_git_check#Checks git identity, remotes, and headless SSH/GPG/credential state before commit or push work.
pokedex_git_commit#Creates a local git commit through Pokedex. Requires workspace write access and an explicit commit message.
pokedex_git_push#Pushes through local git and headless credentials. Requires effective full-access for the selected workspace.
pokedex_git_commit_push#Creates a local commit and then pushes it, without asking Codex to run free-form shell commands.
Approvals
When Codex pauses for approval on a command or file change, ask Poke to list approvals, then approve or decline the pending request from chat.
pokedex_list_approvals#Lists Codex approvals waiting for a decision from Poke.
pokedex_approve#Approves a pending command or file-change request. Omit approvalId when only one is pending; forSession maps to acceptForSession when the pending approval supports that scope.
pokedex_decline#Declines a pending command or file-change request. Omit approvalId when only one is pending.
pokedex_cancel_approval#Cancels a pending command or file-change request. Omit approvalId when only one is pending.
Runtime fields
Start tools accept workspaceAlias and prompt. Follow-up tools use threadId. New threads can set sandbox and approval policy; later turns keep thread permissions and can override model, reasoning, verbosity, web search, and skills.
workspaceAlias#Required when starting work in a local project. It must match a configured workspace alias.
prompt#Required for start and turn tools. This is the user instruction sent to Codex.
threadId#Required for read, continue, resume, fork, interrupt, and goal tools.
name#Optional human-readable name when starting a new task or thread.
model#Optional model override for supported task and turn calls.
profile#Optional Codex profile override passed through to the app server.
reasoningEffort#Optional value: minimal, low, medium, high, or xhigh.
verbosity#Optional value: low, medium, or high.
sandbox#Optional on new task/thread/review calls: read_only, workspace_write, or danger_full_access.
approvalPolicy#Optional on new task/thread/review calls: untrusted, on-request, or never.
webSearch#Optional value: cached, live, or disabled.
skillNames#Optional list of local Codex skill names. Pokedex resolves the paths and sends skill inputs to Codex; writing $skillname in the prompt works too.
skills#Optional advanced input: list trusted Codex skills with name and path, forwarded as skill inputs for the turn.
Startup flags
Flags passed to npx codex-to-poke override the saved config and are stored for later runs.
--workspace <path>#Folder used for the startup workspace instead of the current directory.
--alias <name>#Alias for the startup workspace. The default first-run alias is main.
--read-only | --write | --full-access#Access mode for the startup workspace. First run defaults to read-only.
--port <number>#Local relay port. The default is 4200.
--token <value>#Overrides the random relay bearer token.
--model <name>#Default Codex model for requests that do not override it.
--reasoning <level>#Default reasoning effort: minimal, low, medium, high, or xhigh.
--verbosity <level>#Default response verbosity: low, medium, or high.
--approval <policy>#Default approval policy: untrusted, on-request, or never.
--codex <command>#Command used to start the Codex app server. The default is codex.
--user-id <id>#Local user id used to pair the agent with the relay. The default is local.
CLI help
This is what npx codex-to-poke help prints (the startup help prints. Interactive pokedex> prompt commands are documented in the next section.
pokedex Local Poke to Codex bridge. usage pokedex [--workspace .] [--alias main] [--port 4200] pokedex [--read-only | --write | --full-access] pokedex help config ~/.pokedex/config.jsonc common npx codex-to-poke npx codex-to-poke --write npx codex-to-poke --full-access
Local prompt commands
Everything you can type at the pokedex> prompt while the bridge is running, matching the help command output.
status#Shows relay, agent, and Poke tunnel status, the MCP URL, the active workspace, and the access mode.
logs [relay|agent|poke]#Shows recent logs for one service, or all services when omitted.
shell <on|off>#Allows or blocks Poke from applying supported Pokedex prompt commands through pokedex_command.
ws list#Shows configured workspaces and marks the active one.
ws add <alias> <path> [description]#Adds or updates a workspace alias for a local path.
ws rm <alias>#Removes a workspace alias. The last workspace cannot be removed.
ws use <alias>#Makes a workspace active and restarts services.
ws desc <alias> <description>#Changes the human-readable workspace description.
ws perms <alias> read-only|write|full-access#Sets the effective access level for one workspace.
model <name>#Sets the default Codex model for future requests that do not override it.
reasoning minimal|low|medium|high|xhigh#Sets the default reasoning effort.
verbosity low|medium|high#Sets the default response verbosity.
approval untrusted|on-request|never#Sets the default Codex approval policy.
port <number>#Changes the local relay port and restarts services.
token rotate#Creates a new relay bearer token and restarts services.
restart#Restarts relay, agent, and Poke tunnel with the saved config.
help#Shows the command list.
quit#Stops Pokedex and closes the prompt.
Sandbox modes
read_only
Codex can analyze, plan, review, and answer without writing to the workspace. This is the first-run default.
workspace_write
Requires both global write mode and allowWrite on the selected workspace. Writes stay inside the workspace.
danger_full_access
Requires both global full-access mode and allowFullAccess on the selected workspace. Use it only where you deliberately trust the machine, project, and request.
Config file
Pokedex stores its config at ~/.pokedex/config.jsonc. The JSONC file contains the random relay token, default model settings, the global write and full-access gates, and the workspace list. Default local wiring, including port 4200, user local, and codex app-server --listen stdio://, stays internal unless you override it.
Troubleshooting
Inside the pokedex> prompt, help lists every command and logs shows recent relay, agent, and Poke tunnel logs.
Poke login does not complete
Log in to Poke manually, then start Pokedex again.
Codex cannot be found
Install the Codex CLI globally, then retry.
Codex is not logged in
Log in to Codex once, finish the browser flow, then start Pokedex again.
Notes
Pokedex is an independent, unofficial open-source project released under the MIT license. It is not affiliated with, endorsed by, sponsored by, or maintained by OpenAI, Poke, The Interaction Company of California Inc., or Interaction. Product names are used only to describe compatibility.
Users are responsible for their own OpenAI, Codex, Poke, and Interaction account terms. Pokedex redacts common secret patterns in logs and events it handles, but you should still treat prompts, tool outputs, and any advanced skill-path inputs as project data.