# @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

```bash
npm install -g @samooth/open-codex
```

## Quickstart

1. **Set your API key** (OpenAI is default, but others are supported):
   ```bash
   export OPENAI_API_KEY="sk-..."
   ```

2. **Launch the agent**:
   ```bash
   open-codex
   ```

3. **Or run a one-off task**:
   ```bash
   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.

```json
{
  "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](./LICENSE)