Installation

codexfi installs as a single command. It registers itself with OpenCode, prompts for API keys, and creates helpful slash commands.

Prerequisites

OpenCode installed and working
A Voyage AI API key for embeddings
At least one extraction provider API key:
- Anthropic (default, most consistent)
- xAI (fastest, cheapest)
- Google AI (native JSON mode)

Install

Run the one-liner:

curl -fsSL https://codexfi.com/install | bash

This handles everything: installs Bun if it isn't already present, then runs the codexfi installer.

If you already have Bun installed, you can run the installer directly:

bunx codexfi install

The installer performs three steps:

Step 1: Register with OpenCode

Adds "codexfi" to the plugin array in ~/.config/opencode/opencode.json. If no config exists, it creates one.

Creates the /memory-init slash command at ~/.config/opencode/command/memory-init.md. This command guides the agent through a structured project memory initialization when you start working on a new codebase.

Step 3: Configure API keys

The installer interactively prompts for:

Voyage AI key (required) — used for all embedding operations
Extraction provider key (required) — choose from Anthropic, xAI, or Google

Keys are stored in ~/.codexfi/codexfi.jsonc.

Non-interactive install

For automated or agent-driven installs, pass keys directly:

bunx codexfi install --no-tui \
  --voyage-key pa-... \
  --anthropic-key sk-ant-... \
  --provider anthropic

Available flags:

Flag	Description
`--no-tui`	Skip all interactive prompts
`--voyage-key <key>`	Set Voyage AI API key
`--anthropic-key <key>`	Set Anthropic API key
`--xai-key <key>`	Set xAI API key
`--google-key <key>`	Set Google API key
`--provider <name>`	Set extraction provider: `anthropic`, `xai`, or `google`

Verify installation

After installing, verify your configuration:

bunx codexfi status

This runs 7 checks and reports the result of each:

#	Check	Passes when
1	Data directory	`~/.codexfi/` exists and is readable/writable
2	Vector store	store is initialized (warn if not yet — created on first session)
3	Config file	`~/.codexfi/codexfi.jsonc` exists
4	Voyage API key	`voyageApiKey` is set in `codexfi.jsonc`
5	Extraction API key	at least one of `anthropicApiKey`, `xaiApiKey`, `googleApiKey` is set
6	OpenCode plugin	`"codexfi"` is registered in `opencode.json`
7	Log file	`~/.codexfi.log` exists (warn if not — appears after first session)

A fresh install before the first OpenCode session will show checks 2 and 7 as warnings — this is normal. All others must pass.

Migrating from environment variables? As of v0.4.6, the plugin reads API keys exclusively from codexfi.jsonc. VOYAGE_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, and GOOGLE_API_KEY environment variables are no longer read by the plugin. Run bunx codexfi install to migrate your keys into the config file.

First session setup

On the first session in any project, codexfi automatically reads 28 common project files (README.md, package.json, Dockerfile, tsconfig.json, monorepo configs, agent instructions, and more) plus recent git history, and extracts initial memories. These memories are available immediately on Turn 1 — the agent has project context from its very first response. After the first response, background enrichment adds directory structure and additional context.

For empty directories with no project files, codexfi injects a [MEMORY - NEW PROJECT] hint into the system prompt so the agent knows to help you build from scratch.

For a more thorough initial setup, use the /memory-init slash command in OpenCode. It guides the agent through:

Checking existing memories
Exploring the codebase (or asking founding questions for empty projects)
Saving structured memories across all categories
Confirming what was stored

AGENTS.md (recommended)

Adding instructions to ~/.config/opencode/AGENTS.md improves agent behavior with codexfi. The agent will understand the [MEMORY] block, use the memory tool correctly, and never announce memory operations to the user.

See the OpenCode setup guide for the recommended AGENTS.md configuration.

Updating

OpenCode auto-installs npm plugins at startup and caches them in ~/.cache/opencode/node_modules/. This means updates are automatic — you always get the latest version without manual action.

To force a reinstall:

bunx codexfi install

Uninstalling

Remove "codexfi" from the plugin array in ~/.config/opencode/opencode.json:

{
  "plugin": []
}

Memory data is stored at ~/.codexfi/. Delete this directory to remove all stored memories.