Zinn for Codex

Inspect local Zinn tasks alongside a Codex desktop conversation and move reviewed tasks to another column. The plugin provides manual task lookup, full descriptions, comments, relation navigation and observed task references from the current chat. Optional hooks supply execution identity for direct Zinn commands.

The source builds version 0.1.0 as a candidate in a self-contained local marketplace. The plugin includes its runtime JavaScript and inspector assets.

Requirements

• Codex desktop with local plugin marketplaces, lifecycle hooks and MCP Apps conversation panels.
• Node.js 24.15.0 or newer and Zinn CLI 0.44.0 or newer on the app’s PATH.
• An existing Zinn database that the installed CLI can read.
• Node to run the built plugin, and (optionally) Bun to build the plugin.

The inspector and hook verification use ordinary CLI read commands with the host user’s permissions. Normal database compatibility rules apply, including backups and automatic upgrades when the CLI opens an older database. Current-schema reads leave task data and activity unchanged. SQLite manages its normal WAL coordination files.

The packaged Node backend is tested on macOS, Linux and Windows. Identity command rewriting uses Unix shell syntax.

Configured CLI executables are trusted local programs. The hook writes its own reference files.

Select the database

Default-store setup needs no plugin configuration file. The plugin runs zinn info --json from your home directory to resolve the database location. It honors ZINN_DIR inherited by Codex and the CLI’s settings in that context, including global storage selection. Without an override, Zinn uses ~/.zinn.

The inspector keeps that selected directory until it restarts. It checks CLI compatibility with --version before reading tasks. Restart Codex after changing its environment or storage settings.

Agent commands use their own working directory, CLI settings and ZINN_DIR. Their selected database can differ from the inspector’s. Set ZINN_DIR in Codex’s environment when inspection should use a custom directory.

For plugin-specific options, create the optional ~/.zinn/integrations/codex.json. This location stays in your home directory even when ZINN_DIR selects a different store. An explicit store selects inspection and reference verification independently of agent commands:

			
				
						
						{
	"store": "/absolute/path/to/.zinn"
}
					
			
		

An options file can omit store and use ordinary discovery. To select another file, set ZINN_CODEX_CONFIG in Codex’s environment to its absolute path. The plugin reads that file exclusively. Otherwise, it reads ~/.zinn/integrations/codex.json, falling back to an existing ~/.config/zinn/codex.json only when the new path is absent.

Only one options file is read. Files are never merged or moved automatically. Missing implicit files use the defaults. An explicitly selected file must exist, and any selected file must be readable and valid. A configuration error stops loading without trying another file.

If the desktop app cannot find zinn, use the executable’s absolute path:

			
				
						
						{
	"cli": ["/absolute/path/to/zinn"]
}
					
			
		

cli is an array containing the executable and any fixed arguments. The app must also be able to find node on its PATH.

Build and install

From a Zinn source checkout:

			
				
						$ 
						bun install --cwd integrations/codex --frozen-lockfile
					
						$ 
						bun run codex:build
					
						$ 
						codex plugin marketplace add ./integrations/codex/dist
					
			
		

Open Codex’s Plugins browser, choose the Zinn marketplace and install Zinn. Review and trust the plugin’s hook definitions when Codex requests it, then start a new chat. Installing or enabling a plugin does not automatically trust its hooks. See OpenAI’s plugin setup guide.

For an already built marketplace, register the extracted marketplace root instead:

			
				
						$ 
						codex plugin marketplace add /absolute/path/to/zinn-codex
					
			
		

Keep the extracted directory available as the marketplace source. Codex manages the installed copy. The built folder contains .agents/plugins/marketplace.json and plugins/zinn, including the manifest, hooks, MCP configuration, bundled scripts, HTML and license notices.

bun run codex:package builds the marketplace and writes zinn-codex-0.1.0.tar.gz and its SHA-256 file to integrations/codex/release-dist. The archive includes a zinn-codex marketplace root. Consumers can extract and register it without installing build dependencies.

Inspect tasks

In a chat, open a new side tab, choose More tools, then Plugins and MCPs, and open Zinn task inspector. Launcher labels can vary by Codex version.

Enter a task key from your database, such as APP-1. Task descriptions and comments are displayed as literal text, preserving line breaks. Select a relation to open the related task. Refresh reads the selected task and current-chat references again.

Opening a task through lookup, an observed reference or a relation remembers its key for the current chat and selected database directory. Reopening the panel reads that task’s current contents. A missing task keeps its selected key so you can retry or open another task. An explicit task key supplied when opening the panel takes precedence over the remembered selection.

Selection is remembered only when the host identifies the chat unambiguously. Manual lookup remains available otherwise. A failed selection save leaves task inspection available and reports that the selection could not be remembered. Invalid lookup input and task-read errors preserve the previously remembered key.

For an active task, choose a destination and select Move to…. The initial destination is the project’s first column with the done category, or the task’s current column when the project has none. The move uses the inspector’s selected database and the task’s own project. It follows ordinary zinn task move behavior and refreshes the task afterward. Moving to the current column leaves it unchanged. Archived tasks remain available for inspection.

