zesdex/README.md

Zesdex

Autonomous AI coding and security agent running in a terminal-based TUI environment.

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.

Features

• TUI Interface — Full-screen terminal UI with chat panel, input bar, and status bar built with ratatui and crossterm.
• Multi-Agent Modes — Auto (full autonomy), Normal (review risky ops), Plan (no mutations), Yolo (unrestricted).
• Rich Tool System — 20+ built-in tools for file operations, searching, bash execution, git operations, web access, memory management, and workflow orchestration.
• Daemon Architecture — Run as a background daemon with client attach/detach via Unix domain sockets.
• IPC Protocol — Bidirectional state synchronization between daemon and client processes.
• MCP Support — Model Context Protocol integration for connecting to external AI servers.
• Self-Learning — Persistent memory system that stores lessons, references, and project knowledge.
• Workflow Engine — Orchestrate complex multi-step tasks with parallel sub-agents, pipelines, and phased execution.
• Security Guardrails — Catastrophic operation detection, credential exfiltration monitoring, graduated safety checks.
• Security Sidecar — Python-based security analysis daemon for vulnerability scanning.
• Provider Agnostic — Configurable AI model providers with dynamic model selection.
• Session Management — Multiple sessions with history, rewind, and transcript persistence.

Architecture

src/
├── main.rs                    # Entry point, single/daemon/attach modes
├── app/                       # Application core
│   ├── state/                 # State management (AppStateRest, types, misc)
│   ├── runtime/               # Action dispatch and event loop
│   ├── mode/                  # Agent mode definitions (Auto/Normal/Plan/Yolo)
│   ├── harness.rs             # Tool harness for agent execution
│   ├── workflow/              # Workflow engine (script, engine)
│   ├── mcp/                   # Model Context Protocol manager
│   ├── sec/                   # Security daemon integration
│   ├── subagent/              # Sub-agent orchestration
│   ├── bgbash/                # Background bash job management
│   └── review/                # Self-review quality system
├── controller/                # Input handling and command dispatch
│   ├── input.rs               # Key event processing
│   └── command.rs             # Slash command parser
├── dto/                       # Data transfer objects
│   ├── chat/                  # Message types
│   └── provider/              # AI provider request/response types
├── ipc/                       # Inter-process communication
│   ├── protocol.rs            # Message protocol definition
│   ├── server.rs              # Unix socket server
│   ├── client.rs              # Unix socket client
│   ├── conn.rs                # Connection framing
│   ├── frame.rs               # Frame encoding/decoding
│   ├── snapshot.rs            # State snapshot
│   └── diff.rs                # State diffing
├── model/                     # Data models
│   ├── store.rs               # File-based storage
│   ├── session.rs             # Session management
│   ├── settings.rs            # User settings
│   ├── app_config.rs          # Provider configuration
│   ├── memory.rs              # Persistent memory
│   ├── editlog.rs             # Edit history log
│   ├── msglog/                # Message log persistence
│   ├── agent_def/             # Agent definitions
│   └── session_lock.rs        # Session locking
├── security/                  # Security installation utilities
│   └── install.rs             # Sidecar binary management
├── service/                   # External service integrations
│   ├── provider.rs            # AI provider abstraction
│   └── oauth/                 # OAuth authentication
├── tool/                      # Tool implementations
│   ├── fs/                    # read, write, edit, delete
│   ├── search.rs              # grep, glob
│   ├── shell.rs               # bash execution
│   ├── bash_tools.rs          # bash_output, bash_kill
│   ├── git_operator.rs        # git operations
│   ├── git_worktree.rs        # git worktree management
│   ├── git_cred.rs            # git credential management
│   ├── internet/              # fetch, download, search
│   ├── memory/                # remember, forget, recall
│   ├── 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
│   └── shell_filter/          # Shell output filtering
├── view/                      # TUI rendering
│   ├── chat.rs                # Chat transcript panel
│   ├── markdown.rs            # Markdown rendering
│   ├── status.rs              # Status bar
│   ├── theme.rs               # Color scheme
│   └── workflow.rs            # Workflow visualization
└── resources.rs               # Embedded resources (help text, prompts)

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+A	Cycle agent mode
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

Slash Commands

Command	Description
/help	Show help
/clear	Clear transcript
/model	Select AI model provider
/exit	Exit application
/settings	Open settings
/session	Session management

Agent Modes

• Auto — Full autonomy. The agent can read, write, edit files, run bash commands, and execute git operations without confirmation.
• Normal — Risky operations (write, delete, edit, bash, destructive git) require manual approval.
• Plan — Planning mode. The agent can analyze and propose changes but cannot execute mutations.
• Yolo — Unrestricted mode. Full autonomy with no confirmation prompts.

Security

Zesdex includes multiple layers of security:

• Catastrophic Guard — Detects and blocks destructive operations (rm -rf, force push, credential exfiltration) across all modes.
• Graduated Checks — Content-aware pattern matching for common danger zones (API keys, passwords, git credentials).
• Security Sidecar — Optional Python daemon for deep vulnerability scanning.
• Session Locking — Prevents multiple processes from operating on the same session directory.
• Workspace Isolation — All file operations are validated against workspace roots.

Installation

Prerequisites

• Rust 2021 edition toolchain
• (Optional) Python 3 for the security sidecar

Build from source

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

Security sidecar (optional)

pip install -r security-sidecar/requirements.txt

Configuration

Configuration is stored in ~/.config/zesdex/ (or platform equivalent). Key files:

• config.yaml — Provider settings, default model, temperature, max tokens
• app_config.yaml — AI provider definitions (name, URL, auth type)
• memory/ — Persistent lesson and reference storage
• sessions/ — Per-session transcripts and activity logs