Build an Execution-First Codex CLI Workspace with the Portable Setup Kit

What the Codex CLI Portable Setup Kit Does

The Codex CLI Portable Setup Kit is a community-maintained configuration and installer for OpenAI Codex CLI. It is not Codex itself and is not an official OpenAI product.

The kit changes how Codex approaches repository work. Its instructions emphasize inspecting the workspace, using available tools, making the requested changes, running checks, diagnosing failures, and reporting verified results. Portability is the delivery mechanism; the main product is this execution-first operating style.

Important: TURBO mode enables elevated, non-interactive behavior, including approval_policy = "never". Use it only in a workspace you trust and after reviewing the package. The standard public configuration begins with safer on-request approval and workspace-write sandboxing.

Key Features

• Execution-first instructions: Codex is directed to act on the real target instead of stopping after generic advice or a plan.
• One-click TURBO launch: TURBO.cmd validates the workspace, configures elevated execution policies, inherits native model settings, and starts Codex.
• Transactional installation: The installer verifies SHA-256 manifests, creates timestamped backups, journals operations, and generates a rollback receipt.
• Deterministic analysis tools: The pure-Python re-toolkit handles PE32 and PE32+ inspection, x86 and x64 disassembly, AOB scanning, micro-emulation, Protobuf and TLV analysis, Frida hook generation, and binary differences.
• Dual-stage processing: Structural planning is separated from high-fidelity rendering to reduce placeholder artifacts and degraded long-form output.
• Multiple agent formats: The package supplies instructions or presets for Codex CLI, OpenCode, Claude Code, Cursor, Windsurf, and the ChatGPT App.
• Continuity support: Hooks and context tools help preserve validated state during longer tasks.
• Reversible Git integration: The installer can bind core.hooksPath to the packaged pre-commit guard and restore the prior value during rollback.

Requirements and Preparation

The repository identifies Windows 10 and 11, PowerShell 5.1 or 7, and Python 3.10 or newer as supported components. Codex CLI is required for the primary workflow, although the installer can add a compatibility-pinned global @openai/codex package when Codex is missing.

1. Download a release ZIP or clone the repository.
2. Extract it to a local directory if you downloaded the ZIP.
3. Choose the repository that Codex will manage.
4. Review the included scripts and configuration before enabling elevated or unrestricted execution.
5. Back up any especially important workspace data independently, even though the installer creates transactional backups.

Option 1: Start with TURBO Mode

For the shortest setup path, extract the release and double-click:

TURBO.cmd

The launcher validates the workspace, configures the elevated execution profile, uses your native model settings, and opens Codex ready to operate. This mode also pre-approves runtime tools, marks workspaces as fully trusted, and uses non-interactive approval behavior.

Because these settings reduce confirmation barriers, reserve TURBO mode for reviewed code and trusted workspaces. For a more controlled installation, use the manual procedure below.

Option 2: Perform a Manual Transactional Installation

Open PowerShell in the extracted kit directory. Temporarily allow the installation script for the current PowerShell process, then provide the absolute path to your target workspace:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1 -ProjectRoot 'C:\path\to\your-workspace' -KeysmithPreset unrestricted -SkipPlugins

The example selects the unrestricted Keysmith preset and skips optional plugins. Review these choices before using them in your environment.

During installation, the kit follows a transactional sequence:

1. Validate the project root.
2. Verify the source package against its SHA-256 manifest.
3. Create a timestamped backup and operation journal.
4. Install user files, skills, project files, context tools, and re-toolkit.
5. Substitute paths required by the destination environment.
6. Configure project trust and the repository Git hook path.
7. Attempt optional plugin setup when requested without treating plugin failure as fatal.
8. Write receipt.json and last-receipt.txt.

Each replacement is recorded before it happens. If a later installation step fails, the installer replays the operation list in reverse and restores the previous Git hook binding.

What the Installer Adds

• Codex user configuration: Files under %CODEX_HOME% or ~/.codex, including config.toml, AGENTS.md, instructions, starter rules, and skills.
• User-level agent skills: Reusable skills under ~/.agents.
• Project configuration: AGENTS.md, CLAUDE.md, .codex, .agents, .gitignore, context workflows, hooks, and the reverse-engineering toolkit.
• Local Git configuration: core.hooksPath=.agents/git-hooks for the selected repository.
• Codex CLI: A compatibility-pinned global npm installation when Codex is not already available.
• Optional plugins: Browser, Visualize, and Sites support when available.

The release deliberately excludes credentials and machine-bound state. It does not migrate authentication data, OAuth data, sessions, histories, logs, caches, SQLite databases, cookies, API keys, private keys, browser runtime data, desktop binary paths, or context runtime state from another computer.

Verify the Package and Installation

Run the package verification script before relying on the setup:

.\verify.ps1

To verify the files installed into a particular workspace, add -Installed and the project path:

.\verify.ps1 -Installed -ProjectRoot 'C:\path\to\your-workspace'

Verification is an important part of the design. The installer checks the manifest before writing and blocks manifest path traversal. The repository also describes a nine-step Test-All.ps1 suite used for release testing.

Basic Usage with Codex

After installation, start Codex in the configured repository through TURBO.cmd or your normal Codex CLI workflow. Give it a concrete repository task rather than a request for general advice.

For example, ask Codex to inspect a failing test, implement the correction, rerun the relevant checks, and summarize the changed files. The installed instructions are designed to keep the agent moving from inspection to implementation and verification whenever the next action is available.

A suitable task could be phrased like this:

Inspect the failing tests in this workspace, identify the root cause, implement the smallest correct fix, rerun the affected tests, and report the verified result.

