zesdex/README.md

Zesdex

Autonomous AI coding and security 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 security 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 (28 built-in tools)

Category	Tools
Filesystem	read, write, edit, delete
Search	grep (recursive text), glob (file patterns)
Shell	bash (with catastrophic guard), bash_output, bash_kill
Git	git_operator, git_worktree, git_cred
Internet	fetch (URL→markdown), download, web_search
Memory	remember, recall, forget
Planning	plan_enter, plan_ready, seqthink
Workflow	workflow_run, note_finding
Utility	cd, dir_list, dir_cache_update, pong, todowrite

Intelligence

• 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 — Adaptive quality review system that evaluates completed work against stored lessons and project conventions.
• 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.

Security

• Catastrophic Guard — Detects and blocks destructive operations (rm -rf, force push, credential exfiltration) across all tool invocations.
• Graduated Checks — Content-aware pattern matching for common danger zones (API keys, passwords, git credentials) with configurable rules.
• Risky Tool Classification — Write, delete, edit, bash, and git operations are flagged for additional scrutiny.
• Workspace Isolation — All file operations are validated against workspace roots. Path traversal outside the workspace is rejected.
• Session Locking — Prevents multiple processes from operating on the same session directory.
• Security Sidecar — Optional Python daemon for deep vulnerability scanning (see below).

Session Management

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

---

Security Sidecar

An optional Python-based companion daemon that provides security analysis tools beyond what the core Rust binary offers.

Available Tools

Category	Tools	Required Binary
Web Security	sqlmap, nuclei, ffuf, dalfox, zap, xss_confirm, http	sqlmap, nuclei, ffuf, dalfox, zap-cli, curl
Cryptography	z3, sage, rsa, factordb, hashcat, hashid, decode	z3, sage, hashcat, hashid
Reverse Engineering	js_deobfuscate, sourcemap, wasm_decompile	npx, wasm-decompile
Binary Exploitation	triage, ropgadget, pwntools, exploit_template	file, checksec, ROPgadget, python3

Installation

pip install -r security-sidecar/requirements.txt

# Optional: install full extras for crypto/pwn tools
pip install -r security-sidecar/requirements.txt[full]

Health Check

python -m zesdex_sec_daemon --health

---

Architecture

src/
├── main.rs                    # Entry point: single-process, daemon, or attach mode
├── 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
│   ├── runtime/               # Action dispatch and event loop
│   │   ├── actions/           # Action enum and apply_action reducer
│   │   ├── stream/            # LLM streaming and tool execution
│   │   │   └── tools/         # Tool harness integration
│   │   ├── event_loop/        # Main event loop and shortsend
│   │   └── commands.rs        # Slash command dispatch
│   ├── mode/                  # UI modes and overlays (16 overlays)
│   ├── harness.rs             # Tool harness for agent execution
│   ├── workflow/              # Workflow engine (script DSL, executor)
│   ├── mcp/                   # MCP client manager
│   ├── sec/                   # Security sidecar integration
│   ├── subagent/              # Sub-agent spawn, context, events
│   ├── bgbash/                # Background bash job management
│   ├── review/                # Self-review quality system
│   └── catastrophic.rs        # Catastrophic operation detection
├── controller/
│   ├── input.rs               # Key event → Action mapping
│   └── command.rs             # Slash command parser
├── dto/
│   ├── chat/                  # Message, ToolCall, Role types
│   └── provider/              # AI provider request/response/usage types
├── 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)
│   ├── agent_def/             # Agent definitions (builtin, global, session)
│   └── session_lock.rs        # Flock-based session locking
├── security/
│   └── install.rs             # Sidecar binary management
├── service/
│   ├── provider.rs            # AI provider abstraction
│   └── oauth/                 # OAuth PKCE flow with loopback server
├── tool/                      # 28 tool implementations
│   ├── fs/                    # read, write, edit, delete
│   ├── search.rs              # grep, glob
│   ├── shell.rs               # bash (with catastrophic guard)
│   ├── 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
│   ├── internet/              # fetch, download, web_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 (credentials, git)
├── 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
└── resources.rs               # Embedded resources (help text, system 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	Toggle yolo arm
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
/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
bin/	Security sidecar binary
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
internet_mode	Off	Off, ReadOnly, or Full
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)
• Python 3 (optional, 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

For full crypto and pwn tool support:

pip install pycryptodome factordb-python pwntools ropper

---

License

See LICENSE for details.