tessl/npm-openai--codex

OpenAI Codex CLI is a lightweight coding agent that runs locally, providing multimodal inputs, rich approvals workflow, and terminal-based AI-assisted development

Overview

Eval results

Files

Development Utilities

Name: tessl/npm-openai--codex
Author: tessl

Development utilities provide additional tools for shell completion generation, debugging, and diff application.

Shell Completion

Generate shell completion scripts for the Codex CLI.

codex completion <SHELL>

Arguments

<SHELL>    # Shell to generate completions for (bash, zsh, fish, powershell)

Examples

# Generate bash completions
codex completion bash > /etc/bash_completion.d/codex

# Generate zsh completions
codex completion zsh > ~/.zsh/completions/_codex

# Generate fish completions
codex completion fish > ~/.config/fish/completions/codex.fish

# Generate PowerShell completions (Windows)
codex completion powershell > codex_completion.ps1

Installation Examples

Bash

# System-wide installation
sudo codex completion bash > /etc/bash_completion.d/codex

# User installation
codex completion bash > ~/.local/share/bash-completion/completions/codex

# Source directly in .bashrc
echo 'eval "$(codex completion bash)"' >> ~/.bashrc

Zsh

# Add to fpath and generate completion
mkdir -p ~/.zsh/completions
codex completion zsh > ~/.zsh/completions/_codex

# Add to .zshrc if not already in fpath
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -U compinit && compinit' >> ~/.zshrc

Debug Commands

Internal debugging commands for sandboxed execution.

codex debug <SUBCOMMAND>

Subcommands

Seatbelt (macOS)

Run a command under macOS Seatbelt sandbox.

codex debug seatbelt [OPTIONS] -- <COMMAND>...

Options

--full-auto              # Enable full automation mode
-- <COMMAND>...          # Command to execute under sandbox

Landlock (Linux)

Run a command under Linux Landlock+seccomp sandbox.

codex debug landlock [OPTIONS] -- <COMMAND>...

Options

--full-auto              # Enable full automation mode
-- <COMMAND>...          # Command to execute under sandbox

Examples

# Run command under macOS Seatbelt (macOS only)
codex debug seatbelt -- ls -la /tmp

# Run command under Linux Landlock (Linux only)
codex debug landlock -- python script.py

# Run with full automation
codex debug seatbelt --full-auto -- npm install

# Test sandbox restrictions
codex debug landlock -- curl https://example.com  # Should fail due to network restrictions

Sandbox Behavior

Seatbelt (macOS)

Uses macOS's built-in Seatbelt framework
Restricts file system access
Limits network operations
Provides process isolation

Landlock (Linux)

Uses Linux Landlock LSM and seccomp
Fine-grained file system restrictions
Network access control
System call filtering

Apply Command

Apply the latest diff produced by Codex as a git patch to your local working tree.

codex apply [OPTIONS]

Options

Inherits configuration options from global configuration system.

Examples

# Apply the latest diff from Codex
codex apply

# Apply with specific configuration
codex apply -c diff_format=unified

# Apply in specific directory
codex -C /path/to/project apply

Apply Workflow

Generate diff: Use interactive or exec mode to generate changes
Review diff: Examine the proposed changes
Apply changes: Use codex apply to apply as git patch

# Example workflow
codex exec "Fix the bug in src/main.py"
# Review the suggested changes
codex apply  # Apply the changes to working tree
git add .
git commit -m "Fix bug in main.py"

TypeScript Generation (Internal)

Generate TypeScript protocol bindings (hidden command for internal use).

codex generate-ts [OPTIONS]

Options

-o, --out <DIR>            # Output directory for TypeScript files
-p, --prettier <PATH>      # Optional Prettier executable path

This command is used internally for generating TypeScript bindings and is not part of the public API.

Configuration Integration

All development utilities support configuration overrides:

# Use specific config profile
codex --config-profile development completion bash

# Override configuration for debugging
codex -c sandbox_mode=strict debug landlock -- command

# Apply with configuration
codex -c git_apply_options="--check" apply

Best Practices

Shell Completion

Install completions: Set up completions for your shell
Update regularly: Regenerate when CLI is updated
Test completions: Verify completions work after installation

Debug Commands

Test sandbox behavior: Use debug commands to test security restrictions
Development testing: Verify commands work under sandbox constraints
Platform awareness: Use appropriate sandbox for your OS

Apply Command

Review before applying: Always review diffs before applying
Use version control: Ensure working tree is clean
Test after applying: Verify changes work as expected

Platform Compatibility

Shell Completion: Available on all platforms
Seatbelt Debug: macOS only
Landlock Debug: Linux only
Apply Command: Cross-platform (requires git)

Troubleshooting

Completion Not Working

# Verify completion file exists and is sourced
which codex
codex completion bash > test_completion.sh
source test_completion.sh

Sandbox Failures

# Check platform compatibility
uname -s  # Should be Darwin for Seatbelt, Linux for Landlock

# Verify command syntax
codex debug landlock -- echo "test"  # Simple test command

Apply Issues

# Ensure git repository
git status

# Check for uncommitted changes
git diff --check

# Verify Codex generated a diff
codex exec "List files" | grep -i "diff\|patch"

Install with Tessl CLI