An open-source, general-purpose coding agent for the terminal, the browser, and the desktop.
Website |
English |
简体中文
---
## What is Apexo?
Apexo is a **general-purpose coding agent** with a unified terminal UI (TUI), web UI, and Electron desktop app powered by a single local agent runtime.
Rather than being tied to a single model vendor or acting as a thin wrapper, Apexo provides its own deeply engineered agent architecture — including a durable session runtime, autonomous goals (`/goal`), multi-session workflows (`/workflow`), background task & subagent orchestration (`/tasks`), persistent project memory (`/memory`), native command sandboxing (`/sandbox`), lifecycle hooks (`/hooks`), and side-channel queries (`/btw`) — while offering first-class support across major model ecosystems:
- **Google Gemini & Antigravity first-class support.** Reuse your local Antigravity CLI (`agy`) Google login directly without re-authorizing, or connect via `GOOGLE_GENERATIVE_AI_API_KEY`. Full support for Gemini models, thinking/reasoning summaries, multimodal attachments, and large-context coding workflows. See the [Antigravity setup guide](docs/antigravity.md).
- **xAI Grok & Grok Build workflows.** Sign in with your xAI account (SuperGrok or X Premium) using xAI's OAuth device-code flow, or use `XAI_API_KEY`. All current Grok models (`grok-4.7`, `grok-4.6`, `grok-4.20`, `grok-build-0.1`) and Grok Build-style agent capabilities work natively.
- **Universal multi-provider & OpenAI-compatible runtime.** Connect OpenAI, Anthropic (Claude), MiniMax, DeepSeek, Qwen, or any self-hosted endpoint (vLLM, Ollama, LM Studio) with automatic `` reasoning extraction, incremental streaming, and tool execution.
- **100% local, no middleman subscription, no ads.** There is no hosted model gateway, mandatory account console, telemetry relay, or upsell. Everything runs on your machine and communicates directly with the providers you configure.
- **One server, three interfaces.** Terminal UI, Web UI, and Desktop App share the same local server, live event stream, and durable session history.
- **Grove theme:** a warm-dark/green default theme across TUI, Web, and Desktop, alongside classic built-in and custom themes.
### Authentication & OAuth Philosophy
Apexo supports **local OAuth / native CLI login** for **Google Antigravity (`agy`)** and **xAI Grok**, plus direct API-key and custom endpoint connections for all providers (Google Gemini, xAI, OpenAI, Anthropic, MiniMax, and any OpenAI-compatible service). Authentication is handled entirely on your machine; model requests go straight to the provider you choose.
## Key Capabilities
- **Autonomous Goals (`/goal`):** Define a target objective and verification criteria; the agent iterates until the goal is verified, paused, blocked, or out of budget.
- **Multi-Session Workflows (`/workflow`):** Run structured multi-step workflows in dedicated child sessions while keeping your main conversation responsive.
- **Background Tasks & Subagents (`/tasks`):** Manage background shell commands, scheduled recurring jobs (`/loop`), subagents, and coordinator sessions in one place.
- **Persistent Memory (`/memory`, `/remember`, `/flush`, `/dream`):** Review, curate, and consolidate durable project and user memory across sessions.
- **Command Sandbox (`/sandbox`):** Enforce OS-level sandboxing (`seatbelt` on macOS, `bubblewrap` on Linux) for native shell commands (`workspace` or `read-only` profiles).
- **Lifecycle Hooks (`/hooks`):** Inspect and govern repository and user hooks with explicit per-repository trust controls.
- **Side Questions (`/btw`):** Ask a quick side question (even mid-prompt) in a modal without polluting or interrupting the active session turn.
## Install
```bash
npm install -g apexo-code
apexo --version
```
The npm package installs a prebuilt CLI for macOS, Linux (glibc or musl), or Windows
on x64 and arm64. Desktop installers and standalone CLI archives are available from
[GitHub Releases](https://github.com/cluster1900/apexo-code/releases).
See the [detailed installation guide](docs/installation.md) for platform and CPU
selection, npm-free installation, Windows PowerShell commands, checksums, PATH,
Desktop installation, updates, and removal.
### Build from source
To build Apexo from source, install [Bun](https://bun.sh) 1.4.4 (the repo pins `bun@1.4.4`) and git.
```bash
git clone https://github.com/cluster1900/apexo-code.git apexo && cd apexo
bun install
# Build a single native binary for this machine (the web UI is embedded)
bun run --cwd packages/apexo build --single
# The binary lands in packages/apexo/dist/apexo--/bin/apexo
mkdir -p ~/.local/bin
install -m755 packages/apexo/dist/apexo-*/bin/apexo ~/.local/bin/apexo
install -m755 packages/apexo/dist/apexo-*/bin/apexo-workflow-script ~/.local/bin/apexo-workflow-script
export PATH="$HOME/.local/bin:$PATH"
apexo --version
```
Pushing a `vX.Y.Z` tag runs `.github/workflows/release.yml`, which builds and smoke-tests the CLI npm packages, packages Desktop for macOS, Linux, and Windows,
and attaches the archives to a [GitHub Release](https://github.com/cluster1900/apexo-code/releases).
See [Releasing Apexo](docs/releases.md) for publishing setup and the release checklist.
Once a release exists, the install script can fetch it instead (`--version X.Y.Z` pins a release):
```bash
curl -fsSL https://raw.githubusercontent.com/cluster1900/apexo-code/main/install | bash
```
To run from source without building:
```bash
bun dev # same as: bun run --cwd packages/apexo src/index.ts
bun dev --help
```
## Usage
```bash
apexo # start the terminal UI in the current directory
apexo auth login # sign in to Google Antigravity, xAI Grok (OAuth), or configure an API key
apexo auth list # show configured credentials
apexo models # list available models across all configured providers
apexo run "explain this repo" # one-shot, non-interactive CLI execution
apexo web # start the local server and open the web UI
apexo serve # headless local server (for desktop app, editors, scripts)
apexo acp # run Apexo as an Agent Client Protocol (ACP) server for editors like Zed
```
In the TUI and Desktop composer, `/connect` opens the provider dialog, `/models` switches models, `/themes` switches
themes, and `ctrl+p` (`cmd+k` / `cmd+p` on macOS) opens the command palette. Start a prompt with `!` to run a shell command.
### Providers
| Provider | How to connect | Environment variable |
| ----------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------ |
| **Google Gemini** | API key (AI Studio / Vertex-compatible) | `GOOGLE_GENERATIVE_AI_API_KEY` |
| **Antigravity (Google / Gemini)** | Select Antigravity; reuse local `agy` login or complete `agy`'s Google sign-in once | — |
| **xAI Grok** | `apexo auth login` -> xAI -> SuperGrok Subscription (device-code OAuth), or an API key | `XAI_API_KEY` |
| **OpenAI** | API key | `OPENAI_API_KEY` |
| **Anthropic (Claude)** | API key | `ANTHROPIC_API_KEY` |
| **Custom / OpenAI-Compatible** | Configure `baseURL` + `apiKey` in `apexo.jsonc` (MiniMax, DeepSeek, Ollama, vLLM, etc.) | Custom `{env:...}` |
### Desktop app
The Electron desktop app lives in `packages/desktop`:
```bash
bun run --cwd packages/desktop dev # development build
bun run --cwd packages/desktop build # production bundle (packaging uses electron-builder)
```
The desktop app has no auto-updater; rebuild it (or install a newer release) to update.
## Configuration
Apexo reads JSON/JSONC config files:
| What | Location |
| --------------------- | ------------------------------------------------------------------------- |
| Global config | `~/.config/apexo/apexo.jsonc` (`apexo.json` also works) |
| Data / state / cache | `~/.local/share/apexo`, `~/.local/state/apexo`, `~/.cache/apexo` |
| Project config | `apexo.json` / `apexo.jsonc` in the project (searched up to the git root) |
| Project directory | `.apexo/` (agents, commands, plugins, themes, tools) |
| Environment variables | `APEXO_*` (for example `APEXO_CONFIG`, `APEXO_CONFIG_CONTENT`) |
Example `apexo.json`:
```jsonc
{
"$schema": "https://raw.githubusercontent.com/cluster1900/apexo-code/main/schemas/config.json",
"model": "google/gemini-2.5-pro",
"theme": "grove",
}
```
### Custom OpenAI-Compatible Providers
You can configure any self-hosted or third-party OpenAI-compatible endpoint (such as MiniMax, DeepSeek, Qwen, vLLM, Ollama, or LM Studio) in `~/.config/apexo/apexo.jsonc` or your project's `apexo.jsonc`:
```jsonc
{
"$schema": "https://raw.githubusercontent.com/cluster1900/apexo-code/main/schemas/config.json",
"model": "custom/MiniMax-M2.7",
"provider": {
"custom": {
"npm": "@ai-sdk/openai-compatible",
"name": "Custom OpenAI-Compatible",
"options": {
"baseURL": "https://api.minimax.cn/v1",
"apiKey": "{env:CUSTOM_API_KEY}",
},
"models": {
"MiniMax-M2.7": {
"name": "MiniMax M2.7",
},
},
},
},
}
```
Verify that your custom provider and models are registered by running `apexo models`.
JSON schemas for editor completion live in [`schemas/`](schemas): `config.json` (`apexo.json`),
`tui.json`, `theme.json` (TUI themes), and `desktop-theme.json` (app themes). Regenerate them with
`bun script/schemas.ts`.
## Themes
- **TUI:** `grove` is the default. Switch with `/themes`, or set `"theme"` in `tui.json`
(`~/.config/apexo/tui.json`). Custom themes go in `.apexo/themes/*.json` or
`~/.config/apexo/themes/`.
- **Web and desktop app:** Grove is the default in Settings -> Appearance. The classic theme is
also available.
## Development
```bash
bun install
bun turbo typecheck --concurrency=2
(cd packages/core && bun test)
(cd packages/apexo && bun test)
(cd packages/tui && bun test)
```
Workspace packages use the `@apexo/*` scope; the CLI and server live in
`packages/apexo`.
## Feedback
Report bugs and ideas at [github.com/cluster1900/apexo-code/issues](https://github.com/cluster1900/apexo-code/issues).
## License
MIT. See [LICENSE](LICENSE).