asepharyana
a974118b5a
- Deleted the `security` module and its associated files, including `daemon.rs` and `install.rs`. - Removed references to security features in various modules, including `mod.rs`, `mode/mod.rs`, and `input.rs`. - Updated the `MiscState` struct to eliminate security-related fields. - Adjusted the `apply_action` function to remove security action handling. - Increased the maximum limits for tool-only turns and agent steps in `actions/mod.rs`. - Modified the review prompt to exclude security checks. - Cleaned up the `git_operator` and `shell` tools to remove catastrophic guard checks. - Removed internet-related tools and their references from the tool module.
247 lines
9.8 KiB
Markdown
247 lines
9.8 KiB
Markdown
# 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 (28 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` |
|
|
|
|
### 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.
|
|
- **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
|
|
├── 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
|
|
│ ├── runtime/ # Action dispatch and event loop
|
|
│ │ ├── actions/ # Action enum and apply_action reducer
|
|
│ │ ├── stream/ # LLM streaming and tool execution
|
|
│ │ │ └── tools/ # Tool harness integration
|
|
│ │ ├── event_loop/ # Main event loop and shortsend
|
|
│ │ └── commands.rs # Slash command dispatch
|
|
│ ├── mode/ # UI modes and overlays (16 overlays)
|
|
│ ├── harness.rs # Tool harness for agent execution
|
|
│ ├── workflow/ # Workflow engine (script DSL, executor)
|
|
│ ├── mcp/ # MCP client manager
|
|
│ ├── subagent/ # Sub-agent spawn, context, events
|
|
│ ├── bgbash/ # Background bash job management
|
|
│ ├── review/ # Self-review quality system
|
|
├── controller/
|
|
│ ├── input.rs # Key event → Action mapping
|
|
│ └── command.rs # Slash command parser
|
|
├── dto/
|
|
│ ├── chat/ # Message, ToolCall, Role types
|
|
│ └── provider/ # AI provider request/response/usage types
|
|
├── 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)
|
|
│ ├── agent_def/ # Agent definitions (builtin, global, session)
|
|
│ └── session_lock.rs # Flock-based session locking
|
|
├── service/
|
|
│ ├── provider.rs # AI provider abstraction
|
|
│ └── oauth/ # OAuth PKCE flow with loopback server
|
|
├── tool/ # 28 tool implementations
|
|
│ ├── fs/ # read, write, edit, delete
|
|
│ ├── 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
|
|
│ ├── 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 (credentials, git)
|
|
├── 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
|
|
└── resources.rs # Embedded resources (help text, system 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+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.
|