Zesdex — Autonomous AI Coding Agent
Zesdex is an autonomous AI coding agent with a Terminal UI (TUI). It acts as an OpenAI/Anthropic-compatible LLM client wrapped in a tool-use harness with 37 built-in tools — file operations, git, shell execution, LSP integration, MCP, subagent orchestration, and more.
┌──────────────────────────────────────────────────────────────┐
│ Mode Selector │
│ TUI (default) ─── Daemon ─── Attach ─── API ─── WS/gRPC/Web │
└──────────────────────────────────────────────────────────────┘
Quick Start
# Run the TUI (default mode)
cargo run
# Run the REST API server
cargo run -- --api --api-port 8080
# Run in daemon mode (background + IPC)
cargo run -- --daemon
# Attach TUI to a running daemon session
cargo run -- --attach <session-id>
# Seed initial data (first run)
cargo run --bin bootstrap
Prerequisites
- Rust 1.81+ (edition 2021)
- Linux or macOS (Unix domain sockets required for daemon mode)
- An API key for an OpenAI/Anthropic-compatible LLM provider (set via settings or environment variable)
Modes
| Flag | Mode | Description |
|---|---|---|
| (none) | TUI | Full terminal UI with chat, overlays, and agent loop in one process |
--daemon |
Daemon | Background daemon with IPC socket; clients attach separately |
--attach <id> |
Attach | Connect TUI to an existing daemon session via Unix socket |
--api |
REST API | HTTP server with session management and chat endpoints |
--ws |
WebSocket | WebSocket server for real-time communication |
--grpc |
gRPC | gRPC server for programmatic access |
--web |
Web | Serves the web frontend |
--api-port, --ws-port, --grpc-port, --web-port |
(ports) | Configure server ports (defaults: 8080, 8081, 50051, 3000) |
Architecture
Clean Architecture Layering
apps/
├── domain/ # Pure entities, value objects, repository/service traits
│ # Zero framework deps — only serde + chrono + uuid
├── application/ # Use-case services (auth, sessions, conversations, memory)
│ # Depends only on domain-layer trait interfaces
├── infrastructure/ # All I/O: LLM client, IPC, persistence, LSP, MCP, tools
│ # Implements domain/application port interfaces
└── interfaces/ # Entry points
├── tui/ # Ratatui terminal UI
├── api/ # Axum REST API
├── daemon/ # Unix socket daemon + client
├── ws/ # WebSocket server
├── grpc/ # gRPC server
└── web/ # Web frontend (static file server)
Tool System
37 tools across 9 categories:
| Category | Tools |
|---|---|
| File System | read, write, edit, delete, dir_list, dir_cache_update |
| Shell | bash, bash_interactive, bash_kill, bash_output |
| Git | git_operator, git_cred, git_worktree |
| Search | search, grep, glob, semantic_search |
| LSP | lsp_connect, lsp_hover, lsp_completion, lsp_definition, lsp_references, lsp_diagnostics, lsp_disconnect |
| Memory | remember, recall, forget |
| Workflow | spawn_agents, spawn_pipeline, plan, sequential_think, hive_mind |
| Utility | todo_write, todo_finish, pong, cd |
| Background | Background bash jobs with cancel/status/list |
Each tool implements the Tool trait:
pub trait Tool: Send + Sync {
fn name(&self) -> &'static str;
fn description(&self) -> &'static str;
fn parameters(&self) -> Value;
fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String>;
}
Hive Mind Orchestration
The multi-agent orchestration system compiles a cognitive cycle plan per
task — ordered cycles of parallel processing nodes. Each node has a directive
and an access tier (read / write / full). Node outputs merge into a
shared collective state in real time, and a final consensus synthesis
produces the unified result.
- Auto-trigger: Complex requests automatically use the hive mind
- Manual entry: The
hive_mindtool lets the LLM specify cycles explicitly - Live progress: TUI panel shows each node's status and current tool
- Guaranteed docs: Every convergence writes to
docs/runs/
IPC Protocol (Daemon Mode)
┌──────────┐ Unix socket ┌──────────┐
│ Client │ ◄──────────────► │ Daemon │
│ (TUI) │ length-prefixed│ │
└──────────┘ serde_json └──────────┘
Frame format: [4-byte BE length][JSON payload]
The daemon holds AppStateRest and drives the agent loop. Clients are stateless
renderers that receive full state snapshots after each action.
Built-in Features
| Feature | Description |
|---|---|
| LLM Provider | OpenAI/Anthropic-compatible API (streaming + non-streaming) with automatic retry and fallback |
| Tool Harness | Safety-gated tool execution with graduated review checks |
| Subagents | Auto-inline review, background test-gen, arch-review, security-review |
| OAuth 2.0 | PKCE flow for LLM provider authentication |
| MCP | Model Context Protocol server management (stdio + HTTP transport) |
| LSP | Language Server Protocol integration (completion, hover, diagnostics, references) |
| Session Mgmt | SQLite-persisted sessions with lock-based concurrency control |
| Memory | File-based memory system with frontmatter metadata |
| Edit Log | Append-only edit history with configurable retention |
| Rate Limiting | Sliding-window per-client rate limiter |
| JWT Auth | HS256 JWT access/refresh tokens (API mode) |
| Password Auth | Argon2 password hashing with pepper |
| OAuth Loopback | Localhost HTTP server for OAuth redirect capture |
| Background Jobs | Long-running shell jobs with cancellation and output collection |
| Settings | JSON-persisted settings with hot-reload |
TUI Overlays
16 overlays accessible from the terminal UI:
| Overlay | Purpose |
|---|---|
| Chat Input | Main input bar with autocomplete |
| Bash Panel | Interactive shell panel |
| File Editor | Built-in file editor |
| Effort Selector | LLM reasoning effort selector |
| Help | Keybindings reference |
| Key Input | Custom key binding configuration |
| Learning | Lesson viewer |
| Loading | Generating spinner |
| MCP Manager | MCP server management |
| Model Selector | LLM model picker |
| Quit Confirm | Exit confirmation dialog |
| Rewind | Message/history rewind |
| Settings | Settings panel |
| Todo | Task/TODO list |
| Usage | Token usage statistics |
| Workflow | Hive-mind node progress |
Data & Persistence
All data lives under the platform's data directory (~/.local/share/zesdex/):
~/.local/share/zesdex/
├── settings.json # User settings (provider, model, keys)
├── app_config.json # Provider definitions (endpoints, env vars)
├── sessions/ # Chat sessions (one subdirectory per session)
│ └── <uuid>/
│ ├── session.json # Session metadata
│ ├── messages.jsonl # Message log
│ └── .lock # Session lock file
└── memories/ # Memory files with frontmatter metadata
└── *.md
Development
# Build all crates
cargo build
# Run all unit tests (8 tests across 11 crates)
cargo test
# Run clippy linting
cargo clippy --all-targets
# Run with verbose logging
RUST_LOG=debug cargo run
Workspace Crates
| Crate | Path | Layer |
|---|---|---|
zesdex-domain |
apps/domain/ |
Pure domain entities & traits |
zesdex-application |
apps/application/ |
Use-case services |
zesdex-infrastructure |
apps/infrastructure/ |
All I/O & tool implementations |
zesdex-tui |
apps/interfaces/tui/ |
Ratatui terminal interface |
zesdex-api |
apps/interfaces/api/ |
Axum REST API |
zesdex-daemon |
apps/interfaces/daemon/ |
Unix socket daemon |
zesdex-ws |
apps/interfaces/ws/ |
WebSocket server |
zesdex-grpc |
apps/interfaces/grpc/ |
gRPC server |
zesdex-web |
apps/interfaces/web/ |
Web frontend |
zesdex-gateway |
apps/gateway/ |
CLI entry point & dispatcher |
zesdex-bootstrap |
apps/bootstrap/ |
Initial data seeder |
Code Map
Detailed architecture documentation is in docs/CODEMAPS/:
| File | Covers |
|---|---|
docs/CODEMAPS/architecture.md |
System layout, process modes, data flow |
docs/CODEMAPS/backend.md |
Provider, OAuth, IPC, workflow engine, MCP, LSP, review |
docs/CODEMAPS/frontend.md |
TUI render pipeline, 16 overlays, toasts, input handling |
docs/CODEMAPS/data.md |
Persistence, SQLite msglog, memory files, settings/config |
docs/CODEMAPS/dependencies.md |
All Rust crates and external services |
License
See CHANGELOG.md for release history.