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

```bash
# 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

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

### Security sidecar (optional)

```bash
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