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.