🌟 Highlights

xdh is a lightweight, high-performance terminal agent harness and Text User Interface (TUI) built for autonomous code generation, system exploration, and agentic workflows. Designed with first-class support for Android Termux as well as standard desktop operating systems.

  ██╗  ██╗██████╗ ██╗  ██╗
  ╚██╗██╔╝██╔══██╗██║  ██║
   ╚███╔╝ ██║  ██║███████║
   ██╔██╗ ██║  ██║██╔══██║
  ██╔╝ ██╗██████╔╝██║  ██║   xdharness v1.0.9

🚀 Features

• 🖥️ 3-Segment Layout & Responsive Drawer: Real-time context header (tokens, RAM, latency, provider/model), scrollable history viewport with collapsible blocks, sidecar drawer panel (F2 / Ctrl+B), and dynamic multi-line composer.
• 🔒 Fortified Security & AST Plugin Scanner: Pre-execution AST security validation for plugins blocking dangerous system calls, strict path traversal guards on session IDs, and zero-trust SSRF protection in fetch_url blocking private, link-local, and loopback IPs.
• 🐚 Persistent Shell State: Working directory persists across autonomous bash command executions (cd transitions tracked in harness.current_cwd) and all file tool paths resolve against it.
• 🛡️ Universal Mutation Safety Guards: Comprehensive protection against unauthorized destructive modifications to critical system paths (/etc, /boot, /system, .git, .ssh, .env).
• 🔍 Semantic BM25 / TF-IDF Search: Score-ranked semantic and keyword relevance search for /index build and /index query.
• 🧠 True Context Compaction & Summarization: LLM-driven structured bullet summarization of pruned turns preserving goal progress, file states, and user intent.
• ⚡ Headless & Pipe Mode: Full CLI non-interactive operation (xdh -p "prompt", --pipe, cat file | xdh -p "..." > out) without launching the full TUI.
• 🛡️ Configurable Permission Modes: --safe (strict confirmation on state changes), --auto (default guard against destructive commands), and --yolo (unconstrained speed).
• 🔌 Model Context Protocol (MCP): Native stdio JSON-RPC 2.0 MCP client integration. Configure servers in ~/.xdharness/mcp.json or /mcp add, with automatic dynamic tool discovery.
• 📑 AST Code Structure Outline: Fast structural inspections via AST / multi-language pattern parser (code_outline and /outline <file>).
• 💾 Rollback Checkpoints: Instant snapshots of entire workspaces before refactors (manage_checkpoint and /checkpoint create|restore|list).
• 🚫 .xdhignore & .gitignore Filters: Full workspace scanning exclusion support across search, tree, and index tools.
• ⏰ Autonomous Task Scheduling: Schedule recurring autonomous agent triggers via /schedule <interval_sec> <task>.
• 🎯 Reusable Skills System: Built-in create_skill & call_skill engine. Define, discover, and run skills via /skill list, /skill run <name>, or autonomous agent calls.
• 🤖 Multi-Agent Orchestration: Built-in create_agent & spawn_agents. Launch multiple specialized subagents concurrently in parallel threads to solve tasks cooperatively.
• 🔌 Dynamic Plugin Management: Add, install from git repositories, delete, and manage community or personal plugins via /plugin with automated AST safety verification.
• ❓ Interactive User Question Prompting: Agents can invoke ask_question with selectable options to clarify ambiguity during execution.
• ⚡ Mid-Run User Guidance Interruption: Send a message or press ESC / Ctrl+C while an agent is executing to immediately pause, incorporate guidance, and pivot smoothly.
• 🛡️ Fault-Tolerant Resilience: 5-stage connection retry backoff with automatic provider failover.
• ♾️ Unconstrained Autonomous Execution: Continuous multi-step reasoning without artificial iteration bounds.
• 🎨 Curated Color Palettes: tokyo_night, dracula, catppuccin, monokai, nord, cyberpunk, gruvbox, and solarized.
• 📱 Mobile & Termux First: Smooth step-scroll animation for touch gestures, compact mini-banners for narrow viewports (<70 cols), and zero heavy C-extension dependencies.

📦 Installation

From Source (Git)

git clone https://github.com/PwnedBytes0x1/xdh.git
cd xdh
pip install -r requirements.txt
pip install -e .

Direct Execution

python3 -m xdh --version

Termux Quick Setup

pkg update && pkg install python git -y
git clone https://github.com/PwnedBytes0x1/xdh.git
cd xdh
pip install -r requirements.txt
ln -s $(pwd)/xdh.py $PREFIX/bin/xdh
chmod +x $PREFIX/bin/xdh
xdh

⚡ Quick Start

1. Launch xdh:

   xdh
   

2. Configure Your Provider & Key: Type /settings inside the interface or edit ~/.xdharness/config.json. You can switch providers dynamically:

   xdh ❯ /provider openrouter
   xdh ❯ /model anthropic/claude-3.5-sonnet
   

3. Interact: Type plain language prompts to instruct the agent to inspect files, execute tests, refactor code, or run background builds.

⌨️ Slash Commands

⌨️ Keybindings

• Tab: Auto-complete slash command / accept ghost suggestion.
• Right Arrow: Accept ghost suggestion at line end.
• Up / Down: Navigate history or smooth-scroll conversation viewport.
• F2 / Ctrl+B: Toggle sidecar drawer pane (swarm stats, MCPs, checkpoints, tasks).
• ESC / Ctrl+C: Interrupt running generation / halt active task.
• Ctrl+T: Cycle color themes dynamically.
• Ctrl+P: Cycle configured AI providers.
• Ctrl+O: Toggle block collapse (compact vs expanded summary).
• Ctrl+L: Clear current viewport.
• Ctrl+J: Insert newline in composer without submitting.
• Ctrl+Q: Save session and quit.

📚 Documentation & Wiki

Detailed guides and specifications are organized in docs/wiki/:

• 🏠 Home & Overview: Product overview and architecture.
• 🚀 Getting Started & Installation: Step-by-step setup across Termux, Linux, macOS, and Windows.
• ⚙️ Configuration & Providers: API keys, model parameters, custom endpoints, and auto-failover.
• 🛠️ Tools & Workflows: Deep dive into diff generation, sandbox execution, web search, and tasks.
• 🎨 Theming & UI Customization: Theme reference and customizing styles.
• 🔌 Extensibility & Architecture: Harness internals, compaction, streaming protocols, and lifecycle.

🏗️ Architecture

flowchart TD
    User([User Terminal / Touch]) --> UI[XDHApp TUI Container]
    UI --> Layout[3-Segment Layout: Header, Viewport, Composer]
    UI --> Engine[XDHarness Core Engine]
    Engine --> ProviderRouter[Provider Router & Failover]
    ProviderRouter --> LLM[Streaming API / Ollama / OpenAI / OpenRouter]
    Engine --> ToolManager[Autonomous Tool Execution Engine]
    ToolManager --> Filesystem[(Filesystem & Atomic Backups)]
    ToolManager --> Shell[Subprocess Shell & BG Tasks]
    ToolManager --> Web[DuckDuckGo / Web Fetcher]

🤝 Contributing & Community

Contributions are welcome! Please review our community guidelines before getting started:

• 📜 Code of Conduct
• 💡 Contributing Guide
• 🔒 Security Policy

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.