zesdex/README.md

# Zesdex — Autonomous AI Coding Agent

Zesdex is an autonomous AI coding agent with a Terminal UI (TUI). It acts as an
OpenAI/Anthropic-compatible LLM client wrapped in a tool-use harness with **37
built-in tools** — file operations, git, shell execution, LSP integration, MCP,
subagent orchestration, and more.

```
┌──────────────────────────────────────────────────────────────┐
│                       Mode Selector                            │
│  TUI (default) ─── Daemon ─── Attach ─── API ─── WS/gRPC/Web │
└──────────────────────────────────────────────────────────────┘
```

---

## Quick Start

```bash
# Run the TUI (default mode)
cargo run

# Run the REST API server
cargo run -- --api --api-port 8080

# Run in daemon mode (background + IPC)
cargo run -- --daemon

# Attach TUI to a running daemon session
cargo run -- --attach <session-id>

# Seed initial data (first run)
cargo run --bin bootstrap
```

### Prerequisites

- **Rust** 1.81+ (edition 2021)
- **Linux** or **macOS** (Unix domain sockets required for daemon mode)
- An **API key** for an OpenAI/Anthropic-compatible LLM provider (set via
  settings or environment variable)

---

## Modes

| Flag | Mode | Description |
|------|------|-------------|
| *(none)* | **TUI** | Full terminal UI with chat, overlays, and agent loop in one process |
| `--daemon` | **Daemon** | Background daemon with IPC socket; clients attach separately |
| `--attach <id>` | **Attach** | Connect TUI to an existing daemon session via Unix socket |
| `--api` | **REST API** | HTTP server with session management and chat endpoints |
| `--ws` | **WebSocket** | WebSocket server for real-time communication |
| `--grpc` | **gRPC** | gRPC server for programmatic access |
| `--web` | **Web** | Serves the web frontend |
| `--api-port`, `--ws-port`, `--grpc-port`, `--web-port` | *(ports)* | Configure server ports (defaults: 8080, 8081, 50051, 3000) |

---

## Architecture

### Clean Architecture Layering

```
apps/
├── domain/          # Pure entities, value objects, repository/service traits
│                    # Zero framework deps — only serde + chrono + uuid
├── application/     # Use-case services (auth, sessions, conversations, memory)
│                    # Depends only on domain-layer trait interfaces
├── infrastructure/  # All I/O: LLM client, IPC, persistence, LSP, MCP, tools
│                    # Implements domain/application port interfaces
└── interfaces/      # Entry points
    ├── tui/         # Ratatui terminal UI
    ├── api/         # Axum REST API
    ├── daemon/      # Unix socket daemon + client
    ├── ws/          # WebSocket server
    ├── grpc/        # gRPC server
    └── web/         # Web frontend (static file server)
```

### Tool System

37 tools across 9 categories:

| Category | Tools |
|----------|-------|
| **File System** | `read`, `write`, `edit`, `delete`, `dir_list`, `dir_cache_update` |
| **Shell** | `bash`, `bash_interactive`, `bash_kill`, `bash_output` |
| **Git** | `git_operator`, `git_cred`, `git_worktree` |
| **Search** | `search`, `grep`, `glob`, `semantic_search` |
| **LSP** | `lsp_connect`, `lsp_hover`, `lsp_completion`, `lsp_definition`, `lsp_references`, `lsp_diagnostics`, `lsp_disconnect` |
| **Memory** | `remember`, `recall`, `forget` |
| **Workflow** | `spawn_agents`, `spawn_pipeline`, `plan`, `sequential_think`, `hive_mind` |
| **Utility** | `todo_write`, `todo_finish`, `pong`, `cd` |
| **Background** | Background bash jobs with `cancel/status/list` |

Each tool implements the `Tool` trait:
```rust
pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn parameters(&self) -> Value;
    fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String>;
}
```

### Hive Mind Orchestration

The multi-agent orchestration system compiles a **cognitive cycle plan** per
task — ordered cycles of parallel processing nodes. Each node has a directive
and an **access tier** (`read` / `write` / `full`). Node outputs merge into a
shared collective state in real time, and a final **consensus synthesis**
produces the unified result.

- **Auto-trigger**: Complex requests automatically use the hive mind
- **Manual entry**: The `hive_mind` tool lets the LLM specify cycles explicitly
- **Live progress**: TUI panel shows each node's status and current tool
- **Guaranteed docs**: Every convergence writes to `docs/runs/`

### IPC Protocol (Daemon Mode)

```
┌──────────┐   Unix socket    ┌──────────┐
│  Client   │ ◄──────────────► │  Daemon  │
│  (TUI)    │   length-prefixed│          │
└──────────┘   serde_json      └──────────┘

Frame format: [4-byte BE length][JSON payload]
```

