annodex

AI-native bioinformatics workspace by Annoroad, backed by Codex app-server. Browser workspace for project-scoped agent chat, file preview, extensions, and multi-provider models.

Version: 0.1.67
Repository: seqyuan/annodex
Docs site: see site/ (Fumadocs)

Quick Start

npm install -g @openai/codex @seqyuan/annodex
codex          # Ctrl+C at login prompt (one-time init)
annodex

Open http://localhost:30121/workspace. On first start, annodex can optionally set a web password (similar to Jupyter).

Before first use: ensure your home directory is writable. Annodex and Codex both persist data under $HOME (see Data & storage). On Linux servers with small or read-only home quotas, set ANNODEX_CONFIG_DIR to a writable path (see below).

Features

• Project workspace — pick a project directory; chats, files, and uploads stay scoped to that cwd.
• Project switcher — pinned projects appear as sidebar folders with chat history; unpinned projects list in the top dropdown; the active unpinned project shows as a temporary folder.
• Codex threads — create, resume, fork, and branch conversations via codex app-server.
• Any LLM provider — DeepSeek, OpenAI, Anthropic, and OpenAI-compatible APIs through ~/.config/annodex/providers.json (Settings → Models).
• Streaming UI — live thinking, tool calls, waiting status, and SSE reconnect.
• Native /goal — Codex thread goals with in-app panel and slash command.
• Images — pasted images save to {project}/.annodex-uploads/ and reload after refresh.
• Project memory — working memory (retain / recall / reflect via MCP) with promote to MEMORY.md / CONTEXT.md.
• Project IM (WeCom) — optional one bot per project cwd; configure in Settings → Project → WeCom IM; run annodex-im-gateway as a sidecar (auto-started by annodex start).
• Extensions — MCP / plugin definitions (Settings → Extensions); global config in ~/.config/annodex/extensions.json.
• Skills, tools, sandbox — per-session tool presets and thinking level from the chat bar.
• Files panel — browse, preview, and edit project files alongside chat.
• Optional password — annodex passwd / web-auth.json.

CLI

annodex                      # start managed background server
annodex start                # start if not already running
annodex restart              # stop then start
annodex stop                 # stop background server
annodex status               # show server status
annodex logs                 # show recent logs
annodex logs -f              # follow logs
annodex doctor               # diagnose codex path, config dir, transport
annodex --port 8080          # custom port
annodex --hostname 127.0.0.1 # bind host (use 0.0.0.0 on Linux servers)
annodex --version            # print version
annodex --help               # print help
annodex update               # update global package
annodex passwd               # set/change password
annodex passwd --reset       # remove password

PORT=8080 annodex
ANNODEX_PASSWORD=xxx annodex
ANNODEX_CONFIG_DIR=/data/you/annodex-config annodex

Managed servers auto-restart after package updates once active agent sessions are idle. Set ANNODEX_AUTO_RESTART=0 to disable. Legacy ANNOVIBE_* and PIDEX_* environment variables are still accepted for migration.

Data & storage

Annodex reads Codex thread history from Codex storage and writes its own config under the user home (or ANNODEX_CONFIG_DIR).

Requires a writable home (or override)

Both annodex and Codex need to create and update files under the effective user home:

| Location | Purpose | |---|---| | ~/.config/annodex/ | annodex config, runtime state, logs | | ~/.codex/ | Codex CLI config and chat/session storage (CODEX_HOME) | | {project}/.annodex-uploads/ | pasted chat images (per project cwd) | | {project}/.codex/ | optional project-scoped Codex extensions |

Linux notes

• Confirm echo $HOME points to a directory you own and can write to (touch "$HOME/.annodex-write-test").
• Common failures: home on NFS with quota full, read-only root/home, container users without a writable $HOME, or batch/HPC accounts with tiny home limits.
• Fix: export a writable config root before starting:

  export ANNODEX_CONFIG_DIR=/scratch/$USER/annodex-config
  mkdir -p "$ANNODEX_CONFIG_DIR"
  # Codex sessions still use ~/.codex unless you set CODEX_HOME similarly:
  export CODEX_HOME=/scratch/$USER/codex-home
  mkdir -p "$CODEX_HOME"
  annodex --hostname 0.0.0.0

• Server logs: ~/.config/annodex/annodex.log (or under ANNODEX_CONFIG_DIR).

annodex config files (~/.config/annodex/)

| File | Purpose | |---|---| | providers.json | LLM providers and models | | annodex-projects.json | pinned projects, sort order, registry | | extensions.json | global MCP / extension definitions | | settings.json | app preferences (e.g. auto-restart) | | web-auth.json | optional web UI password hash | | SOUL.md, HARNESS.md | optional global persona / harness text (seeded on first start if missing) | | annodex.json | runtime supervisor state while server is running | | annodex.log | background server log |

Legacy filenames (annovibe-*, pidex-*) are read for migration; new writes use annodex-*.

Development

npm install
npm run dev   # port 30121

Typecheck: node_modules/.bin/tsc --noEmit
Lint: npm run lint

Do not run next build during dev; it pollutes .next/ and can break npm run dev.

See AGENTS.md for architecture and release workflow.