# 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](https://github.com/ratatui-org/ratatui) and [crossterm](https://github.com/crossterm-rs/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](https://modelcontextprotocol.io/) 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 ```bash # Run in single-process mode (default) zesdex # Run as a background daemon zesdex --daemon # Attach to a running daemon session zesdex --attach # 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