codex-toys/docs/pages/guides/install-codex-plugin.md

title	description
Install the Codex plugin	Install codex-toys skills and hooks from a Git-backed Codex plugin marketplace.

Install the Codex plugin

The preferred way to install codex-toys toybox guidance and passive lifecycle hooks is the shared Peezy Tech Codex plugin marketplace. Source definitions live in this repository; release syncs installable plugin bundles into peezy-tech/skills.

The repository root also remains a product-local plugin marketplace for development, with a full plugin plus granular install options:

.codex-plugin/plugin.json
.agents/plugins/marketplace.json
plugins/codex-toys-author/
plugins/codex-toys-local-workspace/
plugins/codex-toys-remote-control/
skills/
hooks/hooks.json
hooks/hook-event.mjs

Plugin	Installs
codex-toys-author	Turn automation authoring guidance.
codex-toys-local-workspace	Local toybox operation guidance and plugin-bundled hooks.
codex-toys-remote-control	Local Codex App guidance for SSH toybox preflight, remote automation, turns in remote workspaces, and proxy dashboards.
codex-toys	Product-local full install for development and compatibility.

Install from GitHub

In Codex App, open Plugins, choose Add marketplace, enter peezy-tech/skills or https://github.com/peezy-tech/skills, then install the plugin you need from the peezy-tech marketplace. Start a new thread so the plugin skills and hooks are loaded.

The same install can be done from a Codex CLI that shares the same CODEX_HOME:

codex plugin marketplace add peezy-tech/skills --ref main
codex plugin add codex-toys-author@peezy-tech
codex plugin add codex-toys-remote-control@peezy-tech
codex plugin add codex-toys-local-workspace@peezy-tech
codex plugin add codex-toys@codex-toys

Local Development

Before publishing or while iterating locally, add the checkout root instead:

codex plugin marketplace add /home/peezy/repos/codex-toys
codex plugin add codex-toys@codex-toys
codex plugin add codex-toys-local-workspace@codex-toys

After changing plugin metadata or skills, reinstall the plugin and start a new thread to pick up the updated skill and hook list.

Hook Surface

The local workspace and full plugins use Codex's native plugin hook discovery. The hook config stays inside the plugin at hooks/hooks.json; it is not copied into ~/.codex/hooks.json.

Make sure plugin hooks are enabled in the Codex home that runs the workspace:

[features]
plugins = true
hooks = true
plugin_hooks = true

The bundled hook command is:

node "${PLUGIN_ROOT}/hooks/hook-event.mjs"

Codex expands ${PLUGIN_ROOT} from the installed plugin bundle. The command is self-contained and writes lifecycle events into the hook spool used by workspace surfaces. Override the spool with CODEX_TOYS_HOOK_SPOOL_DIR.

Local Agent

Plugin install does not start a long-running process. Normal CLI and MCP calls spawn the toybox as needed:

codex-toys fetch
codex-toys workspace doctor
codex-toys workspace methods
codex-toys functions list --json
codex-toys automation list --json
codex-toys turn run "Check workspace status" --wait

Start the toybox explicitly only when another process needs stdio JSON-RPC:

codex-toys toybox serve --cwd /repo

SSH Agent

For remote workspaces, keep the command local and run the toybox over SSH stdio:

codex-toys --ssh <user@tailscale-host> --cwd /repo remote preflight
codex-toys --ssh <user@tailscale-host> --cwd /repo fetch
codex-toys --ssh <user@tailscale-host> --cwd /repo turn run "Check workspace status" --wait
codex-toys --ssh <user@tailscale-host> --cwd /repo automation run check-release --event event.json

Useful remote defaults:

CODEX_TOYS_REMOTE_SSH_TARGET=<user@tailscale-host>
CODEX_TOYS_REMOTE_CWD=/repo
CODEX_TOYS_REMOTE_PATH_PREPEND=/home/user/.local/bin:/home/user/.bun/bin
CODEX_TOYS_TOYBOX_COMMAND=codex-toys
CODEX_TOYS_REMOTE_CODEX_COMMAND=codex

Dashboard Proxy

For browser dashboards, opt into HTTP explicitly:

codex-toys-proxy serve --cwd /repo --static ./dashboard
codex-toys-proxy serve --ssh <user@tailscale-host> --cwd /repo --static ./dashboard

Plain HTML/JS can call:

GET  /api/status
GET  /api/schema
POST /api/rpc
POST /api/app/:method
POST /api/workspace/:method

The proxy schema is derived from the toybox's available workspace methods.