Zee

Zee is a unified CLI agent engine for life admin, investing, and learning. Semantic memory, tool orchestration, and multi-surface support across the TUI, daemon APIs, OpenBB Workspace, and messaging channels.

Release

• Version: see zee --version
• Prebuilt targets: Linux x64
• Other platforms: build from source

Quick Start

Prerequisites

• Bun (v1.1+)
• Qdrant (local) for semantic memory
• OpenBB Platform API for investing workflows (http://127.0.0.1:6900 by default or ZEE_OPENBB_API_URL)
• API key for your model provider (Anthropic, OpenAI, Google, etc.)

Install (npm)

npm install -g @adolago/zee
# or nightly builds
npm install -g @adolago/zee@nightly

Install (script)

curl -fsSL https://raw.githubusercontent.com/adolago/zee/main/install | ZEE_NPM_PACKAGE=@adolago/zee bash

Install from source

# Clone the repository
git clone https://github.com/adolago/zee.git
cd zee

# Install dependencies
bun install

# Build the project
cd packages/zee
bun run build

# Link the binary
ln -sf ~/.local/src/zee/packages/zee/dist/@adolago/zee-linux-x64/bin/zee ~/.bun/bin/zee

OpenBB setup

For investing workflows and the OpenBB copilot surface, point Zee at an OpenBB Platform API instance:

export ZEE_OPENBB_API_URL=http://127.0.0.1:6900
# optional if you use a custom launcher name/path
export ZEE_OPENBB_API_CMD=openbb-api

Configuration

Zee reads JSONC config from ~/.config/zee/zee.jsonc or .zee/zee.jsonc. Environment variables are used only for secrets (Qdrant settings are config-only).

Paths and overrides

Defaults follow XDG:

• Config: ~/.config/zee
• Data: ~/.local/share/zee
• Cache: ~/.cache/zee
• State: ~/.local/state/zee
• Workspace (default worktree): ~/.local/share/zee/worktree

To co-locate everything under a single state root, set ZEE_STATE_DIR. This makes config/data/cache/logs/workspace resolve under that directory as config/, data/, cache/, logs/, and workspace/.

To override only the workspace location, set ZEE_WORKSPACE_DIR.

Use zee paths to print the resolved locations.

Example memory + embeddings configuration:

{
  "memory": {
    "qdrant": {
      "url": "http://localhost:6333",
      "collection": "agent_memory"
    },
    "embedding": {
      "profile": "google/gemini-embedding-2-preview",
      "dimensions": 3072
    }
  }
}

Configure Google embeddings credentials (single source of truth):

zee auth login google

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."     # Optional if using `zee auth login openai`
export VOYAGE_API_KEY="..."     # Optional (Voyage reranking)

Optional: Google Antigravity (plugin-based OAuth):

zee plugin install opencode-google-auth
zee auth login

Select Google when prompted.

Start Qdrant (if running locally):

docker run -p 6333:6333 qdrant/qdrant

Embedding profiles

Common profiles you can set in memory.embedding.profile:

• google/gemini-embedding-2-preview (3072 dims, recommended)

Zee supports Google-only embeddings. You can also override with model, dimensions, and baseUrl.

Keep Qdrant collection dimensions aligned with your embedding dimensions by setting memory.embedding.dimensions to the same value as your collection vectors.

Running

Interactive TUI (attaches to a running daemon):

zee
zee --no-daemon   # run without the daemon (local worker only)

Ensure the daemon is running first (systemd service recommended for always-on messaging). See docs/tui-vim-mode.md for Vim keybindings.

Daemon mode (gateway embedded):

zee daemon --hostname 127.0.0.1 --port 3210

Remote client/server (explicit):

# On the server
zee daemon --hostname 0.0.0.0 --port 3210

# On the client machine
zee client http://server:3210
# or:
ZEE_URL=http://server:3210 zee

OpenBB Workspace copilot:

zee daemon --hostname 127.0.0.1 --port 3210

Then configure OpenBB Workspace to use Zee at:

• agent metadata: http://127.0.0.1:3210/openbb/agents.json
• query endpoint: http://127.0.0.1:3210/openbb/query
• auth: Authorization: Bearer $ZEE_SERVER_PASSWORD or X-Zee-Token: $ZEE_SERVER_PASSWORD

Gateway control plane helpers:

zee gateway status
zee gateway url

Architecture

zee/
├── packages/zee/    # Main CLI/TUI/daemon
├── src/
│   ├── agent/              # Assistant profiles and wiring
│   ├── memory/             # Qdrant semantic memory
│   └── domain/             # Domain tools (zee/, learning/)
└── .agents/skills/         # Skills

Assistant Model

Zee is the only active assistant. The engine still exposes domain toolsets under namespaces:

• zee:* for life admin
• zee:invest-* for investing
• zee:learn-* for learning

Key Features

• Semantic Memory: Vector-based memory with Qdrant for context persistence
• Single Assistant Runtime: No assistant switching or delegation required
• Embedded Gateway: Zee messaging gateway launched and supervised by the daemon

Usage with Zee Gateway

The Zee gateway is always embedded and supervised by the daemon:

zee daemon --hostname 127.0.0.1 --port 3210

For always-on messaging at boot, install the systemd service:

sudo ./scripts/systemd/install.sh --polkit --systemd-only
sudo systemctl enable zee
sudo systemctl start zee

The install script will prompt for sudo if needed. With --polkit, you can run start/stop/restart and enable/disable without sudo:

systemctl restart zee
systemctl enable zee

The systemd unit disables ProtectHome so the daemon can read/write projects in any directory under your home.

The --systemd-only flag writes daemon.systemd_only=true to enforce a systemd-only policy.

Development

# Typecheck
bun run typecheck

# Core tests
cd packages/zee && bun test

# Build + verify binary
cd packages/zee && bun run build && ./script/verify-binary.sh

Wide events

Zee emits wide event JSONL logs for per-request diagnostics:

zee logs wide --lines 50
zee logs wide --where sessionId=session_123

Acknowledgements

See CREDITS.md for upstream projects and forks.

License

See LICENSE.