zesdex/README.md

# 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 (33 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` |
| **Utility** | `cd`, `dir_list`, `dir_cache_update`, `pong`, `todowrite`, `todofinish` |
| **LSP** | `lsp_connect`, `lsp_diagnostics`, `lsp_hover`, `lsp_completion`, `lsp_definition`, `lsp_references`, `lsp_disconnect` |

### 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.
- **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
│   │   ├── 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
│   ├── 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/                      # 33 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 <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+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 |
| `run/` | Unix domain sockets for daemon mode |

### Provider Configuration

Providers are defined in `app_config.json`:

```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 |
|---------|---------|-------------|
| `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](https://rustup.rs/))

### Build from Source

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


---

## License

See [LICENSE](LICENSE) for details.