a
This commit is contained in:
asepharyana
@@ -1,250 +0,0 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user