Codeoid

Identity-first control plane for AI coding agents — multi-session, multi-frontend, with cross-session memory.

Run N parallel coding-agent sessions across repos — Claude Code by default, with Codex, Gemini, OpenAI, and pi as drop-in backends. Switch between them from a terminal cockpit, a web UI, or Telegram. Every action auditable; every agent (and sub-agent) has a cryptographic identity via ZeroID. Memory persists across sessions, so each agent inherits what the last one learned.

Terminal client lives in its own repo. The recommended cockpit is codeoid-tui — a native Rust/Ratatui client that speaks the daemon's WebSocket protocol. A built-in codeoid tui (Ink/React) ships in this repo as a zero-install fallback. See Terminal client.

_{codeoid-tui, the native Rust cockpit, tracking 12 parallel sessions at once. The same sessions open in a browser and on Telegram — one daemon, one source of truth.}

Contents

• Why Codeoid
• How Codeoid compares
• Quick start
• Backends
• Architecture
• Features
• Configuration
• CLI reference
• Development
• Contributing & security

Why Codeoid

You're orchestrating AI coding agents. Codeoid solves the things Claude Code's single-terminal experience can't:

• Parallel sessions, shared workspace memory — Two sessions on two git worktrees building feature A and feature B. Both inherit the same workspace's history. Session B can recall() what Session A learned yesterday, no re-read.
• Never-lose-detail memory — Every tool call, result, and reasoning block persists as a retrievable episode. No lossy compaction. Recall returns the real bytes.
• Three-layer context reduction — Pre-entry compression of CLI output + auto-rotation of the backing context + verbatim recall. Turns that would have cost $0.30 drop to pennies; peak occupancy stays below compaction.
• Mid-turn streaming input (VSCode parity) — Send a follow-up message while Claude is already responding. Priority semantics (now / next / later) let you interrupt-and-re-integrate or gracefully queue for the next turn.
• Production-grade token instrumentation — Per-turn input/output/cache/cost persisted to SQLite. Live StatusBar shows cumulative + Δ this-turn + cache hit rate + current context occupancy + queue depth + rotation count.
• Autonomous runs with a budget — Flip a session to autonomous mode; it auto-approves safe operations until a write/exec budget is spent, then hands control back.
• Device handoff — Start a session on your laptop, attach from your phone. Scrollback replays. Same conversation.
• Identity-grade audit — Every tool call stamped with the SPIFFE URI of the agent that made it. Sub-agents get their own attenuated identities. Delegation chain traceable top to bottom.
• Multi-frontend — same session accessible from terminal TUI, browser, or Telegram bot. Share read-only tokens with a teammate.

How Codeoid compares

Codeoid isn't a general-purpose IDE assistant. It's built for long-horizon, multi-session agent work, where context continuity and token economics matter more than inline code actions — so it optimizes for what the tools you already use don't: verbatim cross-session memory, parallel sessions on one control plane, a cryptographic identity per agent and sub-agent, and per-turn token economics.

Its closest peer is Omnigent, another multi-harness meta-harness — both run Claude, Codex, Gemini, OpenAI, and pi. They optimize for different things. Omnigent leans on breadth and isolation: the widest harness set (incl. Cursor, OpenCode, Hermes), an OS-level sandbox, and credential brokering. Codeoid leans on memory and identity: workspace-scoped verbatim recall, a cryptographic identity per agent and sub-agent (ZeroID), and per-turn token economics — reachable from a terminal, a browser, or your phone. Rule of thumb: reach for Omnigent when you need OS-level isolation and the broadest harness set; reach for Codeoid when you want persistent cross-session memory and per-agent audit for long-horizon work.

📊 Full capability matrix → — feature by feature against Claude Code CLI, the VSCode extension, Cursor, Aider, and Omnigent.

Quick start

Prerequisites

• Bun v1.0+
• Claude Code CLI logged in (claude login) or ANTHROPIC_API_KEY set — the default backend. Other backends (Codex, Gemini CLI, pi, OpenAI, Gemini) are optional — see Backends for each one's setup.
• A ZeroID identity — either the hosted Highflame SaaS (no infra) or a self-hosted ZeroID

Install

Pick one path. This guide writes every command as codeoid <cmd> (the global install); from a source checkout, run bun src/cli.ts <cmd> instead — they're interchangeable. Don't mix the two.

