Pokedex Documentation

Pokedex exposes real pokedex_* MCP tools to Poke and runs a local prompt for managing the bridge.

Installation

Two steps. That's the whole install.

1

Add the recipe in Poke

One tap. The recipe gives Poke the pokedex_* MCP tools — it does not give Poke shell or filesystem access.

Add recipe in Poke

2

Run the bridge in your project

One command, inside the project Codex should see. Keep the terminal open while you use Poke.

npx codex-to-poke

The package is published on npm as codex-to-poke. Config is saved at ~/.pokedex/config.jsonc, and the first run stores the current folder as the main workspace. Source code is on GitHub.

Setup, workspaces & skills

First-contact tools: check that the bridge is healthy, see which workspace aliases exist, 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.

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.

Review, goals & output

Run reviews, manage long-running goals, and read diffs and token usage from allowed workspaces.

#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 the latest token usage Pokedex has seen from a completed local Codex turn.

Approvals

When Codex pauses for approval — for a command or a 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 approves for the whole session.

#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, images, 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.

#imagePaths

Optional list of local image paths attached to the turn.

#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 3000.

#--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 interactive commands it also lists are documented in the next section). The same text appears with help inside the pokedex> prompt.

pokedex
Local Poke to Codex bridge.

usage
  pokedex [--workspace .] [--port 3000] [--write] [--read-only]
  pokedex help

config
  ~/.pokedex/config.jsonc

common
  npx codex-to-poke
  npx codex-to-poke --write
  npx codex-to-poke --read-only

Local prompt commands

Everything you can type at the pokedex> prompt while the bridge is running — the same list the help command prints.

#status

Shows relay, agent, and Poke tunnel status, the MCP URL, the active workspace, and the access mode.

#config

Prints the saved JSONC config with secrets hidden.

#output [relay|agent|poke]

Shows recent logs for one service, or all services when omitted.

#write <on|off>

Sets write permission for the active workspace.

#full-access <on|off>

Sets full filesystem access for the active workspace. Enabling it also enables write.

#workspace list

Shows configured workspaces and marks the active one.

#workspace add <alias> <path> [description]

Adds or updates a workspace alias for a local path.

#workspace remove <alias>

Removes a workspace alias. The last workspace cannot be removed.

#workspace use <alias>

Makes a workspace active. Run restart to apply it to the running stack.

#workspace describe <alias> <description>

Changes the human-readable workspace description.

#workspace write <alias> <on|off>

Sets write permission for one workspace.

#workspace full-access <alias> <on|off>

Sets full access 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 — port 3000, user local, and codex app-server --listen stdio:// — stays internal unless you override it.

Troubleshooting

Inside the pokedex> prompt, help lists every command and output shows recent relay, agent, and Poke tunnel logs.

Poke login does not complete

Log in to Poke manually, then start Pokedex again.

npx poke@latest login

Codex cannot be found

Install the Codex CLI globally, then retry.

npm install -g @openai/codex@latest

Port 3000 is busy

Start the bridge on another local port.

npx codex-to-poke --port 3010