Coder CLI - Enhanced Terminal Coding Agent

Coder CLI is an enhanced fork of OpenAI's Codex CLI that brings powerful AI coding assistance directly to your terminal with additional features for improved developer experience.

Codex CLI is a coding agent from OpenAI that runs locally on your computer.
If you are looking for the cloud-based agent from OpenAI, Codex Web, see chatgpt.com/codex.

---

Table of contents

• Quickstart
  • Installing and running Codex CLI
  • Using Codex with your ChatGPT plan
  • Connecting on a "Headless" Machine
    • Authenticate locally and copy your credentials to the "headless" machine
    • Connecting through VPS or remote
  • Usage-based billing alternative: Use an OpenAI API key
  • Choosing Codex's level of autonomy
    • 1. Read/write
    • 2. Read-only
    • 3. Advanced configuration
    • Can I run without ANY approvals?
    • Fine-tuning in config.toml
  • Example prompts
• Running with a prompt as input
• Using Open Source Models
  • Platform sandboxing details
• Experimental technology disclaimer
• System requirements
• CLI reference
• Memory & project docs
• Non-interactive / CI mode
• Model Context Protocol (MCP)
• Tracing / verbose logging
  • DotSlash
• Configuration
• FAQ
• Zero data retention (ZDR) usage
• Codex open source fund
• Contributing
  • Development workflow
  • Writing high-impact code changes
  • Opening a pull request
  • Review process
  • Community values
  • Getting help
  • Contributor license agreement (CLA)
    • Quick fixes
  • Releasing codex
• Security & responsible AI
• License

---

Quickstart

Installing and running Codex CLI

Install globally with your preferred package manager:

npm install -g @openai/codex  # Alternatively: `brew install codex`

Then simply run codex to get started:

codex

You can also go to the latest GitHub Release and download the appropriate binary for your platform.

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.

Using Codex with your ChatGPT plan

Run codex and select Sign in with ChatGPT. You'll need a Plus, Pro, or Team ChatGPT account, and will get access to our latest models, including gpt-5, at no extra cost to your plan. (Enterprise is coming soon.)

Important: If you've used the Codex CLI before, follow these steps to migrate from usage-based billing with your API key:

1. Update the CLI and ensure codex --version is 0.20.0 or later
2. Delete ~/.codex/auth.json (this should be C:\Users\USERNAME\.codex\auth.json on Windows)
3. Run codex login again

If you encounter problems with the login flow, please comment on this issue.

Connecting on a "Headless" Machine

Today, the login process entails running a server on localhost:1455. If you are on a "headless" server, such as a Docker container or are ssh'd into a remote machine, loading localhost:1455 in the browser on your local machine will not automatically connect to the webserver running on the headless machine, so you must use one of the following workarounds:

Authenticate locally and copy your credentials to the "headless" machine

The easiest solution is likely to run through the codex login process on your local machine such that localhost:1455 is accessible in your web browser. When you complete the authentication process, an auth.json file should be available at $CODEX_HOME/auth.json (on Mac/Linux, $CODEX_HOME defaults to ~/.codex whereas on Windows, it defaults to %USERPROFILE%\.codex).

Because the auth.json file is not tied to a specific host, once you complete the authentication flow locally, you can copy the $CODEX_HOME/auth.json file to the headless machine and then codex should "just work" on that machine. Note to copy a file to a Docker container, you can do:

# substitute MY_CONTAINER with the name or id of your Docker container:
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

whereas if you are ssh'd into a remote machine, you likely want to use scp:

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

or try this one-liner:

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

Connecting through VPS or remote

If you run Codex on a remote machine (VPS/server) without a local browser, the login helper starts a server on localhost:1455 on the remote host. To complete login in your local browser, forward that port to your machine before starting the login flow:

Installation

npm install -g @just-every/coder

Then run:

coderr

Key Features

🎯 Core Capabilities

• AI-powered coding agent that runs locally in your terminal
• File operations: Read, write, and modify files with AI assistance
• Command execution: Run shell commands with intelligent context
• Project understanding: Analyzes your codebase to provide relevant suggestions

✨ Enhanced Features (Fork Additions)

• Image Support: Drag-and-drop, paste, or reference images directly in the terminal
• Dynamic Reasoning: Adjust AI reasoning effort mid-conversation with /reasoning command
• Flexible Configuration: Uses ~/.coder directory (or ~/.codex for compatibility)

Quick Start

1. Install and Launch