A. From npm — recommended, to just use it. Codeoid runs on Bun, so install it with Bun (npm also works, as long as Bun is on your PATH — it's the runtime):

bun install -g codeoid        # or: npm install -g codeoid
codeoid --help                # confirm it's on your PATH

This puts a codeoid command on your PATH; use codeoid <cmd> everywhere below. If codeoid isn't found afterward, your global-bin directory isn't on PATH — add Bun's (~/.bun/bin) to it, or use path B.

B. From source — to hack on it. Clone, then run bun install before anything else:

git clone https://github.com/highflame-ai/codeoid.git
cd codeoid
bun install                   # REQUIRED first — pulls commander and the rest

⚠️ Skipping bun install and running bun src/cli.ts … straight from a fresh clone fails with error: ENOENT while resolving package 'commander'. Run bun install once in the checkout and it's fixed. From source, use bun src/cli.ts <cmd> wherever this guide says codeoid <cmd>.

Authenticate

Codeoid needs one thing to start: a ZeroID key. Two ways to get one.

Option A — Highflame SaaS (recommended, no infra)

1. Sign up at highflame.ai and open Studio → Code Agents.

2. Create a code agent and mint its key — you'll get a zid_sk_..., shown once, so copy it now.

   • The agent's credential policy must allow the api-key grant type, or the key won't verify. If minting or registration fails with a grant-type error, switch the agent to a policy that permits api-key grants.

3. Log in — Codeoid ships pointing at the Highflame SaaS issuer, so there's nothing else to configure:

   codeoid login                 # prompts for the key (hidden), verifies it, saves to ~/.codeoid/config.json

Option B — Self-hosted ZeroID (local, ~2 min)

ZeroID is open source. Bring it up with Docker, mint a key, then point Codeoid at it.

First, in a directory outside your Codeoid checkout, run ZeroID:

git clone https://github.com/highflame-ai/zeroid
cd zeroid
make setup-keys              # generate the ECDSA/RSA signing keys
docker compose up -d         # starts Postgres + ZeroID on :8899
curl http://localhost:8899/health     # → {"status":"healthy",...}
# Then register an agent to mint a key (zid_sk_…, shown once) — use the
# ZeroID SDK / API from its quickstart, e.g.
#   client.agents.register(name="codeoid", created_by="you@example.com")

Then, back in Codeoid, log in against your local issuer with that key:

codeoid login --zeroid local                       # localhost:8899
# ...or any deployment:
codeoid login --zeroid https://zeroid.mycorp.com

--zeroid accepts a preset (highflame, highflame-dev, local) or any URL. The issuer is pinned to whatever you log in against — a token minted by any other issuer is rejected. login exchanges the key on the spot and prints the subject + granted scopes so you know it works before the daemon ever starts.

The daemon fetches the issuer's JWKS to verify tokens, so wherever ZeroID runs must be reachable from the daemon.

Run

# Start the daemon — serves TUI/web/Telegram + mounts memory
codeoid start

Then connect a client:

# Recommended: the native Rust cockpit (separate repo).
#   git clone https://github.com/highflame-ai/codeoid-ui && cd codeoid-ui
#   cargo run -p codeoid-tui --release
#
# Or the built-in fallback TUI (Ink/React, no extra install):
codeoid tui

Or browse to http://localhost:7400/ui/ for the web UI.

Each client authenticates itself — not just the daemon. codeoid login authorizes the daemon (saved to ~/.codeoid/config.json). A browser or Telegram client is a separate client under the same zero-trust model, so the web UI's first-run splash asks for a credential too — paste the same zid_sk_... key (or a scoped share token) once; the browser remembers it and exchanges it for a short-lived JWT to talk to the daemon. Logging in on the CLI does not carry over to the browser.

Backends

Claude is the default and always available. Every other backend is opt-in and auto-detected:

• CLI backends (codex, gemini-cli, pi) run their own agent CLI. Codex and pi authenticate with their own login (your existing Codex / pi subscription); gemini-cli uses a Gemini API key or Vertex. gemini-cli and pi ship bundled with Codeoid (no separate install); codex you install yourself.
• In-daemon API backends (openai, gemini) register only when their API key is set in ~/.codeoid/.env. These bill against the key, not a subscription.

Pick a backend per session with codeoid new <name> --provider <id>, or switch a live session with /provider <id>. Set keys from the Settings screen (⚙ / /settings) or by editing ~/.codeoid/.env — see Configuration for every variable.

Gemini needs an API key (or Vertex) — a consumer Google (AI Pro/Ultra) subscription can't be used with Codeoid. Both Gemini backends authenticate with GEMINI_API_KEY / GOOGLE_API_KEY (from AI Studio) or Vertex. The difference is capability: gemini-cli runs the full Gemini CLI over ACP (streaming + its own tools/MCP), while gemini is a lightweight in-daemon API client.

Claude — default, always on (Anthropic)

Nothing to install — it runs in-process via the Claude Agent SDK. Just authenticate one of two ways:

• Subscription: claude login (uses your Claude/Anthropic plan), or
• API key: put ANTHROPIC_API_KEY=sk-ant-… in ~/.codeoid/.env.
• Amazon Bedrock: set CLAUDE_CODE_USE_BEDROCK=1. AWS credentials aren't forwarded to the backend by default — allow them through with CODEOID_AGENT_ENV_ALLOW=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN.

Models: the aliases opus / sonnet / haiku, or any full claude-* id (codeoid new work --provider claude, then /model opus).

Gemini CLI (gemini-cli) — the richer Gemini backend (API key / Vertex)

Runs the full Gemini CLI over ACP — streaming plus its own tools/MCP — so it's a fuller Gemini experience than the lightweight in-daemon gemini backend.

• Auth: set GEMINI_API_KEY (from AI Studio) in ~/.codeoid/.env, or configure Vertex (GOOGLE_* + a GCP project). A consumer Google subscription is not supported.
• No install needed — Codeoid bundles the Gemini CLI; at runtime it uses gemini from your PATH if present, otherwise its bundled copy.

Override the binary with providers.geminiCli.command, or disable it with providers.geminiCli.enabled: false in config.json. Driven over ACP (gemini --acp).

Codex (codex) — OpenAI Codex CLI

1. Install the OpenAI Codex CLI (npm i -g @openai/codex) — unlike gemini-cli/pi it is not bundled, so codex must be on your PATH (or point providers.codex.command at it).
2. Authenticate with codex login (stored in ~/.codex/auth.json) — uses your OpenAI/Codex plan — or provide OPENAI_API_KEY in the environment.
3. Codeoid auto-detects codex (your PATH plus common Node bin dirs) and drives it over codex app-server.

Override with providers.codex.command, disable with providers.codex.enabled: false. Codex's native approval/sandbox default is derived from the session mode; pin it with CODEX_APPROVAL_POLICY (untrusted / on-request / never) and CODEX_SANDBOX_POLICY (read-only / workspace-write / danger-full-access).

pi (pi) — the pi coding agent

1. Log in once with the pi CLI so it stores credentials in ~/.pi/agent/auth.json.
2. That's it — Codeoid bundles pi, so at runtime it uses pi from your PATH if present, otherwise its bundled copy, driven over pi --mode rpc.

Override with providers.pi.command, disable with providers.pi.enabled: false. PI_CONFIG_DIR relocates pi's config/credential directory.

OpenAI (openai) — API key

An in-daemon backend that talks to the OpenAI API. Set OPENAI_API_KEY=sk-… in ~/.codeoid/.env (or via the Settings screen). The backend registers only when the key is present. Billed against the key.

Gemini (gemini) — API key

A lightweight in-daemon backend that talks to the Gemini API. Set GOOGLE_API_KEY=… (or GEMINI_API_KEY) in ~/.codeoid/.env; it registers only when the key is present. For a fuller agent (streaming + tools) on the same key, use gemini-cli above.

Architecture

_{Claude is the default backend; Codex, Gemini, OpenAI, pi, and the Gemini CLI plug into the same session interface.}

In one Bun process the daemon brokers everything between your clients and Claude, and owns three subsystems:

• Session Manager — per-session mode + write/exec budget, pinned files, the sub-agent tree, scrollback, and a JSONL transcript for crash-safe resume.
• Memory Engine — a chunker turns every tool call into a verbatim episode; a hybrid ranker (vectors + FTS5 BM25 + recency + path overlap) serves it back. Backed by SQLite (FTS5 + embeddings + file-read cache) and exposed to Claude as an in-process MCP server — recall(), recall_file(), timeline().
• ZeroID client — registers the session's SPIFFE identity and mints attenuated tokens for each sub-agent.

Each session drives its own provider backend — the Claude Agent SDK by default, or Codex, Gemini, OpenAI, pi, or the Gemini CLI, all behind one SessionProvider interface (adding a backend is one factory + one register()). The diagram above shows how the pieces fit.

Sessions are daemon-owned. Clients are stateless; they attach, receive scrollback replay, and stream live deltas. Detach and re-attach from anywhere.

Features

Full detail — keybindings, slash commands, ranking weights, rotation thresholds — lives in docs/FEATURES.md. The highlights:

Memory & context

• Cross-session memory — every tool call, result, and reasoning block is stored verbatim as a retrievable episode, served back by a hybrid ranker (vectors + FTS5 + recency + path overlap). Claude gets recall(), recall_file(), and timeline().
• Workspace memory index — a compact hot-files + topic-clusters + recent-sessions block auto-injected into every system prompt, so a fresh session starts already oriented.
• Three-layer context reduction — pre-entry CLI-output compression, backing-context auto-rotation, and verbatim recall. All lossless: recall returns the original bytes.

Sessions & control

• Multiple harnesses — Claude Code by default; Codex, Gemini, OpenAI, pi, and the Gemini CLI drop in behind one provider interface. Fork a session onto a different backend and it resumes with the full conversation.
• Parallel sessions + git worktrees — run features side by side; branches share one workspace memory, anchored on git-common-dir.
• Execution modes — guarded / interactive / autonomous, the last with a write-action budget that reverts to guarded when spent.
• Mid-turn streaming input — send a follow-up while Claude is still responding; now / next / later priority.
• Attachments — @file mentions, one-shot /context, and persistent /pin; drag-drop in the web UI.

Identity & resilience

• Cryptographic identity per agent + sub-agent — ZeroID SPIFFE/WIMSE URIs stamped on every tool call; /who prints the full delegation chain, and revoking the parent kills it.
• Production resilience — retry-with-fallback, graceful shutdown, transcript-based resume, rate limiting, keep-warm interrupt, and never-lose-message persistence.

Interfaces

One daemon, one source of truth, three ways in: the terminal cockpit (shown at the top), a browser, and Telegram. Device handoff lets you start on one and pick the session up on another — scrollback replays.

_{The SolidJS web UI at localhost:7400/ui — session list on the left, live log in the center, a metrics strip on top (turns, tokens, cache reads, cumulative cost).}

_{The same session on a phone, in the Telegram mini app — identical scrollback, a live header, served by the bot over the same WebSocket.}

Full keybindings, slash commands, and the Telegram command set → docs/FEATURES.md.

Configuration

Codeoid reads ~/.codeoid/config.json and environment variables; env-only secrets (like the Telegram bot token) live in ~/.codeoid/.env so they survive daemon restarts. Every client action is gated by a ZeroID permission scope, and scopes attenuate into revocable read-only share tokens for teammates.

→ Configuration & permission scopes — every environment variable, the config.json schema, the ~/.codeoid/.env file, and the full scope list.

CLI reference

Commands below use the global install (codeoid). From a source checkout, replace codeoid with bun src/cli.ts.

codeoid start [--port 7400] [--host 127.0.0.1] [--no-telegram] [--no-web]

codeoid tui                                          # Launch the cockpit TUI
codeoid ls                                           # List sessions
codeoid new <name> [workdir]                         # Create session
  --worktree <branch>                                #   auto-spawn a git worktree
  --repo <path>                                      #   worktree source (default: cwd)
  --worktree-dir <path>                              #   override target dir
codeoid attach <session>                             # Readline streaming attach
codeoid send <session> <message...>                  # One-shot send
codeoid interrupt <session>                          # Interrupt
codeoid approve <session> [--deny]                   # Approve / deny pending tool
codeoid destroy <session>                            # Destroy

Development

bun install              # install deps
bun run dev              # run daemon with --watch
bun run build            # build to dist/
bun run typecheck        # type check
bun run lint             # lint with biome
bun test                 # run unit tests (memory, attachments, etc.)

Key files

Area	File
CLI + command routing	src/cli.ts
Daemon HTTP + WebSocket	src/daemon/server.ts
Session orchestration	src/daemon/session-manager.ts, src/daemon/session.ts
Memory engine	src/daemon/memory/
Attachments + limits	src/daemon/attachments.ts
Git worktree helper	src/worktree.ts
Web UI server (serves web/dist at /ui)	src/frontends/web-ui/index.ts
Web UI app (SolidJS)	web/
Telegram bot	src/frontends/telegram/index.ts
Built-in TUI (Ink, legacy fallback)	src/tui/
Native TUI (Rust, recommended)	highflame-ai/codeoid-ui
Protocol types	src/protocol/types.ts

Contributing & security

PRs welcome — see CONTRIBUTING.md. For vulnerabilities, see SECURITY.md (please don't open public issues for security).

License

MIT © Codeoid

---

Powered by ZeroID with pluggable agent backends (default Claude Agent SDK). Terminal cockpit: codeoid-tui.