OpenCodeX

An AI coding agent with the OpenCode experience — OpenCodeX branding, BYO provider/model, pure Node.js runtime. No account, no hosted models, no Zen. Bring your own API key and your own models.

opencodex   # start the terminal UI
ocx         # alias

Why OpenCodeX

• BYO provider/model — any OpenAI-compatible endpoint; no vendor lock-in, no account
• Pure Node.js — Node >= 22, ESM only, no Bun required
• Skills engine — discover + evaluate + load the right skill for every prompt
• Built-in skills — caveman, ponytail, coding, debugging, testing, git, documentation
• MCP engine — local & remote servers, per-prompt relevance, Playwright + Context7 built in
• Agent tool loop — bash / read_file / write_file / MCP tools, guarded against infinite loops
• Sessions & streaming — persistent sessions, SSE streaming responses
• TUI + CLI — /models model picker, provider management, full command set

Requirements

• Node.js >= 22 (ESM only; no Bun required)

Install

npm install -g @bajoel13/opencodex

Or from source:

git clone https://github.com/cgnbajoel-cyber/opencodex
cd opencodex
npm install
npm run build
node dist/cli.js --version

Quickstart

1. Configure a provider

Create opencodex.json in your project (or ~/.config/opencodex/opencodex.json):

{
  "provider": {
    "myai": {
      "baseURL": "https://api.example.com/v1",
      "env": ["MYAI_API_KEY"],
      "models": {
        "my-model-id": "My Display Name"
      },
      "activeModel": "my-model-id"
    }
  }
}

modelId (the key) is what gets sent to the API; alias (the value) is only the display name. Requests always use the modelId.

Then export your key (never commit it):

export MYAI_API_KEY="sk-..."

2. Discover models

opencodex models              # interactive /models picker (auto in a TTY)
opencodex models --refresh    # auto-discover from GET /v1/models

Discovery handles https://host, https://host/, https://host/v1, https://host/v1/ without producing /v1/v1/models, and falls back to manual model entry if discovery fails.

3. Run the agent

opencodex run "what is opencodex?"
opencodex run --no-stream "explain the tool loop"
opencodex run --model <model-id> "use a specific model"

Each prompt goes through: skill discovery → relevance → skill loading → MCP discovery → relevance → connection → system prompt construction → LLM request → tool calls (up to 8 iterations) → final response.

CLI

opencodex --help        # list all commands
opencodex --version     # print version
ocx --help              # alias

| Command | Description | |---|---| | opencodex [project] | start the terminal UI | | opencodex run <message> | send a prompt and run the agent | | opencodex models | list / select models, edit aliases, discover | | opencodex providers | list configured providers | | opencodex skills | list skills, evaluate prompt relevance | | opencodex mcp | manage MCP servers (add / list / remove) | | opencodex session | session management (list, continue, export, import) | | opencodex config | view or edit configuration | | opencodex serve | headless HTTP server | | opencodex export / import | session JSON export / import | | opencodex debug | debugging utilities | | opencodex db | database utilities | | opencodex completion | shell completion script |

Skills

Skills are discovered on every prompt (no permanent cache) and only the relevant ones are loaded into context:

opencodex skills                       # list available skills
opencodex skills --evaluate "debug a failing test"   # check relevance

Built-in: caveman (ultra-compressed output), ponytail (laziest solution that works), coding, debugging, testing, git, documentation. Add your own skills to ~/.config/opencodex/skills/ or via config.

MCP

Local and remote MCP servers, connected per-prompt based on relevance:

opencodex mcp add playwright --builtin   # browser automation (needs npx)
opencodex mcp add context7 --builtin     # library documentation
opencodex mcp list                       # server status

Environment variables

OPENCODEX_* is the primary namespace; legacy OPENCODE_* still works as a fallback (OpenCodeX values take precedence).

Documentation

• docs/architecture.md — architecture overview
• docs/requirements.md — requirements
• docs/implementation-plan.md — phase plan
• docs/agent-runtime.md — agent pipeline & tool loop
• docs/provider.md / docs/models.md — provider & model design
• docs/mcp.md — MCP engine
• docs/skills.md — skills engine
• docs/compatibility.md — OpenCode compatibility notes
• docs/troubleshooting.md — troubleshooting

License

MIT