@samooth/open-codex

@samooth/open-codex

Lightweight coding agent that runs in your terminal.

Open Codex is a powerful, terminal-based coding assistant designed to help you build, refactor, and maintain your codebase directly from your CLI. It combines LLM reasoning with the ability to execute shell commands and apply file edits safely.

This is a community-maintained fork of the original OpenAI Codex CLI, featuring expanded support for multiple AI providers and a more flexible architecture.

Features

• Multi-Provider Support: Use OpenAI, Google Gemini, OpenRouter, Ollama, xAI, DeepSeek, or Hugging Face.
• Interactive Chat: A rich terminal UI built with Ink for seamless developer interaction.
• High Performance: Parallel tool execution and asynchronous file indexing for faster responses.
• Autonomous Action: The agent can read/write files and execute shell commands to solve complex tasks.
• Safety First: Three levels of autonomy (suggest, auto-edit, full-auto) with optional sandboxing (macOS Seatbelt) and a Dry Run mode.
• Context Aware: Automatically picks up project-specific instructions from codex.md files and maintains a persistent memory of your project.
• Multimodal: Supports passing images (screenshots, diagrams) to guide the coding process.

Installation

npm install -g @samooth/open-codex

Quickstart

• Set your API key (OpenAI is default, but others are supported):

  export OPENAI_API_KEY="sk-..."
  

• Launch the agent:

  open-codex
  

• Or run a one-off task:

  open-codex "Refactor src/utils.ts to use async/await"
  

Usage & Slash Commands

Inside the interactive chat, you can use several slash commands to control the agent:

• /help – Show available commands and shortcuts.
• /model – Switch the LLM model for the current session.
• /approval – Switch between autonomy levels (Suggest, Auto Edit, Full Auto).
• /history – Review the commands run and files touched in this session.
• /clear – Reset the conversation context.

Keyboard Shortcuts

• Enter: Send message.
• Up/Down: Navigate prompt history.
• Ctrl+J: Insert a newline.
• Esc (twice): Interrupt the agent's current action.
• Ctrl+C: Exit the application.

Configuration

Codex stores its settings in ~/.codex/config.json. You can configure the default provider, model, and approval mode there.

{
  "model": "o4-mini",
  "provider": "openai",
  "approvalMode": "suggest",
  "memory": {
    "enabled": true
  }
}

Supported Providers

Provider	Env Variable
OpenAI	OPENAI_API_KEY
Gemini	GOOGLE_GENERATIVE_AI_API_KEY
OpenRouter	OPENROUTER_API_KEY
xAI	XAI_API_KEY
DeepSeek	DS_API_KEY
Hugging Face	HF_API_KEY
Ollama	(Runs locally)

Security

Open Codex is designed to be safe by default. It warns you when running outside of a Git repository and provides a --dry-run flag to preview all intended actions before they happen. On macOS, it supports sandbox-exec to restrict file system access and disable networking during execution.

License

Apache-2.0