{"id":50669889,"url":"https://github.com/minghinmatthewlam/codex-zig-port","last_synced_at":"2026-06-08T10:02:57.325Z","repository":{"id":356846431,"uuid":"1234289960","full_name":"minghinmatthewlam/codex-zig-port","owner":"minghinmatthewlam","description":"Independent Zig reimplementation of the Codex CLI","archived":false,"fork":false,"pushed_at":"2026-06-04T22:56:54.000Z","size":8672,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T23:10:52.985Z","etag":null,"topics":["cli","codex","developer-tools","openai","tui","zig"],"latest_commit_sha":null,"homepage":"https://github.com/minghinmatthewlam/codex-zig-port/tree/main/docs","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minghinmatthewlam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T01:47:44.000Z","updated_at":"2026-05-20T18:40:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/minghinmatthewlam/codex-zig-port","commit_stats":null,"previous_names":["minghinmatthewlam/codex-zig-port"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/minghinmatthewlam/codex-zig-port","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minghinmatthewlam%2Fcodex-zig-port","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minghinmatthewlam%2Fcodex-zig-port/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minghinmatthewlam%2Fcodex-zig-port/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minghinmatthewlam%2Fcodex-zig-port/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minghinmatthewlam","download_url":"https://codeload.github.com/minghinmatthewlam/codex-zig-port/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minghinmatthewlam%2Fcodex-zig-port/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34057158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","codex","developer-tools","openai","tui","zig"],"created_at":"2026-06-08T10:02:53.472Z","updated_at":"2026-06-08T10:02:57.318Z","avatar_url":"https://github.com/minghinmatthewlam.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Zig Port\n\n[![CI](https://github.com/minghinmatthewlam/codex-zig-port/actions/workflows/ci.yml/badge.svg)](https://github.com/minghinmatthewlam/codex-zig-port/actions/workflows/ci.yml)\n\nThis repository is an independent Zig reimplementation of the Codex CLI.\nA local Rust Codex checkout can be used as a behavioral reference only:\nruntime code in this repository must not import, link to, shell out to, or copy\nsource from the original implementation.\n\nThis is an unofficial project and is not affiliated with or endorsed by OpenAI.\n\n## Open Source Status\n\nThis repository is public under the MIT License. It is pre-release software:\nmany surfaces are intentionally marked partial until they are implemented and\nverified against the real CLI, TUI, or app-server behavior.\n\nContributions should follow `CONTRIBUTING.md`, security reports should follow\n`SECURITY.md`, and conduct expectations are in `.github/CODE_OF_CONDUCT.md`.\nDo not include real credentials, `auth.json`, private prompts, or local session\ntranscripts in public issues or pull requests.\nThe current public-readiness audit is tracked in `docs/oss-readiness.md`; the\nmanual release process is tracked in `docs/release.md`.\n\n## First Milestone\n\nThe first demo slice targets macOS and focuses on the interactive CLI surface:\n\n- launch an interactive terminal UI with `zig build run`\n- accept an optional initial prompt with `codex-zig [PROMPT]`\n- use alternate-screen terminal mode by default and preserve inline scrollback\n  with the Rust-compatible `--no-alt-screen` flag\n- attach local image files to the first interactive prompt with `-i/--image`\n- reuse local Codex auth from `$CODEX_HOME/auth.json` or `~/.codex/auth.json`\n- refresh expired or stale ChatGPT auth tokens from stored refresh tokens\n- manage basic auth with `login status`, `login --with-api-key`,\n  `login --with-access-token`, `login --device-auth`, and `logout`\n- send a Responses API turn\n- stream assistant text deltas in the interactive TUI\n- set the `priority` service tier for later turns with `/fast`\n- include discovered `AGENTS.md` project instructions in API turns\n- create a repository guide through interactive `/init`\n- compact an interactive session into a continuation summary with `/compact`\n- inspect effective interactive configuration and local config source status with `/debug-config`\n- inspect current built-in key bindings with `/keymap`\n- toggle plan-only prompts with `/plan`\n- render plan-mode `\u003cproposed_plan\u003e` blocks without leaking markup\n- manage ordered terminal-title items with `/title`\n- configure status-line preview items with `/statusline`\n- choose a syntax theme with `/theme`\n- select a communication personality with `/personality`\n- set and persist the current thread title with `/rename`\n- enable native Responses web search with `--search` or `web_search = \"live\"`\n- accept modern `exec_command` tool calls for one-shot command execution and\n  PTY-backed `write_stdin` session input, including Rust-shaped yield bounds\n  and `background_terminal_max_timeout`\n- accept `update_plan` tool calls and surface task progress in the TUI\n- run explicit local TUI shell commands with `!COMMAND`\n- execute basic `shell` / `shell_command` tool calls after user confirmation\n- run a command through the macOS Seatbelt sandbox with `sandbox macos`,\n  including Rust built-ins and supported custom `[permissions]` profiles\n  for parsed Seatbelt-only socket/denial flags\n- check `prefix_rule` execpolicy files against a command with\n  `execpolicy check`, including `match` / `not_match` examples,\n  `network_rule` validation, and absolute host executable resolution\n- apply focused `apply_patch` file edits after user confirmation\n- discover and execute configured stdio and streamable HTTP MCP tools as\n  `mcp__server__tool` calls, including streamable HTTP MCP session-id reuse and\n  configured static/env HTTP headers, JSON-RPC responses delivered over GET SSE\n  streams after accepted POSTs, plus best-effort session teardown\n- expose model-facing `list_mcp_resources`, `list_mcp_resource_templates`, and\n  `read_mcp_resource` tools for configured stdio and streamable HTTP MCP\n  servers\n- copy the last assistant response from the interactive TUI with `/copy`\n- toggle copy-friendly transcript output from the interactive TUI with `/raw`\n- toggle the in-memory Vim composer mode indicator with `/vim`\n- include file contents in the next interactive prompt with `/mention`\n- ask a question in an ephemeral fork with `/side`\n- inspect configured MCP servers from the interactive TUI with `/mcp`\n- accept app-server MCP config reload requests and list server status with\n  `config/mcpServer/reload` and `mcpServerStatus/list`, including enabled\n  local plugin-cache `.mcp.json` server entries plus raw stdio and streamable\n  HTTP tool, resource, and resource-template inventory plus streamable HTTP\n  bearer-token, file-backed OAuth, and OAuth-discovery not-logged-in auth state\n- read resources with and without loaded thread IDs, and call tools on\n  configured stdio and streamable HTTP MCP servers through app-server\n  `mcpServer/resource/read` and `mcpServer/tool/call`, including streamable\n  HTTP configured static/env headers, GET SSE responses after accepted POSTs,\n  and forwarded MCP JSON-RPC error code/message/data payloads\n- bridge stdio MCP `elicitation/create` requests raised during app-server\n  `mcpServer/tool/call` and model-triggered `turn/start` MCP tool calls through\n  `mcpServer/elicitation/request` plus `serverRequest/resolved`\n- complete app-server MCP OAuth login requests with `mcpServer/oauth/login`,\n  including generated completion notification artifacts, Rust-shaped\n  configured-server checks, PKCE browser callback handling, credential storage,\n  and completion notifications over stdio, Unix-socket, and websocket transports\n- complete CLI MCP OAuth login requests with `codex-zig mcp login`, including\n  configured-server, streamable HTTP, comma-separated scope checks, metadata\n  discovery, dynamic client registration, PKCE browser callback handling,\n  token exchange, fallback credential writes, and retry without scopes when a\n  provider rejects metadata-discovered scopes\n- remove file-backed and macOS keychain-backed MCP OAuth credentials for\n  streamable HTTP servers with `codex-zig mcp logout`\n- report bearer-token, file-backed OAuth, macOS keychain-backed OAuth, and\n  OAuth-discovery not-logged-in state from `codex-zig mcp list`\n- list local app-server plugin marketplaces with `plugin/list`, including\n  repo/home marketplace manifests, manifest metadata, and installed/enabled\n  state from `$CODEX_HOME`\n- list remote app-server plugin marketplaces with `plugin/list`, including\n  ChatGPT global, workspace directory, and shared-with-me catalog sources\n- read local app-server plugin details with `plugin/read` for marketplace-backed\n  local plugins, including summary metadata, manifest description, skills,\n  hooks, app ids, and MCP server names\n- install local and git-backed app-server plugins with `plugin/install`,\n  including cache copy, Rust-compatible git source normalization, git-subdir\n  sparse checkout, config enablement, and Rust-shaped auth-policy responses\n- install remote app-server plugins with `plugin/install`, including bundle\n  download, versioned cache writes, cloud install mutation, and Rust-shaped\n  auth-policy responses\n- read remote app-server plugin details with `plugin/read`, including catalog\n  metadata, installed/enabled state, disabled remote skills, app ids, and\n  remote source summaries\n- read remote app-server plugin skill Markdown with `plugin/skill/read`\n- create, list, retarget, and delete remote app-server plugin shares with\n  `plugin/share/save`, `plugin/share/list`, `plugin/share/updateTargets`, and\n  `plugin/share/delete`\n- uninstall local and remote app-server plugins with `plugin/uninstall`,\n  including local cache/config cleanup and remote cloud mutation\n- run a stdio MCP server with `codex` and `codex-reply` tools plus per-call\n  Rust-shaped tool schemas, `model`, `cwd`, `approval-policy`, `sandbox`,\n  `base-instructions`, `developer-instructions`, `compact-prompt`, and\n  supported `config` object overrides\n- run a minimal exec-server stdio/websocket JSON-RPC transport with a Rust-shaped\n  `initialize` handshake, detached websocket `resumeSessionId` reconnects,\n  pipe-backed and macOS PTY-backed `tty`\n  `process/start` / `process/read` / `process/write` / `process/terminate`\n  lifecycle, `envPolicy`-based child environment filtering and overlays, Unix\n  `arg0` process titles, filesystem read/write/mkdir/metadata/list/copy/remove\n  RPCs with supported filesystem sandbox contexts, buffered executor-side\n  `http/request` RPCs for built-in HTTP methods with buffered and streamed\n  timeout handling plus streamed response body-delta notifications over stdio\n  and websockets,\n  registry-backed remote executor registration through `--remote` /\n  `--executor-id` with bearer-token auth plus local `ws://` and loopback\n  self-signed or public-CA `wss://` rendezvous serving\n- run a minimal app-server JSON-RPC transport over stdio or Unix sockets with\n  an `initialize` handshake, keeping Unix socket listeners alive for sequential\n  clients\n- generate minimal app-server TypeScript bindings and JSON Schema bundles with\n  `app-server generate-ts -o DIR [--experimental]` and\n  `app-server generate-json-schema -o DIR [--experimental]`, including\n  command-exec request, response, follow-up, and output-delta notification\n  shapes in the public generated artifacts, plus the hidden internal\n  `RolloutLine.json` schema with\n  `app-server generate-internal-json-schema -o DIR`\n- handle app-server filesystem JSON-RPC methods for read, write, mkdir,\n  metadata, directory listing, remove, and copy\n- watch app-server filesystem mutations and request-boundary external file\n  changes with `fs/watch`, `fs/unwatch`, and `fs/changed` notifications on the\n  same JSON-RPC connection\n- answer app-server model catalog and provider-capability JSON-RPC methods\n- compute legacy app-server `gitDiffToRemote` responses against a remote branch\n- answer legacy app-server `fuzzyFileSearch` requests with local file and\n  directory matches plus connection-local `fuzzyFileSearch/session*`\n  notifications\n- report app-server account state with `account/read` for no-auth, API-key,\n  ChatGPT, Bedrock, custom no-auth provider, and local-OSS cases\n- report legacy app-server auth status with `getAuthStatus`\n- start app-server API-key and external ChatGPT-token login with\n  `account/login/start`, respect forced account-login config, and emit account\n  login/update notifications\n- refresh external ChatGPT app-server auth tokens on Responses `401` with\n  `account/chatgptAuthTokens/refresh`, persist the returned token, and retry\n  the turn, with bounded failure handling when clients reject or do not answer\n  the refresh request\n- expose model-facing `get_goal`, `create_goal`, and `update_goal` tools during\n  app-server loaded-thread turns when `[features].goals` is enabled, backed by\n  the same transcript-persisted loaded-thread goal state as `thread/goal/*`\n- handle app-server login cancellation requests with `account/login/cancel`\n- read app-server account rate limits with `account/rateLimits/read`\n- notify workspace owners about credit or usage-limit issues with\n  `account/sendAddCreditsNudgeEmail`\n- remove app-server auth with `account/logout` and emit `account/updated`\n- read app-server config basics plus effective feature flags, user\n  config-origin/layer metadata, user sandbox workspace settings, user tools\n  and apps config including app defaults, forced account-login config, policy\n  flags, and per-app tool overrides, trusted project-stack scalar, tool, app,\n  and sandbox workspace layers, system scalar/tool/app/sandbox workspace\n  precedence, required empty user/system layers, and legacy managed\n  scalar/tool/app/sandbox overrides with `config/read`\n- write app-server config scalar, array, object, and null-clearing values with\n  `config/value/write`\n- merge and replace existing app-server TOML table objects with\n  `config/value/write`\n- apply multiple app-server config edits in one file write with\n  `config/batchWrite`, including table-object merge/replace behavior\n- report absent, system `requirements.toml`, and legacy managed config\n  requirements with `configRequirements/read`, including system feature and\n  managed hook requirements, residency requirements, plus network scalar,\n  domain, and socket requirements\n- clear memory directories and SQLite memory-state rows with `memory/reset`\n- list app-server collaboration mode presets with `collaborationMode/list`\n- list app-server experimental feature metadata and patch process-local runtime\n  feature enablement\n- proxy stdio JSON-RPC to the app-server Unix control socket with\n  `app-server proxy`\n- accept Rust-compatible app-server `--analytics-default-enabled`, run plain\n  websocket JSON-RPC, reject Origin-bearing websocket requests, and enforce\n  websocket capability-token auth from `--ws-token-file` or `--ws-token-sha256`\n  plus HS256 signed-bearer auth with exp/nbf/issuer/audience validation, keeping\n  websocket listeners alive for sequential clients with connection-local state\n  reset\n- apply the latest PR diff from a Codex agent task with `apply` / `a`\n- send tool output back to the model\n- review current changes from the interactive TUI with `/review`\n- run narrow non-interactive `review --uncommitted`, `review --base`, and\n  `review --commit` flows, plus custom review instructions from argv or stdin,\n  including Rust-compatible `exec review` dispatch with exec-level `--cd`\n  handling, post-`review` model/config/feature overrides, JSONL events, and\n  last-message output files\n- run non-interactive `exec` prompts from argv, explicit `-`, or piped stdin,\n  including prompt-plus-piped-context requests\n- enforce Rust-compatible non-interactive `exec` and `review` Git-repository\n  checks, with `--skip-git-repo-check` and dangerous bypass exceptions on\n  `exec`, including for `exec review`\n- reject conflicting approval-policy flags when dangerous bypass mode is set\n- inspect known feature flags with `features list`\n- enable or disable known feature flags and Rust legacy aliases for one\n  invocation with root `--enable/--disable` or exec-local `--enable/--disable`,\n  including `exec --disable shell_tool` request-tool filtering\n- persist feature flags and Rust legacy aliases globally or per profile with\n  `features enable|disable`, including Rust-like root clearing for default-off\n  flags, under-development warnings for direct root enables, and app-server\n  startup warnings for config-enabled under-development features plus\n  deprecation notices for legacy feature keys\n- emit app-server startup deprecation notices for\n  `experimental_instructions_file`\n- emit app-server startup warnings for deprecated `on-failure` approval-policy\n  configuration\n- emit app-server startup warnings for user/plugin hook-load warnings\n- emit app-server `initialize` config warnings when project-local `.codex`\n  config, hooks, and exec policies are disabled until the project is trusted,\n  for ignored unsupported project-local config keys, and for malformed user or\n  trusted project-local execpolicy rules\n- emit app-server `turn/plan/updated` notifications when `turn/start` runs a\n  model-requested `update_plan` tool call\n- emit app-server `turn/diff/updated` notifications when `turn/start` runs a\n  successful model-requested `apply_patch` edit in a git-backed loaded thread\n  cwd\n- emit app-server `item/fileChange/patchUpdated` notifications when\n  `turn/start` runs successful model-requested `apply_patch` edits\n- emit app-server `item/commandExecution/outputDelta` notifications when\n  `turn/start` runs model-requested shell tools\n- emit app-server `item/commandExecution/terminalInteraction` notifications\n  when `turn/start` writes stdin to model-started terminal sessions\n- clean model-started app-server PTY sessions through\n  `thread/backgroundTerminals/clean` for clients with `experimentalApi`\n- require `initialize.params.capabilities.experimentalApi` for implemented\n  Rust experimental app-server request methods, including `memory/reset`,\n  `thread/goal/*`, `thread/memoryMode/set`, `thread/turns/list`,\n  `thread/realtime/*`, `thread/backgroundTerminals/clean`, `process/*`,\n  `collaborationMode/list`, and `fuzzyFileSearch/session*`\n- require `initialize.params.capabilities.experimentalApi` for implemented\n  Rust experimental app-server request fields on `thread/start`,\n  `thread/resume`, `thread/fork`, `turn/start`, `turn/steer`,\n  `command/exec`, and `account/login/start`\n- suppress implemented Rust experimental app-server server notifications,\n  including `thread/goal/*` and `process/*`, until the client enables\n  `experimentalApi`\n- emit app-server `remoteControl/status/changed` after `initialize` with the\n  current disabled remote-control status, honoring notification opt-out\n- emit app-server `app/list/updated` after `experimentalFeature/enablement/set`\n  enables `apps`, using the current local plugin app catalog and honoring\n  notification opt-out\n- run app-server `review/start` inline and detached reviews for loaded threads,\n  including Rust-shaped target validation, read-only review runtime\n  constraints, configured `SessionStart` / `UserPromptSubmit` hook handling for\n  inline reviews, detached review thread starts, `ReviewStartResponse` display\n  turns, structured review output rendering, and `review_model` request routing\n- include experimental `permissionProfile` and `activePermissionProfile`\n  fields on `thread/start`, `thread/resume`, and `thread/fork` responses only\n  after the client enables `experimentalApi`\n- emit app-server `rawResponseItem/completed` notifications for raw Responses\n  output items observed during `turn/start`\n- emit app-server reasoning stream notifications for Responses reasoning\n  events observed during `turn/start`\n- emit app-server model reroute and verification notifications for Responses\n  model metadata observed during `turn/start`\n- emit app-server `item/mcpToolCall/progress` notifications around configured\n  MCP tool calls during `turn/start`\n- emit app-server MCP startup status notifications while `turn/start`\n  discovers configured MCP tools\n- emit app-server `mcpServer/elicitation/request` requests when stdio MCP tools\n  ask the client for structured input during `turn/start`\n- emit app-server `thread/compacted` notifications after successful loaded\n  thread compactions\n- root app-server `turn/start` model-requested shell tools and `apply_patch`\n  edits in the loaded thread cwd when the tool call does not provide an\n  explicit workdir\n- run a minimal interactive remote app-server TUI over `--remote unix://PATH`,\n  loopback `--remote ws://HOST:PORT`, or TLS `--remote wss://HOST:PORT` for\n  new threads, remote resume/fork pickers, `resume --last`, explicit\n  `resume TARGET`, explicit\n  `fork ID|PATH`, `fork --last`, text/local-image turns, and websocket\n  capability-token auth via `--remote-auth-token-env`\n- start a minimal local remote-control server with `--remote-control`,\n  `--remote-control-bind`, or runtime `/remote-control [start|stop]`, exposing\n  controller/viewer browser links, `/api/state`, live `/api/events`\n  server-sent state snapshots, and controller-only `/api/message` prompt\n  submission into the running TUI\n- accept interactive override flags after `resume` and `fork`, including model,\n  profile, cwd, image, approval, sandbox, OSS, remote, and no-alt-screen\n  settings\n- add local and git-backed marketplace sources, upgrade configured Git\n  marketplaces, and remove configured marketplaces with `plugin marketplace`,\n  mutating `$CODEX_HOME/config.toml`\n- list user and per-cwd project command hooks from `config.toml` and\n  `hooks.json` with app-server `hooks/list`, including user hook-state\n  enable/trust metadata and enabled local plugin-cache hooks\n- execute trusted app-server `SessionStart` and `UserPromptSubmit` command\n  hooks during `turn/start`, including hook lifecycle notifications, Rust-shaped\n  stdin payloads, and hidden developer-message context injection\n- list local app-server skills from repo, user, and per-cwd extra roots with\n  `skills/list`, including enabled local plugin-cache skill roots,\n  `forceReload` cache refreshes, and `agents/openai.yaml` interface/dependency metadata plus\n  `skills/config/write` enablement toggles\n- parse the planned Rust top-level `remote-control` command's config and\n  feature options, while still reporting headless app-server remote\n  control as unimplemented\n- parse the experimental `cloud` / `cloud-tasks` command family, including\n  `exec`, `status`, `list`, `apply`, and `diff` options; `exec` creates Cloud\n  tasks with environment id or label resolution, prompt/stdin input, git\n  branch selection, best-of-N metadata, and starting-diff payloads; `list`\n  resolves environment id or label filters, `status` and `diff` perform\n  authenticated Cloud Tasks backend reads, and `diff` / `apply` resolve\n  sibling attempts for `--attempt` selection before displaying or applying\n  Cloud diffs locally with `git apply --check --3way` preflight followed by\n  `git apply --3way`, including parsed applied/skipped/conflict path summaries\n  in apply diagnostics; top-level `cloud` opens a\n  line-oriented task picker for list/status/diff/apply workflows and task\n  creation in the selected environment, while the\n  richer full-screen picker UI remains planned\n- print general or command-specific help with `help [COMMAND]`\n- generate shell completion scripts for bash, elvish, fish, powershell, and zsh\n\nLong-term exact parity is tracked in `docs/parity.md`.\n\n## License\n\nThis project is licensed under the MIT License. See `LICENSE`.\n\n## Requirements\n\nThe first milestone is developed and verified on macOS. Other Unix-like\nplatforms may build, but they are not yet part of the supported verification\nmatrix.\n\n- Zig `0.16.0`\n- Python 3 for smoke-test harnesses\n- SQLite development headers/library available to the system linker\n- Git for repository-aware exec, review, and plugin-marketplace smokes\n\nOn macOS with Xcode Command Line Tools installed, the SQLite and Git\nrequirements are normally already available.\n\n## Build\n\n```sh\nzig build\nzig build test\nzig build run\n```\n\nThe project currently targets Zig `0.16.0`.\n\n## Verification\n\nRun the repeatable checks:\n\n```sh\nzig build test\nzig build e2e\n```\n\nThe `e2e` step starts a local mock Responses server, launches the real\n`zig-out/bin/codex-zig` binary in a pseudo-terminal, verifies top-level\n`-i/--image` initial-prompt attachment on the interactive path, verifies\nruntime feature toggles through `features list`, profile-scoped feature\npersistence, Rust legacy feature aliases, direct under-development enable\nwarnings, app-server startup warnings for config-enabled under-development\nfeatures, suppression with `suppress_unstable_features_warning = true`, legacy\nfeature-key deprecation notices, deprecated `experimental_instructions_file`\nnotices, deprecated `on-failure` approval-policy warnings, initialize-time\nproject-local config warnings for disabled project config and ignored\nunsupported keys plus malformed user/trusted project execpolicy rules,\nhook-load startup warnings, and root default-off feature clearing, checks\n`help [COMMAND]`,\nverifies exact generated shell completion output for bash, elvish, fish,\npowershell, and zsh, verifies\n`execpolicy check` prefix-rule JSON output, `match` / `not_match` validation,\n`network_rule` validation, and resolved host executable JSON output,\ninteractive remote app-server flag parsing/rejection plus real\n`--remote unix://PATH` and loopback `--remote ws://HOST:PORT` TUI turns through\na running app-server, verifies planned-but-unimplemented Rust top-level command\nstubs plus the `remote-control` and `cloud` command families' Rust-shaped\noption parsing and positional-argument rejection, verifies local remote-control\nflag parsing/rejection, runtime\n`/remote-control [start|stop]`, and a PTY-driven local `/api/message`\nsubmission into the running TUI while a live `/api/events` stream observes the\nupdated transcript, verifies session-local\n`resume` / `fork` override parsing,\nverifies local and git-backed `plugin marketplace`\nadd/repeat/upgrade/remove config mutation,\nverifies `debug clear-memories` against temporary memory roots with symlink-root\nrejection and SQLite state-db row cleanup, checks the debug app-server\nsend-message-v2 turn stream against a mock Responses backend, verifies\n`debug trace-reduce` lifecycle replay against a temporary trace\nbundle, runs the top-level `apply` command success and preflight-conflict paths\nagainst a mock ChatGPT task backend and temporary git repositories, then drives\n`/help`, `/status`,\n`/debug-config` effective values plus config-source status, `/keymap`, `/plan` tool omission and proposed-plan rendering, `/title` item selection and persistence, `/statusline`, `/theme`, `/personality`, persisted `/rename` metadata, `/sessions`, `/fast`, `/copy`, `/raw`, `/vim`, `/mention`, `/side`, `/mcp`, `!COMMAND`, `/model`, `/permissions`, `/history`, model-requested `update_plan`, `exec_command`, and\n`apply_patch` tool calls with approval, `/ps`, `/clean`, and `/quit`, then checks\nthe captured terminal transcript, API request count, propagated model override,\npropagated service tier, and the file created in the temporary workspace. It\nalso launches the TUI without `--no-alt-screen` to verify alternate-screen\nenter/leave escape sequences, checks `tui.alternate_screen = \"never\"` stays\ninline, then launches `codex-zig app-server` as a subprocess and verifies\nnewline-delimited JSON-RPC initialize requests and unsupported-method errors\nover stdio, verifies `memory/reset` against temporary memory roots plus\npartial-reset refusal cases, then checks an explicit Unix socket and the default\n`CODEX_HOME/app-server-control/app-server-control.sock` socket, including\nsequential client connections after the first client disconnects. The same\nsmoke script also proxies JSON-RPC over `app-server proxy --sock`, verifies the\nhidden `stdio-to-uds` relay command with a persistent Unix listener, verifies\napp-server local and git-backed\nmarketplace add/list/repeat/upgrade/remove RPC behavior, including git revision\nmetadata, local app-server\n`plugin/list` marketplace discovery from repo, home, and configured local roots, remote\n`plugin/list` catalog fetching, remote `plugin/read` detail fetching, remote\n`plugin/skill/read` Markdown fetching, remote plugin share save/list/update/delete\nbehavior, local `plugin/uninstall` cache/config cleanup, remote\n`plugin/uninstall` cache cleanup, local, relative git, and pinned git-subdir\n`plugin/install` cache/config writes, remote `plugin/install` bundle cache writes and cloud mutation,\nand local `plugin/read` details for skills, hooks, apps, and MCP servers,\nverifies app-server hooks-list discovery for user and\nproject `config.toml` / `hooks.json` command hooks, enabled local plugin-cache\ncommand hooks, persisted user hook state, and malformed JSON warnings, verifies\napp-server\nskills-list discovery for repo, user, extra, and enabled local plugin-cache\nskill roots plus `forceReload` cache behavior, `agents/openai.yaml`\ninterface/dependency metadata, and `skills/changed` invalidations for in-process skill and config\nmutations, verifies\napp-server MCP server status pagination, enabled local plugin-cache MCP entries,\nraw stdio tool/resource/resource-template inventory, bearer-token,\nfile-backed OAuth, and OAuth-discovery not-logged-in auth reporting,\nconfig-backed stdio resource reads with and without loaded thread IDs,\nloaded-thread stdio tool calls including non-object argument pass-through, and\nstdio MCP elicitation request/response round trips for both direct\n`mcpServer/tool/call` and model-triggered `turn/start` MCP tool calls, and\napp-server streamable HTTP MCP resource reads and tool calls with bearer-token\nand file-backed OAuth auth plus streamable HTTP MCP session-id and teardown\nheaders and GET SSE responses after accepted POSTs,\nmodel-facing stdio and streamable HTTP MCP resource\nlist/template/read tool calls, verifies model-facing streamable HTTP MCP tool\ndiscovery and execution with bearer-token auth plus session-id and teardown\nheaders and GET SSE responses after accepted POSTs, verifies\nCLI MCP OAuth login, including provider-rejected discovered-scope retry,\nfile-backed MCP OAuth logout, and macOS keychain-backed MCP OAuth logout for\nstreamable HTTP servers, verifies\nCLI MCP auth-status reporting for bearer-token, file-backed OAuth, macOS\nkeychain-backed OAuth, and OAuth-discovery not-logged-in servers, verifies\nexec-server filesystem read, write, metadata, directory listing, copy, remove,\nand sandbox-context behavior against a temporary directory, verifies\napp-server filesystem read, write, metadata, directory listing, copy, and remove\nbehavior against a temporary directory, verifies app-server filesystem watch\nnotifications for in-process file mutations, direct external file mutations,\nand unwatch cleanup,\nverifies app-server buffered `command/exec` for stdout/stderr capture,\ncapture-time independent output-cap truncation, timeout exit-code responses\nwith captured pre-timeout output, cwd and environment overrides, nonzero exit\nresponses, supported `permissionProfile`\nexecution shapes using Rust-shaped `fileSystem` / `network.enabled` payloads,\nmanaged permission-profile network enabled/restricted behavior,\n`streamStdoutStderr` output-delta notifications, external permission-profile\nand external sandbox-policy execution, sandbox-policy `networkAccess`\nenforcement, stdio stdin streaming, PTY sessions, active PTY resize,\nworkspace-write sandbox-policy temp-root defaults and exclude\nflags, implicit workspace-write temp-root defaults, required streaming\n`processId` validation, and follow-up command session validation/inactive-process\nerrors,\nverifies app-server `process/spawn` execution, output/exited notifications,\nactive stdio streamed-output and stdin sessions, duplicate active handle\nrejection, active `process/kill`, macOS PTY sessions with `process/resizePty`,\nand non-stdio transport rejection for process stdin/TTY sessions,\nchecks app-server model catalog, provider-capability, collaboration-mode-list,\napp-list empty and enabled local plugin app manifest catalogs,\ngit-diff-to-remote, fuzzy-file-search one-shot scoring/order and session notifications,\naccount-read, get-auth-status,\naccount-logout, account-login, account-login-cancel, account-rate-limits,\naccount-add-credits-nudge, config-read with user origin/layer metadata, user\nsandbox workspace settings, instruction/developer/compact prompt fields,\ntools/apps config including app defaults, policy flags, and per-app tool\noverrides, trusted project scalar, tool, app, and\nsandbox workspace layers, system scalar/tool/app/sandbox workspace\nprecedence, required empty user/system layers, and legacy managed\nscalar/tool/app/sandbox overrides,\nconfig-value-write including table-object merge/replace behavior,\nconfig-batch-write including table-object merge/replace behavior, and\nconfig-requirements RPCs against temporary config homes, including system\nrequirements precedence and legacy managed-config requirements, and a mock\nbackend, checks app-server experimental\nfeature listing and runtime\nenablement patching against temporary config homes, verifies websocket\nsequential-client lifecycle and connection-local subscription reset, verifies\napp-server\nTypeScript/JSON Schema generation including command-exec request/response,\nfollow-up, and output-delta notification artifacts, verifies the hidden\ninternal `RolloutLine.json` schema generator, and checks app-server flag\ncompatibility for analytics defaults plus websocket transport,\ncapability-token auth, and signed-bearer auth. It also runs\nCLI smokes for profile-scoped feature enablement writes and reads, `exec review`\ndispatch with `--cd`, equals-form exec options, piped-stdin exec prompts, the\nexec Git-repository guard, `exec resume` option placement, yolo /\n`--dangerously-bypass-approvals-and-sandbox` approval-policy conflicts, and removed\n`--full-auto` compatibility, plus rejection of the removed top-level\n`marketplace` namespace and sandbox built-in permission-profile execution.\nApp-server smokes cover profile-scoped feature enablement writes and reads. Run\n`scripts/tui_e2e.py --show-output` directly when you want to inspect the\nterminal transcript.\n\n## Auth\n\n`codex-zig` reuses the same `$CODEX_HOME/auth.json` file as the Rust CLI by\ndefault, and also honors Rust's `cli_auth_credentials_store` setting for file,\nmacOS keychain, auto, and process-local ephemeral auth storage. The current Zig\nauth surface supports:\n\n```sh\ncodex-zig login status\ncodex-zig login\ncodex-zig login --with-api-key\ncodex-zig login --with-access-token\ncodex-zig login --device-auth\ncodex-zig logout\n```\n\n`login` starts a local browser OAuth callback flow on macOS, writes the\nresulting ChatGPT tokens to the selected auth store, and persists a best-effort\ntoken-exchanged `OPENAI_API_KEY` when the issuer returns one. `login\n--device-auth` implements the ChatGPT device-code fallback directly in Zig and\ndoes not request the browser-login API-key exchange.\nApp-server `chatgptAuthTokens` logins are treated as external auth and stay in\nthe process-local ephemeral store, taking precedence over persistent auth until\nlogout clears both active and persistent entries.\n`login --with-access-token` stores the token in the Rust CLI-compatible\n`agent_identity` auth shape; full upstream JWT/JWKS verification and\nagent-task authorization are still tracked as parity work. `CODEX_ACCESS_TOKEN`\ncan also provide the access token without writing `auth.json`.\n`logout` best-effort revokes managed ChatGPT OAuth tokens before removing the\nselected auth store entry.\n\n## Sessions\n\nInteractive and non-interactive turns save Zig-native JSONL transcripts under\n`$CODEX_HOME/sessions/zig/`.\n\n```sh\ncodex-zig sessions\ncodex-zig resume\ncodex-zig resume --last\ncodex-zig resume last -m gpt-5.5 --sandbox workspace-write\ncodex-zig resume \u003csession-id\u003e\ncodex-zig fork\ncodex-zig fork --last\ncodex-zig fork \u003csession-id\u003e\n```\n\n## Configuration\n\nThe port reads `model`, `model_provider`, `openai_base_url`,\n`chatgpt_base_url`, `approval_policy`, `sandbox_mode`, `oss_provider`,\n`personality`, and `profile` from top-level keys in\n`$CODEX_HOME/config.toml`. It also supports `[profiles.\u003cname\u003e]` sections for\nthose same fields, reads `[tui].theme`, `[tui].status_line`,\n`[tui].terminal_title`, and `[tui].alternate_screen` for TUI preferences, and reads\n`[model_providers.\u003cname\u003e].base_url`, `wire_api`, `env_key`,\n`experimental_bearer_token`, `query_params`, `http_headers`, and\n`env_http_headers` for custom providers. It also supports section-form\n`[model_providers.\u003cname\u003e.auth]` and inline `auth = { ... }` `command`, `args`,\n`cwd`, `timeout_ms`, and `refresh_interval_ms` for command-backed bearer tokens.\nThe current port supports Responses wire API providers, rejects the removed\n`wire_api = \"chat\"` setting, and rejects command-auth combinations that Rust\nmarks invalid. Command-backed provider tokens are cached while fresh, rerun\nafter `refresh_interval_ms` before a later request, and force-refreshed once on\n401 before retrying the request.\nWhen `--oss` is active, the local OSS request path ignores configured custom\nprovider request metadata so remote-provider query params, HTTP headers, and\nprovider auth are not sent to the local endpoint.\n\n```sh\ncodex-zig --profile work auth-status\ncodex-zig -m gpt-5.5 -a never -s danger-full-access\ncodex-zig -i screenshot.png -- \"describe this\"\ncodex-zig --cd ~/dev/my-project\ncodex-zig --add-dir ~/scratch\ncodex-zig -c model=gpt-5.5\ncodex-zig exec -c sandbox_mode=read-only \"say hello\"\ncodex-zig --oss --local-provider lmstudio\ncodex-zig --search\ncodex-zig --enable goals features list\ncodex-zig --disable shell_tool features list\ncodex-zig exec --enable goals --disable shell_tool \"say hello\"\ncodex-zig help exec\ncodex-zig exec help resume\ncodex-zig exec review --help\ncodex-zig --no-alt-screen\ncodex-zig --version\ncodex-zig exec --version\ncodex-zig exec --profile work \"say hello\"\ncodex-zig exec --skip-git-repo-check \"say hello\"\nprintf 'say hello' | codex-zig exec\nprintf 'extra context' | codex-zig exec \"summarize\"\ncodex-zig exec resume --all last \"continue\"\ncodex-zig exec --image screenshot.png -- \"describe this\"\ncodex-zig sandbox macos -- /bin/echo ok\ncodex-zig sandbox macos --permissions-profile :workspace --cd . -- /bin/echo ok\ncodex-zig sandbox macos --permissions-profile custom-profile --cd . -- /bin/echo ok\ncodex-zig features list\ncodex-zig features enable goals\ncodex-zig features disable goals\ncodex-zig --profile work features enable goals\ncodex-zig mcp list\ncodex-zig mcp add docs -- node ./server.js\ncodex-zig mcp add remote --url https://example.com/mcp\ncodex-zig mcp-server\ncodex-zig app-server\ncodex-zig review --uncommitted\ncodex-zig review --base main\ncodex-zig review --commit HEAD\ncodex-zig exec review --uncommitted\ncodex-zig exec review -m gpt-5.5 --json -o review.txt --uncommitted\n```\n\n`CODEX_ZIG_PROFILE` selects a profile. `CODEX_ZIG_MODEL` overrides the model.\n`CODEX_ZIG_MODEL_PROVIDER` selects a configured model provider.\n`CODEX_ZIG_BASE_URL` overrides both API base URLs for local testing.\n`CODEX_ZIG_WEB_SEARCH` overrides web search mode with `disabled`, `cached`, or\n`live`.\n`CODEX_OSS_BASE_URL` or `CODEX_OSS_PORT` override the local OSS Responses endpoint.\nThe Rust-compatible `-c/--config key=value` path currently accepts supported\nscalar keys: `profile`, `model`, `openai_base_url`, `chatgpt_base_url`,\n`oss_provider`, `approval_policy`, `sandbox_mode`, `web_search`, and\n`tui.alternate_screen`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminghinmatthewlam%2Fcodex-zig-port","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminghinmatthewlam%2Fcodex-zig-port","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminghinmatthewlam%2Fcodex-zig-port/lists"}