Zesdex

Autonomous AI coding agent in a terminal-based TUI.

Zesdex is a Rust-powered AI assistant that operates directly in your terminal via a rich TUI interface. It combines large language model intelligence with a comprehensive set of tools to explore, understand, and modify codebases autonomously — with built-in guardrails at every layer.

---

Features

Core

• TUI Interface — Full-screen terminal UI with chat panel, input bar, and status bar built with ratatui and crossterm.
• Daemon Architecture — Run as a background daemon with client attach/detach via Unix domain sockets. The daemon processes state; clients only render.
• IPC Protocol — Bidirectional state synchronization between daemon and client processes with diff-based updates.
• Provider Agnostic — Configurable AI model providers with dynamic model selection, per-role temperature/token limits, and API key management.

Tool System (34 built-in tools)

Category	Tools
Filesystem	read, write, edit, delete
Search	grep (recursive text), glob (file patterns)
Shell	bash, bash_output, bash_kill
Git	git_operator, git_worktree, git_cred
Memory	remember, recall, forget
Planning	plan_enter, plan_ready, seqthink
Workflow	workflow_run, note_finding, company_pipeline
Utility	cd, dir_list, dir_cache_update, pong, todowrite, todofinish
LSP	lsp_connect, lsp_diagnostics, lsp_hover, lsp_completion, lsp_definition, lsp_references, lsp_disconnect

Intelligence

• Company Pipeline — Autonomous agent orchestration modeled as a company with specialized divisions. The CEO (main agent) automatically delegates work to 5 divisions in sequence:

  Strategy → Engineering → Quality → Security → Documentation
  

  Each division has a dedicated role, toolset, and system prompt. Controlled via /pipeline full|quick|skip.

• Workflow Engine — Orchestrate complex multi-step tasks with parallel sub-agents, pipelines, and phased execution. Spawn independent workers that share findings in real-time.

• Self-Learning — Persistent memory system that stores lessons, references, and project knowledge across sessions. Memories include provenance tracking, lifecycle management, and scope isolation.

• Self-Review — Review subagents trigger automatically after each code edit (inline) and at turn completion (background). Three types: code quality, architecture, and security.

• Self-Healing — On build/test failures, spawns a sub-agent with the error context to autonomously fix issues before reporting them to the user.

• MCP Support — Model Context Protocol integration for connecting to external AI tool servers.

• Sequential Thinking — Chain-of-thought reasoning tool for step-by-step problem decomposition.

• Session Locking — Prevents multiple processes from operating on the same session directory.

Session Management

• Multiple concurrent sessions with history, rewind, and transcript persistence.
• Per-session edit logs with full change tracking.
• Session archival and summary generation.

---

Architecture

