njfio/codex-process: Lightweight coding agent that runs in your terminal · GitHub

npm i -g @openai/codex
or brew install --cask codex

Codex CLI is a coding agent from OpenAI that runs locally on your computer.

Install globally with your preferred package manager:

# Install using npm
npm install -g @openai/codex

# Install using Homebrew
brew install --cask codex

Then simply run codex to get started.

Each GitHub Release contains many executables, but in practice, you likely want one of these:

• macOS
  • Apple Silicon/arm64: codex-aarch64-apple-darwin.tar.gz
  • x86_64 (older Mac hardware): codex-x86_64-apple-darwin.tar.gz
• Linux
  • x86_64: codex-x86_64-unknown-linux-musl.tar.gz
  • arm64: codex-aarch64-unknown-linux-musl.tar.gz

Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.

Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.

You can also use Codex with an API key, but this requires additional setup.

This fork now ships a renamed primary CLI binary: nickdex. (codex remains as a compatibility alias for now.)

nickdex process run --task "Implement X"
nickdex process execute --task "Implement X"
nickdex process execute --task "Implement X" --dry-run
nickdex process execute --task "Implement X" --verify "cargo test -p codex-cli" --verify "cargo test -p codex-core"
nickdex process execute --task "Implement X" --sandbox workspace-write --approval-policy never
nickdex process status --run-id <id>
nickdex process pr-comments --repo owner/repo --pr 123
nickdex process pr-comments --repo owner/repo --pr 123 --act
nickdex process pr-comments --repo owner/repo --pr 123 --act --dry-run
nickdex process pr-comments --repo owner/repo --pr 123 --act --no-dedupe
nickdex process pr-comments --repo owner/repo --pr 123 --act --require-clean-worktree --max-mutations-per-run 12
nickdex process pr-comments --repo owner/repo --pr 123 --gh-max-attempts 7 --gh-base-backoff-ms 750
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20 --act
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20 --act --dry-run
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20 --act --no-dedupe
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20 --act --confirm-label process:auto-fix --max-mutations-per-run 12
nickdex process issues watch --repo owner/repo --label process:auto-fix --limit 20 --act --max-concurrency 3 --queue-delay-ms 400 --max-act-items 10

process execute now runs an end-to-end stage pipeline and writes machine-readable artifacts under .process/runs/<run-id>/: contract.json, red-proof.json, green.json, verify.json, traceability.json, summary.md, and execute.json. It automates:

• CONTRACT stage scaffolding with task + scope placeholders.
• RED stage intent recording with a failing-proof placeholder.
• GREEN stage Codex subprocess execution (codex exec) unless --dry-run.
• VERIFY stage execution of each --verify command (when provided) with per-command stdout/stderr pass/fail capture.
• EVIDENCE stage summary + traceability scaffold generation. Stage failures are recorded in execute.json and printed to the console; the run continues through all stages so a final report is always produced.

process run remains available as the lightweight scaffolding command. The pr-comments subcommand performs live GitHub comment ingestion via gh, capturing unresolved PR review comments (including reviewThreadId) and issue comments into .process/runs/<run-id>/pr-comments.json. Passing --act enables triage and follow-up automation: comments are classified (quick_fix, needs_issue, question) and written to .process/runs/<run-id>/triage.json. Passing --act --dry-run performs the same ingestion + triage planning flow but skips all external mutations (no Codex subprocesses, no branch/commit/push/PR operations, and no GitHub comment/thread/issue updates). In --act mode, optional mutation guardrails are available: --require-clean-worktree (fail fast if git has local changes), --max-mutations-per-run <n> (global cap across issue create, branch/commit/push, PR create, comment post, and thread resolve actions), plus --confirm-label <label> for issues watch (only act on issues that still carry the label). Dedupe/idempotency is enabled by default across prior local run artifacts and can be bypassed with --no-dedupe. For quick_fix items, Codex runs targeted exec subprocesses in isolated git worktrees/branches (process/quick-fix-pr-<pr>-<comment-id-short>), creates one commit per successful item, then attempts to push each quick-fix branch and open a follow-up PR (base = source PR base branch when detectable, otherwise main). For review-comment quick fixes with a successful follow-up PR, it also attempts to resolve the original review thread via gh api graphql (resolveReviewThread). The triage artifact records per-item execution/commit metadata plus push/PR metadata (quickFixPushed, quickFixRemoteBranch, quickFixPrUrl, quickFixPrNumber, quickFixPushError, quickFixPrError) and thread-resolution metadata when applicable (quickFixThreadResolved, quickFixThreadResolveError). When at least one quick fix succeeds, the command posts one concise PR update comment through gh pr comment summarizing applied items (including files/verification status, commit links, and created follow-up PR links when available), and stores that comment URL in the triage artifact when it can be detected. For needs_issue items, follow-up issues are opened via gh issue create and linked in the artifact. triage.json now includes run-level operationId, dryRun, run-level guardrails, dedupe summary fields duplicateCount + dedupeKeysMatched[], and per-item dedupeKey, idempotent, plannedAction, and skippedReasons[]. The issues watch subcommand fetches matching open issues and writes .process/runs/<run-id>/issues-watch.json with fetchedAt, repo, label, openIssues[], and suggestedActions[]. With --act, issues watch triages each issue (quick_fix or needs_manual) and isolates each quick-fix attempt so one issue failure does not abort the rest. Matching issues are first queued and then started with bounded concurrency (--max-concurrency, default 1) plus inter-start throttling (--queue-delay-ms, default 250) to reduce GitHub/git bursts. Use --max-act-items to cap how many queued issues are acted on in a run (remaining issues are recorded as skipped with an explicit reason). Successful quick-fix attempts run targeted codex exec in an isolated worktree branch, commit/push changes, open a follow-up PR, and post a status comment back on the issue via gh issue comment. Non-successful attempts post a concise manual-follow-up comment with the failure reason. --act --dry-run keeps ingestion/triage/queue planning but skips all mutation steps. Action runs write .process/runs/<run-id>/issues-watch-act.json with run-level fields operationId, dryRun, guardrails, fetchedAt, repo, label, maxConcurrency, queueDelayMs, maxActItems, actedCount, skippedCount, duplicateCount, dedupeKeysMatched[], and per-issue issueActions[] entries: issueNumber, issueUrl, decision, plannedAction, skippedReasons[], attempted, success, branch, commitSha, commitUrl, prUrl, prNumber, updateCommentUrl, and error. gh process-mode calls now retry transient API failures (including rate limiting/abuse/secondary-limit signals) with exponential backoff + jitter. Tune behavior with --gh-max-attempts (default 5) and --gh-base-backoff-ms (default 500).

A separate dashboard plan for configuring schedules/repos and monitoring process jobs is documented at:

• docs/dashboard-mvp.md
• process-dashboard/README.md (foundation service scaffold and local run steps)

This scope is explicitly for codex-process / nickdex automation and excludes autoresearch-rs.

• Codex Documentation
• Contributing
• Installing & building
• Open source fund

This repository is licensed under the Apache-2.0 License.