pixel

Pixel for Codex

pixel install puts Pixel’s protocol into the one key of Codex’s config that every Codex front end reads, and pixel install --repo adds a project guard.

Updated

Install Pixel

Pixel is a command-line tool: Codex runs the pixel binary, so install it first (macOS and Linux).

brew install LivioGama/tap/pixel

The install script is the other channel. Neither one changes any agent’s configuration.

What pixel install writes

pixel install

Run it once, from anywhere; it writes Codex’s files in $CODEX_HOME instead of ~/.codex when that variable is set. For Codex:

  • ~/.codex/config.toml
  • ~/.codex/hooks.json

The developer_instructions key of ~/.codex/config.toml, which every Codex front end reads, plus a metrics PostToolUse hook.

Every pixel install also deploys the prompt itself to ~/.local/share/pixel/agent-prompt.md and ~/.local/share/pixel/subagent-prompt.md, and wires the other agents it finds.

Or as a plugin

codex plugin marketplace add LivioGama/pixel, then codex plugin add pixel@pixel.

The plugin never installs the pixel binary. The protocol it loads starts by checking for it (command -v pixel) and tells the agent to work without Pixel’s commands when it is missing.

Per repository

pixel install --repo .

Adds an advisory guard to this repository only, and skips every global step. For Codex:

  • .codex/config.toml
  • .codex/hooks.json
  • .codex/pixel-composed-guard-backup.json

The guard steers the agent toward Pixel commands, for example with a notice before an untargeted read of a large source file, and never blocks a tool call. Every file that names this machine’s pixel binary goes into the clone’s .git/info/exclude, so a git add -A cannot publish it. Every per-repository file

Codex has no personal project file, so the guard is left out when Git tracks .codex/hooks.json: it would carry this machine's path into every clone.

Check it

pixel doctor .

pixel doctor . reports the wiring of every agent as green, stale or missing, and names the command that repairs each finding. For Codex alone:

pixel doctor . --only install.codex-config --only install.codex-metrics-hook --only repo.codex-config --only repo.codex-hooks

Remove it

pixel uninstall

It removes everything pixel install wrote, for every agent at once, and the binary at ~/.local/bin/pixel, where the install script puts it. A package manager removes its own copy: brew uninstall LivioGama/tap/pixel.

pixel uninstall --repo . removes only this repository’s files.

Pixel for other agents