src/
├── main.rs                    # Entry point: single-process, daemon, or attach mode
├── resources.rs               # Embedded resources (help text, system prompts)
├── app/
│   ├── state/                 # AppStateRest — immutable-rest state model
│   │   ├── rest.rs            # Core state struct
│   │   ├── types.rs           # Overlay, Toast, Origin enums
│   │   ├── snapshot.rs        # State snapshots for IPC
│   │   ├── diff.rs            # Diff-based state synchronization
│   │   ├── runtime.rs         # Runtime state mutations
│   │   └── misc.rs            # DirCache and miscellaneous state helpers
│   ├── runtime/               # Action dispatch and event loop
│   │   ├── actions/           # Action enum and apply_action reducer
│   │   ├── stream/            # LLM streaming and tool execution
│   │   │   └── tools/         # Tool harness integration
│   │   │   └── turn.rs        # Turn orchestration
│   │   ├── event_loop/        # Main event loop and shortsend
│   │   ├── commands.rs        # Slash command dispatch
│   │   └── shortsend.rs       # Short-lived async send helper
│   ├── mode/                  # UI modes and overlays (13 modes)
│   │   ├── bash.rs            # Bash panel mode
│   │   ├── editor.rs          # Multi-line editor mode
│   │   ├── effort.rs          # Effort level selector
│   │   ├── help.rs            # Help overlay
│   │   ├── key_input.rs       # Raw key input mode
│   │   ├── loading.rs         # Loading spinner overlay
│   │   ├── mcp.rs             # MCP server management
│   │   ├── quit_confirm.rs    # Quit confirmation dialog
│   │   ├── rewind.rs          # Session rewind mode
│   │   ├── settings.rs        # Settings panel
│   │   ├── todo.rs            # Task list overlay
│   │   └── workflow.rs        # Workflow visualization
│   ├── harness.rs             # Tool harness for agent execution
│   ├── workflow/              # Workflow engine
│   │   ├── script.rs          # Workflow script DSL
│   │   ├── engine.rs          # Workflow executor
│   │   └── company.rs         # Company pipeline orchestrator
│   ├── mcp/                   # MCP client manager
│   │   └── manager.rs         # MCP server lifecycle and tool exposure
│   ├── subagent/              # Sub-agent management
│   │   ├── spawn.rs           # AgentDefinition and spawning
│   │   ├── engine.rs          # Sub-agent event loop
│   │   ├── context.rs         # Context construction for sub-agents
│   │   └── event.rs           # Progress event types
│   ├── bgbash/                # Background bash job management
│   │   ├── job.rs             # Background job handle
│   │   └── control.rs         # Bash control (bg/fg/kill)
│   ├── lsp/                   # LSP client management
│   │   ├── client.rs          # LSP client connection wrapper
│   │   └── provisioner.rs     # Auto-provisioning of LSP servers
│   └── review/                # Self-review quality system
├── controller/
│   ├── input.rs               # Key event → Action mapping
│   └── command.rs             # Slash command parser
├── dto/
│   ├── chat/                  # Message, ToolCall, Role types
│   │   ├── message.rs         # Chat message types
│   │   ├── tool.rs            # Tool call/result types
│   │   └── mod.rs
│   └── provider/              # AI provider request/response/usage types
│       ├── request.rs         # Provider request schema
│       ├── response.rs        # Provider response schema
│       └── usage.rs           # Token usage tracking
├── ipc/
│   ├── protocol.rs            # ClientRequest, DaemonFrame, StatePayload
│   ├── server.rs              # Unix socket server
│   ├── client.rs              # Unix socket client
│   ├── conn.rs                # Framed connection
│   ├── frame.rs               # Length-prefixed frame encoding
│   ├── snapshot.rs            # State snapshot serialization
│   └── diff.rs                # Binary diff for state sync
├── model/
│   ├── store.rs               # File-based storage (~/.config/zesdex/)
│   ├── session.rs             # Session CRUD and listing
│   ├── settings.rs            # User settings (provider, model, tokens)
│   ├── app_config.rs          # Provider definitions and model roles
│   ├── memory.rs              # Persistent memory with frontmatter
│   ├── editlog.rs             # Edit history tracking
│   ├── msglog/                # Message log (SQLite-backed)
│   │   ├── schema.rs          # SQLite schema
│   │   ├── query.rs           # Query helpers
│   │   ├── blobs.rs           # Large blob storage
│   │   └── summary.rs         # Session summarization
│   ├── agent_def/             # Agent definitions (builtin, global, session)
│   │   ├── builtin.rs         # Built-in agent profiles
│   │   ├── global.rs          # Global agent config
│   │   └── session.rs         # Per-session agent config
│   ├── conversation.rs        # Conversation helpers
│   └── session_lock.rs        # Flock-based session locking
├── service/
│   ├── provider.rs            # AI provider abstraction
│   └── oauth/                 # OAuth PKCE flow with loopback server
│       ├── loopback.rs        # Local HTTP server for OAuth redirect
│       ├── manager.rs         # OAuth token manager
│       ├── pkce.rs            # PKCE code challenge/verifier
│       └── mod.rs
├── tool/                      # 34 tool implementations
│   ├── fs/                    # read, write, edit, delete
│   │   ├── read.rs
│   │   ├── write.rs
│   │   ├── edit.rs
│   │   ├── delete.rs
│   │   └── helpers.rs         # Path resolution and validation
│   ├── search.rs              # grep, glob
│   ├── shell.rs               # bash
│   ├── bash_tools.rs          # bash_output, bash_kill
│   ├── git_operator.rs        # git operations
│   ├── git_worktree.rs        # git worktree management
│   ├── git_cred.rs            # git credential store/get/erase
│   ├── memory/                # remember, forget, recall
│   │   ├── remember.rs
│   │   ├── forget.rs
│   │   └── recall.rs
│   ├── plan.rs                # plan_enter, plan_ready
│   ├── seqthink.rs            # Sequential thinking
│   ├── workflow.rs            # workflow_run, note_finding
│   ├── utility/               # cd, dir_list, dir_cache_update, pong, todowrite, todofinish
│   │   ├── cd.rs
│   │   ├── dir_list.rs
│   │   ├── dir_cache_update.rs
│   │   ├── pong.rs
│   │   ├── todowrite.rs
│   │   └── todofinish.rs
│   ├── lsp/                   # LSP tools (connect, diagnostics, hover, etc.)
│   │   └── mod.rs
│   └── shell_filter/          # Shell output filtering (credentials, git)
│       ├── credentials.rs
│       ├── git.rs
│       └── mod.rs
└── view/                      # TUI rendering
    ├── chat.rs                # Chat transcript with markdown
    ├── markdown.rs            # Markdown → ratatui spans
    ├── status.rs              # Status bar
    ├── theme.rs               # Color scheme
    └── workflow.rs            # Workflow visualization

