# 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](https://github.com/seqyuan/annodex)  
Docs site: see [`site/`](site/) (Fumadocs)

## Quick Start

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

Open [http://localhost:30121/workspace](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](#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

```bash
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:
  ```bash
  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

```bash
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](AGENTS.md) for architecture and release workflow.