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 (37 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, read_findings, hive_mind
Utility	cd, dir_list, dir_cache_update, pong, todowrite, todofinish
Agent	spawn_agents, spawn_pipeline
LSP	lsp_connect, lsp_diagnostics, lsp_hover, lsp_completion, lsp_definition, lsp_references, lsp_disconnect

Intelligence

• Hive-Mind Orchestration — Autonomous agent orchestration modeled as a distributed machine intelligence (à la Stellaris). The Core Intelligence (main agent) compiles a cognitive cycle plan per task — an ordered list of cycles, each a set of anonymous processing nodes that run in parallel. Every node carries only a directive (what to do) and an access tier (read/write/full); cycle count and nodes-per-cycle are decided per task, not fixed. Every node's output merges into a shared collective state the instant it completes, and a final synthesis node reconciles it into one consensus. Every convergence is written to docs/runs/*.md. Manual entry point: the hive_mind tool.

• 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
│   │   ├── learning.rs        # Lesson management overlay
│   │   ├── 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
│   │   ├── hive_mind.rs       # Hive-mind orchestrator
│   │   └── docs.rs            # Deterministic docs/runs/*.md writer
│   ├── 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
/workflow	Open the workflow panel
/workflow run <script>	Run a JSON-encoded workflow script
/mcp	Open MCP server manager
/mcp add <name> <command>	Add an MCP server
/login [provider]	Authenticate with a provider
/edit [path]	Open a file/dir in the external editor
/compact	Compact the conversation transcript
/lesson	Interactive lesson/memory review
/quit	Exit application
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

---

Development

Commit Convention

Project ini menggunakan Conventional Commits untuk otomatis menentukan versi rilis (melalui semantic-release).

Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

<type> — menentukan bump version:

Type	Bump	Keterangan
feat	minor	Fitur baru
fix	patch	Perbaikan bug
chore	patch	Tugas maintenance, refactor ringan
docs	patch	Perubahan dokumentasi
refactor	patch	Refactor kode (tanpa perubahan fungsional)
test	patch	Penambahan atau perbaikan test
style	patch	Perubahan formatting, whitespace, dll
perf	patch	Optimasi performa
ci	patch	Perubahan CI/CD

BREAKING CHANGE pada body commit → major (apa pun typenya).

Contoh:

feat(agent): add workspace-aware file search

Implement context-aware search scoped to current workspace directory.

BREAKING CHANGE: search results now filter by workspace scope.

fix(ipc): handle partial frame on unix socket reconnect

chore: update rustls to 0.23

Release Workflow

Push ke branch main akan memicu:

1. CI — cargo build --release + cargo test
2. Semantic Release — analisis commit → update Cargo.toml + CHANGELOG.md → git tag → GitHub Release dengan binary

---

License

See LICENSE for details.