npm install -g @just-every/coder
coder

2. Authenticate

You can use Coder CLI with:

• ChatGPT Plus/Pro subscription (recommended)
• OpenAI API key (usage-based billing)

3. Choose Autonomy Level

Read/Write Mode (default - full capabilities):

coderr

Read-Only Mode (safer, no file modifications):

coder --read-only

Example Usage

# Start an interactive session
code

# Run with a specific prompt
code "refactor this function to use async/await"

# Analyze code without making changes
code --read-only "explain the authentication flow"

# Adjust reasoning effort
/reasoning high  # More thorough analysis
/reasoning low   # Faster responses

Common Tasks

• Debug code: "Why is this function returning null?"
• Add features: "Add error handling to all API calls"
• Refactor: "Convert this class to use TypeScript"
• Explain: "How does the authentication system work?"
• Generate tests: "Write unit tests for the user service"

Configuration

Configuration file location: ~/.code/config.toml (or set CODE_HOME environment variable)

Basic Configuration

# Model selection
model = "gpt-5"

# Approval settings
approval_policy = "ask"  # ask | automatic | never

# Feature flags
hide_agent_reasoning = false

Environment Variables

• CODE_HOME or CODEX_HOME: Override default config directory
• OPENAI_API_KEY: Use OpenAI API directly
• OPENAI_BASE_URL: Use alternative API endpoints

Enhanced Image Support

The fork adds comprehensive image handling:

1. Drag and drop images directly into the terminal
2. Paste images from clipboard
3. Reference image files by path: "analyze screenshot.png"

Using the /reasoning Command

Dynamically adjust the AI's reasoning effort:

/reasoning high   # Detailed analysis, slower
/reasoning medium # Balanced (default)
/reasoning low    # Quick responses

Terminal Interface Tips

Text Selection

• Press Ctrl+M to toggle between mouse modes:
  • Scrolling mode (default): Mouse wheel scrolls chat history
  • Selection mode: Allows text selection and copying
• The status bar shows current mouse mode

Keyboard Shortcuts

• Enter: Submit your message
• Up/Down arrows: Navigate command history
• Ctrl+M: Toggle mouse capture (scrolling vs text selection)
• Ctrl+C: Cancel current operation
• Ctrl+D: Exit the application

System Requirements

• Operating Systems: macOS, Linux, Windows (WSL recommended)
• Node.js: Version 20 or higher
• Terminal: Modern terminal with UTF-8 support
• Memory: 4GB RAM minimum, 8GB recommended

Command Line Options

coder [options] [prompt]

Options:
  --model <name>     Override the model (e.g., gpt-5, claude-opus)
  --read-only        Prevent file modifications
  --no-approval      Skip approval prompts (use with caution)
  --config <key=val> Override config values
  --help            Show help information
  --version         Show version number

Advanced Features

Model Context Protocol (MCP)

Coder CLI supports MCP for extended capabilities:

• File system operations
• Web browsing
• Database connections
• Custom tool integrations

Project Documentation

Create a CODEX.md file in your project root to provide context:

# Project Overview
This is a React application using TypeScript...

## Key Components
- Authentication: src/auth/*
- API Client: src/api/*

Non-Interactive Mode

For CI/CD pipelines:

coder --non-interactive "update all dependencies"

Troubleshooting

Common Issues

Installation fails: Ensure Node.js 20+ is installed

node --version  # Should be v20.0.0 or higher

Authentication issues: Re-run the login flow

coder --login

Performance problems: Adjust model or reasoning level

coder --model gpt-5-turbo
# or use /reasoning low during conversation

Contributing

We welcome contributions! This fork maintains compatibility with upstream Codex while adding new features.

Development Setup

# Clone the repository
git clone https://github.com/just-every/code.git
cd code

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
./codex-rs/target/release/coder

Submitting Changes

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Differences from Original Codex

Feature	Coder CLI (Fork)	Original Codex
Command	code	codex
Config Directory	~/.code	~/.codex
NPM Package	@just-every/coder	@openai/codex
Image Support	✅ Enhanced	Basic
/reasoning Command	✅ Available	Not available
Environment Variables	CODE_HOME + CODEX_HOME	CODEX_HOME only

License

Apache 2.0 - See LICENSE file for details.

Acknowledgments

This project is a fork of OpenAI Codex CLI. We maintain compatibility while adding community-requested features.

---

Need help? Open an issue on GitHub or check the original Codex documentation.