Zest
Docs / Codex

Zest for Codex

Install from the Codex app or the CLI, then authenticate once.

Codex logo

Marketplace install: Use either the Codex App plugin manager or the Codex CLI command below. The ZIP download is kept as a temporary fallback for environments where Git marketplace install is unavailable.

Install

New to Zest? Step 7 opens your browser, where you can create your account. Free for 3 seats, no credit card.

Create a free account
  1. 1

    Add the marketplace from Codex App

    In Codex, open Plugins, click the dropdown next to the search input labeled Built by OpenAI, then choose Add Marketplace. Use Winding-Labs/zest-codex with Git ref main. Leave sparse paths empty.

    Source: Winding-Labs/zest-codex
    Git ref: main
  2. 2

    Or add the marketplace from Codex CLI

    From your terminal, run:

    codex plugin marketplace add Winding-Labs/zest-codex --ref main
  3. 3

    Install Zest

    Open the "Zest" marketplace in Codex and install "Zest" by clicking the + button, or install it directly from your terminal:

    codex plugin add zest@zest

    The GitHub ZIP remains available as a temporary fallback only.

    Download fallback ZIP
  4. 4

    Restart Codex

    Completely quit Codex and open it again. This refreshes the local plugin marketplace and loads the plugin.

  5. 5

    Trust the plugin's hooks

    Codex runs a plugin's hooks only once you trust them. Open the hooks list and trust Zest's: they keep your sign-in fresh and start the background sync when a session starts. Without them, sessions sync only when you ask.

    /hooks
  6. 6

    Verify the plugin

    In Codex, open the plugin manager and confirm "Zest" is installed or enabled from the "Zest" marketplace.

    /plugins
  7. 7

    Authenticate with Zest

    Trigger the login skill and follow the browser flow. You can also ask Codex naturally: "Log me into Zest".

    $zest:login
  8. 8

    Verify the MCP server

    Confirm the bundled MCP server is enabled. If Zest does not appear, restart Codex once more.

    /mcp
  9. 9

    Pick a permission mode that allows sync

    Codex's "Approve for me" mode runs an automatic safety reviewer that blocks Zest sync, because sync uploads your sanitized sessions to your own Zest account (an external service). If sync is denied with a high-risk message, open the permission selector at the bottom of the Codex composer and switch to "Ask for approval" — you will get a normal prompt you can approve — or "Full access". Both let sync run, and you can change it any time per session.

Check it works

Ask Codex for Zest's status, or run the status skill. It shows the plugin version, your sign-in and workspace, whether remote and background sync are on, the queue, whether this folder is tracked, and the next step when something is blocked.

$zest:status

What it captures

What it reads on your laptop

  • Codex's session logs in ~/.codex/sessions/ and their names in session_index.jsonl, from the CLI, the Codex app and the IDE extension.
  • Your plan, from the sign-in Codex keeps in ~/.codex/auth.json.

What it uploads

  • Your prompts and Codex's replies: their text only. When Codex logs a prompt together with the context it adds (such as your AGENTS.md), that text goes with it.
  • Each session's name, folder (org/repo from the git remote, or the folder name), git branch, models, token counts, context use and rate limits.
  • How many times each tool, skill and MCP server was used, and how many images, as counts.
  • Whether the session ran in the Codex app or in a terminal.

When it syncs

When a Codex session starts, and on every prompt, the plugin's hooks refresh your sign-in and make sure the background process is running. Every 60 seconds it uploads the new messages of every session active today, from the CLI, the app or the IDE; a session you resume today uploads in full. Sessions from earlier days are never uploaded. The process stops after 10 minutes without activity. Your first sign-in imports up to 10 of today's sessions.

What stays on your laptop

  • Secrets. Every text field is checked against 74 patterns (API keys, tokens, passwords, private keys, email addresses and more) and a match is replaced with [REDACTED] before it leaves your laptop. The API runs the same patterns again. The patterns.
  • Text your workspace does not collect. If you or an admin turned off prompts or agent replies in Settings → Privacy, that text is left out of the upload.
  • Code diffs and file contents, tool calls and their output, web searches, and Codex's reasoning.
  • Subagent sessions.
  • Full paths: only the folder name or org/repo.
  • Folders you ignore. A session with no folder is never ignored.

Where the data goes

To the Zest API at /api only, over HTTPS, with this plugin's own device token. The API checks it and stores it under your workspace. How Zest works · how the token is kept.

Besides Zest:

  • No analytics. When an update is out, the plugin runs codex plugin marketplace upgrade zest itself, at most once a day; set ZEST_CODEX_AUTOUPDATE_DISABLED to stop it.

Pause, sign out, uninstall

Pause syncing

$zest:disable-remote-sync

Sessions are still collected on your laptop and nothing uploads, until $zest:enable-remote-sync. $zest:disable-background-sync also stops the background process.

Ignore a folder

$zest:ignore

Ignores the folder you name, or the current session's. $zest:unignore undoes it.

Sign out

$zest:logout

Revokes the token on the server and erases it from ~/.codex-zest/auth/zest2-auth.json. The queue stays.

Uninstall

codex plugin remove zest@zest

Then delete ~/.codex-zest.

Troubleshooting

Sessions sync only when you ask

The plugin's hooks are not trusted, so nothing starts the background process. Open the hooks list in Codex and trust Zest's, then start a new session.

/hooks

Sync is denied with a high-risk message

Codex's “Approve for me” mode blocks uploads to an outside service. Switch the permission selector under the composer to “Ask for approval” or “Full access”.

Zest's skills are missing

Quit Codex completely and open it again, then check /plugins and /mcp for Zest.

Codex in Zest

Codex analytics shows what Zest does with these sessions, per engineer and per team.