Zagens

August 1, 2026 · View on GitHub

Zagens Screenshot

Zagens

Open-source agent harness for DeepSeek V4.

中文 · 日本語 · Português (BR) | English

Long-horizon agent work tends to stall or “claim done” too early. Code and office files often live in separate tools. Local agents need replay, approval, and auditability — not just another chat window.

Zagens is an open-source agent harness for DeepSeek V4.

From the authors: Don’t believe an AI agent can do anything — it has boundaries. What we can do is expand those boundaries.

License: MIT. Runtime lineage: NOTICE.md · third-party/deepseek-tui/. Capabilities below reflect Zagens v0.9.0 — see CHANGELOG.md.

Resource	Link
User guides	zagens.com/docs
Downloads	GitHub Releases (latest `zagens-v0.9.0`) · zagens.com/download
Design specs	`docs/README.md`
Contributing	`CONTRIBUTING.md` · `LOCAL_DEV_VERIFY.md`
Security	`SECURITY.md`

Who Zagens is for

Good fit	Less fit
DeepSeek power users — daily DeepSeek API / V4 coding and agent workflows who want a local agent platform beyond official tools	A hosted SaaS with managed models and billing
Developers who want a standalone agent platform (desktop, TUI, or CLI — not locked into one IDE extension)	“Chat only” — no tools, no workspace, no replay
Terminal-first users on macOS / Linux / Windows — full-screen `zagens-tui` with the same engine as desktop	Fully autonomous YOLO agents with no guardrails
Teams working on long code refactors in one auditable workflow	Zero-setup mobile or browser-only experience
People who care about local sidecar architecture, MCP/skills, and exec approval in the UI	Teams that only want a web copilot with no local execution
Windows desktop users today; macOS/Linux via TUI, CLI, or source build

Three things that define Zagens

1. Harness, not a chat shell — Long-horizon code tasks use composable completion gates (operator / model / toolchain layers), not “the model said it’s finished.” Spec: LHT · fixtures: fixtures/harness/.

2. Multiple surfaces, one engine — Tauri 2 desktop or full-screen zagens-tui (ratatui) or headless zagens CLI — all run Kernel V3 (LiveTurnMachine + EffectInterpreter, event-sourced turns, log-first session resume). Desktop adds tray, WebView panels, embedded PTY, and sidecar supervision; TUI adds three-column transcript/composer/inspector + LHT panel in the terminal.

3. One code agent surface — Desktop Composer exposes Auto / Code task types (legacy Office preference migrates to Code). For document workflows, use load_skill zagens-office plus an external Office CLI — not a separate built-in Office mode.

Also shipped: CRAFT multi-agent (sub-agents, fix-loop verdicts, P1 blackboard — notes), lazy symbol index (.zagens/symbols.json), MCP, skills, hooks, scheduled tasks / night queue, batch_edit / refactor_imports bulk code tools.

Problems we focus on

Pain	How Zagens approaches it
Agent stops mid-task or marks work complete prematurely	Layered completion gates + long-horizon task panel (composable harness)
IDE plugins vs terminal agents don’t share one session story	Single sidecar + SQLite threads, fork/resume, replay, workspace snapshots
Running tools locally without blind trust	Exec policy, network rules, path canonicalization, approval UI, runtime token kept out of the WebView (sandbox matrix)

Shipped today (v0.9.0)

Office → zagens-office (breaking): Built-in Office mode / write_office / read_office and bundled PBS Python removed; document workflows use skill zagens-office + external CLI via exec_shell (hard route). Desktop streaming stability: multi-turn/restore id collisions, mid-turn replace, lossy delta dedup, dual live frames fixed. Browser P0 + Windows CDP: shared URL policy, session allowlist, CDP interact/snapshot. Windows exec_shell: host-aware description, spawn alignment, output spill, [agent] shell.

Desktop streaming UX: Live transcript no longer blanks during deep tool loops; SSE reconnect after transient proxy errors; compact Hold panel + streaming reasoning; throttled Browser preview hints. Harness file-changes card: live session edit list with +/- stats, click-through to Diff.

Tool evidence + intent composites: Evidence envelope (facts / citations / uncertainty) + citation auditor; investigate / answer_from_repo / change_and_verify; claim↔evidence nudge; promote_to_context + differential read_file; noisy-tool compact. Shared model catalog / providers.toml SSOT; first-class Moonshot / Kimi K3. Audit scratchpad completion gates + force import.

Desktop Browser pane: Embedded WebView (with windowed fallback); agent tools browser_navigate / snapshot / click·type·scroll / wait / preview; URL policy + session allowlist; YOLO separate from global auto-approve. Diff thin-layer Git: workspace status / changes / file-diff / read-only PRs; Diff-tab badge; force-push approval banner. Night queue stop/cancel/retry/clear controls. Integrated terminal lifecycle + shell UX. Zagens Neural Ring icon.