The daemon holds `AppStateRest` and drives the agent loop. Clients are stateless
renderers that receive full state snapshots after each action.

---

## Built-in Features

| Feature | Description |
|---------|-------------|
| **LLM Provider** | OpenAI/Anthropic-compatible API (streaming + non-streaming) with automatic retry and fallback |
| **Tool Harness** | Safety-gated tool execution with graduated review checks |
| **Subagents** | Auto-inline review, background test-gen, arch-review, security-review |
| **OAuth 2.0** | PKCE flow for LLM provider authentication |
| **MCP** | Model Context Protocol server management (stdio + HTTP transport) |
| **LSP** | Language Server Protocol integration (completion, hover, diagnostics, references) |
| **Session Mgmt** | SQLite-persisted sessions with lock-based concurrency control |
| **Memory** | File-based memory system with frontmatter metadata |
| **Edit Log** | Append-only edit history with configurable retention |
| **Rate Limiting** | Sliding-window per-client rate limiter |
| **JWT Auth** | HS256 JWT access/refresh tokens (API mode) |
| **Password Auth** | Argon2 password hashing with pepper |
| **OAuth Loopback** | Localhost HTTP server for OAuth redirect capture |
| **Background Jobs** | Long-running shell jobs with cancellation and output collection |
| **Settings** | JSON-persisted settings with hot-reload |

---

## TUI Overlays

16 overlays accessible from the terminal UI:

| Overlay | Purpose |
|---------|---------|
| Chat Input | Main input bar with autocomplete |
| Bash Panel | Interactive shell panel |
| File Editor | Built-in file editor |
| Effort Selector | LLM reasoning effort selector |
| Help | Keybindings reference |
| Key Input | Custom key binding configuration |
| Learning | Lesson viewer |
| Loading | Generating spinner |
| MCP Manager | MCP server management |
| Model Selector | LLM model picker |
| Quit Confirm | Exit confirmation dialog |
| Rewind | Message/history rewind |
| Settings | Settings panel |
| Todo | Task/TODO list |
| Usage | Token usage statistics |
| Workflow | Hive-mind node progress |

---

## Data & Persistence

All data lives under the platform's data directory (`~/.local/share/zesdex/`):

```
~/.local/share/zesdex/
├── settings.json           # User settings (provider, model, keys)
├── app_config.json         # Provider definitions (endpoints, env vars)
├── sessions/               # Chat sessions (one subdirectory per session)
│   └── <uuid>/
│       ├── session.json    # Session metadata
│       ├── messages.jsonl  # Message log
│       └── .lock           # Session lock file
└── memories/               # Memory files with frontmatter metadata
    └── *.md
```

---

## Development

```bash
# Build all crates
cargo build

# Run all unit tests (8 tests across 11 crates)
cargo test

# Run clippy linting
cargo clippy --all-targets

# Run with verbose logging
RUST_LOG=debug cargo run
```

### Workspace Crates

| Crate | Path | Layer |
|-------|------|-------|
| `zesdex-domain` | `apps/domain/` | Pure domain entities & traits |
| `zesdex-application` | `apps/application/` | Use-case services |
| `zesdex-infrastructure` | `apps/infrastructure/` | All I/O & tool implementations |
| `zesdex-tui` | `apps/interfaces/tui/` | Ratatui terminal interface |
| `zesdex-api` | `apps/interfaces/api/` | Axum REST API |
| `zesdex-daemon` | `apps/interfaces/daemon/` | Unix socket daemon |
| `zesdex-ws` | `apps/interfaces/ws/` | WebSocket server |
| `zesdex-grpc` | `apps/interfaces/grpc/` | gRPC server |
| `zesdex-web` | `apps/interfaces/web/` | Web frontend |
| `zesdex-gateway` | `apps/gateway/` | CLI entry point & dispatcher |
| `zesdex-bootstrap` | `apps/bootstrap/` | Initial data seeder |

### Code Map

Detailed architecture documentation is in `docs/CODEMAPS/`:

| File | Covers |
|------|--------|
| `docs/CODEMAPS/architecture.md` | System layout, process modes, data flow |
| `docs/CODEMAPS/backend.md` | Provider, OAuth, IPC, workflow engine, MCP, LSP, review |
| `docs/CODEMAPS/frontend.md` | TUI render pipeline, 16 overlays, toasts, input handling |
| `docs/CODEMAPS/data.md` | Persistence, SQLite msglog, memory files, settings/config |
| `docs/CODEMAPS/dependencies.md` | All Rust crates and external services |

---

## License

See `CHANGELOG.md` for release history.