The profile is intended to encourage Codex to inspect files and test output first, edit the actual project, retry failed checks, and then provide a concise result rather than returning a tutorial for you to execute manually.

Use the Built-In re-toolkit

The toolkit is installed at .agents/tools/re-toolkit/ inside the project. Its unified entry point is cli.py. Commands that support --json are particularly useful when another script or agent needs structured output.

Automatically Triage a Binary

python .agents/tools/re-toolkit/cli.py auto target.dll --json

This performs automatic format discovery and triage on the target.

Inspect a PE File

python .agents/tools/re-toolkit/cli.py parse-pe sample.exe --json

The PE parser can inspect headers, section tables, imported DLLs, exported symbols, and RVA translation information for PE32 and PE32+ files.

Scan for an AOB Pattern

python .agents/tools/re-toolkit/cli.py pattern-scan target.bin --pattern "48 89 ?? 24 ?? 55" --json

Use ?? as a wildcard when bytes may vary between binaries or versions.

Extract Strings

python .agents/tools/re-toolkit/cli.py strings sample.exe --min-len 5 --json

This extracts ASCII and UTF-16LE strings with their offsets while filtering out strings shorter than the selected minimum.

Disassemble Opcodes

python .agents/tools/re-toolkit/cli.py disasm 90505831C0C3 --arch x86_64

The disassembler supports x86 and x64 analysis of raw opcodes or binary sections.

Decode an Undocumented Protobuf Payload

python .agents/tools/re-toolkit/cli.py decode-protobuf 089601120474657374

This performs schema-less inspection of Protobuf wire-format data. The subsystem also includes TLV frame dissection.

Emulate a Small Instruction Sequence

python .agents/tools/re-toolkit/cli.py emulate --code B82A000000505BC3

The micro-emulator provides an isolated register, stack, and memory sandbox for supported CPU-level analysis.

Generate a Frida Hook

python .agents/tools/re-toolkit/cli.py gen-hook --symbol CryptHashData --module advapi32.dll --output hook.js

This generates a Frida interceptor script for the selected module and symbol. The toolkit also supports anti-debug script generation.

Calculate a Binary Difference Patch

python .agents/tools/re-toolkit/cli.py diff-patch --orig orig.bin --patched mod.bin --json

This compares an original binary with a modified copy and emits patch information.

Inspect a Region as a Hex Dump

python .agents/tools/re-toolkit/cli.py hexdump target.bin --offset 0x100 --length 128

This formats 128 bytes beginning at offset 0x100 as an aligned hexadecimal dump.

Run the Dual-Stage Pipeline

The project includes a two-stage pipeline that separates structural planning from final rendering. The first stage creates the structure and major beats, while the second produces the full output. This separation is intended to reduce attention collapse, truncation, and literal placeholder artifacts such as ROLE_A and ROLE_B.

python .agents/tools/re-toolkit/cli.py pipeline "Your complex scenario or system architecture prompt"

This workflow is most relevant for complex prompts that benefit from explicit structural preparation before detailed generation.

Configure Other Supported Agent Tools

The package includes native configuration files for several agent environments, including AGENTS.md for Codex CLI, OPENCODE.md and opencode.json for OpenCode, CLAUDE.md for Claude Code, .cursorrules for Cursor, and .windsurfrules for Windsurf.

To configure and synchronize supported GPT-based agent frameworks and IDE integrations in the workspace, run the universal adaptor:

ADAPT_ALL.cmd

You can also export presets through re-toolkit:

python .agents/tools/re-toolkit/cli.py export-preset --target all

The repository includes a separate ChatGPT App preset under docs/CHATGPT_APP_PRESET.md.

Advanced Tips

Prefer Structured Output for Automation

Use --json where the command supports it. Structured results from PE parsing, pattern scanning, automatic triage, or binary differences are easier to save, compare, and pass into another tool.

Combine Analysis Commands

Start with auto for format discovery, continue with parse-pe for executable metadata, use strings to locate readable indicators, and apply pattern-scan when you have a candidate byte signature. Use disasm, emulate, or gen-hook for progressively deeper inspection.

Use the Speculative Probe Carefully

The toolkit exposes a speculative dual-model shadow probe with refusal abort and failover:

python .agents/tools/re-toolkit/cli.py spec-probe "Reverse engineer target module and extract memory offsets" --target game.dll --json

Use binary-analysis capabilities only on software and data you are authorized to inspect.

Keep Receipts

Do not delete the generated receipt if you may need to reverse the installation. The receipt stores the operation sequence needed to remove newly installed files, restore replaced files, and recover the previous Git hook configuration.

Understand the Standard Security Defaults

Outside explicitly selected TURBO behavior, the public edition begins with these reviewable settings:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

The starter rules do not include pre-approved command prefixes unless TURBO mode is chosen. Use the standard defaults when you want confirmation boundaries and workspace-scoped writes.

Roll Back the Installation

To restore the latest recorded installation, run:

.\rollback.ps1

To restore a particular transaction, provide its receipt explicitly:

.\rollback.ps1 -Receipt 'C:\path\to\receipt.json'

Git Bash users can invoke the wrapper:

./ROLLBACK.sh

Rollback removes files added by the installer, restores files that existed before installation, and restores or unsets the repository's previous core.hooksPath value.

Further Documentation

For the underlying Codex concepts, consult the official documentation for Codex CLI, configuration basics, AGENTS.md, rules, hooks, skills, and plugins.

Conclusion

The Codex CLI Portable Setup Kit packages an execution-focused Codex profile, project instructions, agent integrations, deterministic analysis utilities, verification, backups, and rollback into one reproducible setup. Begin with the standard transactional installation when you want reviewable controls, verify the result, and enable TURBO mode only when its elevated, non-interactive behavior is appropriate for a trusted workspace.