Harness 2026 H2 (Phase 0–4): Predicate library + HarnessVerifyLoop; night queue (zagens queue + desktop panel + schedule/hooks); skill stage gates; Gate-as-Code (zagens gate); draft_skill + promote; T5 explore_codebase / edit_and_check; Agent health (GET /v1/agent-health); replay pack + zagens trace benchmark. Specs: docs/harness/.

Desktop streaming timeline: Interleaved thinking / tool / text blocks with activity bundles, settled auto-collapse, and long-turn scanability (workflow / sub-agent / browser collapse). Sub-agent step journals (anti-black-box). LHT verify-hygiene + live completion-gate status.

Kernel V3 engine: event-sourced turn loop — KernelEvent log in sessions.db, LiveTurnMachine planning, EffectInterpreter IO, golden replay fixtures. Spec: AGENT_KERNEL_V3.md.

Desktop (Tauri): Browser + Diff + night-queue controls; Agent health side panels; streaming timeline; Dusk theme; git worktree parallel sessions; checkpoint/rewind and channels; model providers panel; per-session config overlay; integrated PTY; Kernel Trace Report export. UI in zh-Hans / en / ja / pt-BR.

Terminal TUI (zagens-tui): full-screen three-column shell — sessions rail, streaming transcript + thinking/tools, composer with /model and /lht, approval modal, inspector (files / diff / checklist / context / agents / MCP), collapsible LHT lower pane, theme presets, session restore (--fresh for clean start). Same runtime threads and Kernel V3 path as desktop.

Runtime: threads, MCP, skills, lifecycle hooks, multi-provider routing, vision; night-queue / agent-health / symbol-index APIs; GET/PUT/DELETE /v1/threads/{id}/config; global thread.status SSE; POST /v1/threads/{id}/events channel injection.

Tools (representative): files, git, exec_shell, T4 assert_*, T5 composites, intent composites (investigate / answer_from_repo / change_and_verify), optional web_search / fetch_url, memory tools; Office files via skill zagens-office. Full list: crates/runtime-server/src/tools/ · CHANGELOG.md.

Known limits (read before you rely on us)

We prefer honest scope over marketing checklists.

Topic	Status
Desktop installers	Windows installer on Releases. macOS / Linux desktop packages — planned. `zagens` CLI and `zagens-tui` binaries ship for all three platforms today.
OS sandbox enforcement	macOS Seatbelt — enforced when `sandbox-exec` is available. Windows — native sandbox enforced after setup (`elevated` recommended: profile read isolation + WFP; `unelevated` fallback: workspace write isolation only). Settings → Sandbox first-run wizard. Linux — policy declared, not OS-enforced yet (degraded). Details: `SANDBOX_CAPABILITY_MATRIX.md`.
Providers	Optimized for DeepSeek V4 (Pro / Flash); you bring API keys. Other OpenAI-compatible endpoints supported — we do not host models.
Long-horizon & multi-agent	Gates and CRAFT are production-usable but still evolving; edge cases and new gate types land in active development.
Document workflows	Built-in Office mode removed; use skill `zagens-office` + external CLI. See OFFICE_SCENARIOS.md (deprecated memo).

Report security issues via SECURITY.md.

Where we’re headed

Public design specs live under docs/. Directionally:

Platform parity — macOS/Linux desktop installers; Linux native sandbox (Landlock/bwrap). Windows native sandbox shipped in 0.7.x.
Trustworthy long tasks — tighter completion gates, harness fixtures, and replay-friendly operator workflows.
Hardening — security and exec-policy improvements tracked in CHANGELOG and SECURITY.md.

Quick start

Zagens Desktop (Windows)

GitHub Releases ships the Windows desktop installer (*-setup.exe.zip). macOS / Linux desktop packages are planned. SmartScreen: SMARTSCREEN.md.

CLI & TUI — by platform

Surface	Linux	macOS	Windows
`zagens-tui` (full-screen terminal UI)	✅	✅	✅
`zagens` (headless CLI)	✅	✅	✅
Desktop app	— (use TUI)	— (use TUI)	✅ installer

Install via pre-built binaries (Releases zagens-v0.9.0), cargo install (crates.io), or from source (below).

Rust prerequisite (cargo install / source only): install rustup (Rust 1.88+; CI pins 1.96). Then source "$HOME/.cargo/env" (Linux/macOS) or open a new terminal (Windows).

Linux (Ubuntu / Debian)

sudo apt update
sudo apt install -y build-essential curl pkg-config libssl-dev libdbus-1-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# TUI (first compile may take 10–30 min)
cargo install zagens-cli --version 0.9.0 --bin zagens-tui --features tui --locked

# Headless CLI (optional)
cargo install zagens-cli --version 0.9.0 --bin zagens --locked

Pre-built (no Rust required): download zagens-tui-x86_64-unknown-linux-gnu and/or zagens-x86_64-unknown-linux-gnu from Releases, verify the matching .sha256, chmod +x, and move into a directory on your PATH.

