diff --git a/README.md b/README.md deleted file mode 100644 index 1d4b1ff..0000000 --- a/README.md +++ /dev/null @@ -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 - -# 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 ` | **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; -} -``` - -### 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) -│ └── / -│ ├── 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.