---

Usage

# Run in single-process mode (default)
zesdex

# Run as a background daemon
zesdex --daemon

# Attach to a running daemon session
zesdex --attach <session-id>

# Set log level
RUST_LOG=debug zesdex

Key Bindings

Binding	Action
Ctrl+Q	Quit
Ctrl+H	Help overlay
Ctrl+P	Settings overlay
Ctrl+B	Bash panel
Ctrl+S	Session hub
Ctrl+T	Task list
Ctrl+W	Workflow view
Ctrl+K	Key input mode
Esc	Cancel / back
Tab	Autocomplete
↑/↓	History / navigation
Scroll	Mouse scroll in chat

Slash Commands

Command	Description
/help	Show help
/clear	Clear transcript
/model	Select AI model provider
/pipeline	Show current pipeline mode
/pipeline full	Force full company pipeline (5 divisions) on next request
/pipeline quick	Force quick pipeline (3 divisions) on next request
/pipeline skip	Skip pipeline — handle next request directly
/exit	Exit application
/settings	Open settings
Any text	Sent to the AI assistant as a prompt

---

Configuration

All configuration lives in ~/.config/zesdex/ (or platform equivalent via the dirs crate).

File	Purpose
settings.json	Provider selection, model, temperature, max tokens, review settings, workflow concurrency
app_config.json	AI provider definitions (name, API base URL, auth type, default model)
memory/	Persistent lesson and reference storage (Markdown with YAML frontmatter)
sessions/	Per-session transcripts, edit logs, and activity data
run/	Unix domain sockets for daemon mode

Provider Configuration

Providers are defined in app_config.json:

{
  "providers": {
    "my-provider": {
      "api_base": "https://api.example.com/v1",
      "api_key_env": "MY_API_KEY",
      "default_model": "model-name"
    }
  },
  "model_roles": {
    "default": {
      "provider": "my-provider",
      "model": "model-name",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "default_provider": "my-provider",
  "default_model": "model-name"
}

Settings

Key settings in settings.json:

Setting	Default	Description
review_enabled	true	Enable self-review after tool execution
review_max_lessons_per_run	5	Max lessons loaded per review cycle
adaptive_review_max_skip	3	Consecutive passes before skipping review
verify_command	null	Optional command to verify changes
workflow_max_concurrency	5	Max parallel sub-agents in workflows
session_archive_enabled	true	Auto-archive completed sessions

---

Installation

Prerequisites

• Rust 2021 edition toolchain (rustup)

Build from Source

git clone <repository-url>
cd zesdex
cargo build --release
./target/release/zesdex

---

License

See LICENSE for details.