zagens-tui              # resume last session
zagens-tui --fresh      # new session

macOS

xcode-select --install    # if the C toolchain is missing
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

cargo install zagens-cli --version 0.9.0 --bin zagens-tui --features tui --locked
cargo install zagens-cli --version 0.9.0 --bin zagens --locked   # optional

Pre-built: zagens-tui-x86_64-apple-darwin or zagens-tui-aarch64-apple-darwin (Intel vs Apple Silicon) on Releases.

Windows

Pre-built (fastest): Releases — zagens-tui-x86_64-pc-windows-msvc.exe, zagens-x86_64-pc-windows-msvc.exe (+ .sha256). Add the folder to PATH or copy the .exe files into a directory on PATH.

crates.io (install Rust for Windows first):

cargo install zagens-cli --version 0.9.0 --bin zagens-tui --features tui --locked
cargo install zagens-cli --version 0.9.0 --bin zagens --locked

crates.io (all platforms)

cargo install zagens-cli --version 0.9.0 --bin zagens-tui --features tui --locked   # TUI
cargo install zagens-cli --version 0.9.0 --bin zagens --locked                   # CLI
cargo install zagens-cli --version 0.9.0 --bin zagens-runtime --locked           # HTTP sidecar (optional)

From source — desktop

git clone https://github.com/didclawapp-ai/zagens.git
cd zagens

cargo build -p zagens-cli          # copies zagens-runtime into crates/desktop/binaries/

cd crates/desktop/web-ui && npm install
cd .. && cargo tauri dev

# API key: Zagens Settings, or ~/.zagens/config.toml

From source — terminal TUI

cargo build -p zagens-cli --features tui --bin zagens-tui
./target/debug/zagens-tui          # restore last session; --fresh for new session

API key: DEEPSEEK_API_KEY, ~/.zagens/config.toml, TUI /api-key / first-run onboarding, or zagens login --api-key <key>. Legacy ~/.deepseek/config.toml is read if present but new installs use ~/.zagens/.

Headless CLI examples:

zagens doctor
zagens exec 'summarize src/' --json
zagens exec 'refactor auth module' --auto
zagens serve --http --port 7878

Config reference: config.example.toml.

Architecture

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Zagens Desktop  │  │   zagens-tui     │  │  zagens CLI      │
│  Tauri + WebView │  │  ratatui TUI     │  │  exec / serve    │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         │ HTTP+SSE (loopback) │ in-process          │ in-process / HTTP
         ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│  zagens-runtime sidecar  ·  Kernel V3 turn engine               │
│  LiveTurnMachine → EffectInterpreter → V3TurnHost               │
│  /v1/threads · MCP · skills · tools · kernel_events log         │
└───────────────────────────────┬─────────────────────────────────┘
                                ▼
         zagens-core · runtime-orchestrator · runtime-adapters

Full boundaries: docs/tech/RUNTIME_ARCHITECTURE.md · Kernel V3: docs/tech/AGENT_KERNEL_V3.md · HTTP contract: docs/tech/API_DESIGN.md.

Security modes (`sandbox_mode`)

Mode	Description
`read-only`	No shell execution or file writes
`workspace-write`	Shell and writes within the workspace (recommended default)
`danger-full-access`	Full filesystem access — use with caution
`external-sandbox`	Route `exec_shell` through an OpenSandbox-compatible API

Approval policies (on-request / untrusted / never), per-domain network rules, OS keyring for credentials. Runtime token never enters the WebView.

Development

Prerequisites: Rust 1.88+ (MSRV; CI pins 1.96), Node.js 20 LTS, Python 3.8+, Tauri CLI 2.

See CONTRIBUTING.md and LOCAL_DEV_VERIFY.md.

Command	Description
`just check`	PR gate: verify + workspace tests + web-check (`justfile` L2)
`just verify-all`	Push gate: verify + tests + multi-session + lockfile (L3)
`just verify`	CI lint mirror — toolchain + prebuild + fmt + clippy (L1)
`just web-check`	Web UI: tsc + ESLint + Vitest
`just --list`	All recipes with tier guide in justfile header
`bash scripts/ci/verify-lint.sh`	Same as `just verify` (direct script)
`bash scripts/ci/verify-workspace.sh`	Same as `just verify-all`
`cargo test --workspace --all-features`	Rust tests only (`just test-all` adds prebuild)
`cd crates/desktop && cargo tauri dev`	Launch desktop in dev mode

Windows: just verify or pwsh -File scripts/ci/verify-lint.ps1. Cursor: Run Task → Zagens:*

zagens/
├── crates/desktop/        # Tauri desktop app
├── crates/runtime-server/ # zagens-runtime sidecar · zagens CLI · zagens-tui (feature `tui`)
├── crates/core/           # Kernel V3 engine (LiveTurnMachine, kernel events)
├── docs/                  # Public design specs
├── fixtures/harness/      # LHT / kernel replay fixtures
└── config.example.toml