Panel moves record your normal CLI human identity, without inherited agent, model, effort, client or conversation declarations. The plugin declares zinn-codex/0.1.0 after any inherited client chain on CLI runs it starts, so a panel move records that token in actor_client and zinn activity list --client zinn-codex selects it. Codex’s tool permission settings apply. A move is submitted only by the explicit button action and is not automatically retried after a failure.

Observed references come from supported direct CLI calls, task keys in agent dispatches and completed replies. A reference is an observation, rather than a task assignment or proof that the task changed. References refresh every five seconds while the panel is visible, keeping the selected task open. Task details are re-read when opened or refreshed.

References with a relative ZINN_DIR are recorded when the command’s working directory can be established.

Each request uses the host’s current chat metadata. Manual lookup remains available when that metadata is absent or conflicting. Completed-reply keys are checked against the selected store. A missing key is retained as a warning when its project prefix is represented by tasks in that store.

Panel reads can wait for another process or an automatic upgrade to finish. Cancelling a request or closing the backend stops its CLI child. Periodic refresh waits for the pending reference read to complete.

Hook settings

The configuration accepts these options:

Use absolute paths in JSON. The default data path is resolved from the user’s home directory. ZINN_CODEX_CONFIG can select a different absolute configuration-file path when it is set in the host’s environment.

Identity capture handles one literal direct zinn command, or the configured CLI invocation. It appends zinn-codex/0.1.0 after any inherited client chain. It leaves compound shell commands and shell expansions unchanged. Explicit ZINN_AGENT, ZINN_MODEL, ZINN_EFFORT and ZINN_CLIENT assignments in that command take precedence. Unknown values clear inherited hook attribution for that command. Codex requires a PreToolUse allow response to accept rewritten input. The plugin uses that response and does not register a PermissionRequest hook. Review its definitions before trusting them. See Codex hooks. Zinn records activity only when the CLI operation makes a change.

With captureEffort: true, effort is supplied only when the transcript’s thread, turn and model match the callback and exactly one matching turn context exists. Missing, partial, oversized or ambiguous metadata leaves effort unknown. Duplicate contexts can occur after compaction. See CLI actor identity for the recorded fields.

To stop reference recording and identity capture, set both observe and identity to false. To keep recording references and disable identity capture, set only identity to false. These settings take effect on the next hook invocation. Previously recorded references remain available until their files are removed.

These hook settings do not disable the panel’s remembered selection.

Optional reply and dispatch verification shares a short deadline across CLI compatibility, info --json and task lookup. It proceeds when the schema is current. Unavailable completed-reply verification is recorded separately. Execution identity remains independent. The schema check is best effort because another client can replace or restore the database before the following read.

Local data and privacy

The observer writes task keys, their source, selected-store paths, chat IDs and timestamps. It processes shell text, dispatch text and completed replies in memory to find those keys. The reference files contain this metadata rather than command arguments, prompts, replies or task contents. Effort capture processes the callback’s transcript file in memory and retains no transcript copy.

Each chat has at most 1,024 reference records of at most 16 KiB each. Reaching that limit is reported by the inspector. Reference data persists across plugin upgrades and has no automatic expiry. Disable observation and remove the integration’s hashed chat subdirectories to clear only reference records. With the default dedicated directory, remove ~/.local/share/zinn-codex to clear all local integration state.

The panel keeps one selection record per chat and canonical selected-store path in dataDirectory/selections. Each record contains only a format version and task key. Its filename hashes the chat and store scope. Task contents and drafts are fetched or held in memory rather than saved in these records. Selection state survives normal app restarts and plugin upgrades, has no automatic expiry and remains after uninstall. Stop the plugin and remove only its selections subdirectory to clear remembered selections while keeping reference records. Restoring or replacing a database at the same path keeps the same selection scope and reads the task key against the current database.

The plugin uses local STDIO and has no hosted server. Task data returned through the native panel passes through Codex. Your host’s data-handling settings and policies apply. Keep database files, transcripts and reference files out of public support reports.

Update, disable and remove

Build the selected source version again, or extract a new versioned marketplace archive. Refresh the source and update or reinstall Zinn through Codex’s Plugins browser. Restart Codex only if refreshed changes do not appear. Keep codex.json and the reference directory outside the plugin folder. Review changed hook definitions again when requested.

Disable Zinn in the Plugins browser to stop loading it. Uninstall it there to remove the installed plugin. Remove the marketplace source with:

			
				
						$ 
						codex plugin marketplace remove zinn
					
			
		

Your Zinn database, configuration, reference files and selection records remain under your control. Remove the dedicated integration data directory separately if you want to clear its metadata. To roll back, register the previous built marketplace and reinstall that version.

Troubleshooting and compatibility

For startup failures, check the configuration path, absolute store path, app PATH, Node version and CLI version. Run the configured CLI’s zinn info --json equivalent with the same ZINN_DIR to check database compatibility.

For an empty recent list, check hook trust and observe, then mention a real task key in a completed reply or run a direct CLI lookup. Failed verification is reported separately from a missing task. A newly created task becomes available on the next refresh.

The backend uses Node and ordinary CLI commands. Native plugin, hook and panel behavior also depends on the Codex host and operating system. Verify native opening, hook trust, references, update and removal when adopting a new host version. Report the plugin, Codex, Node and CLI versions through Contact.