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_mind tool 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.