🌟 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.2

🚀 Features

• 🖥️ 3-Segment Layout: Real-time context header (tokens, RAM, latency, provider/model), scrollable history viewport with collapsible blocks, and dynamic multi-line composer.
• 🎯 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 (researcher, coder, tester, reviewer, custom personas) 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 and autonomous tool injection into TOOLS_SPEC.
• ❓ Interactive User Question Prompting: Agents can invoke ask_question with selectable options to clarify ambiguity during execution, awaiting user input before proceeding.
• ⚡ Mid-Run User Guidance Interruption: Send a message or press ESC / Ctrl+C while an agent is executing to immediately pause, incorporate guidance (e.g. "don't do that, do this instead"), and pivot smoothly.
• 🛡️ Fault-Tolerant Resilience: 5-stage connection retry backoff (increasing by +5s intervals: 5s, 10s, 15s, 20s, 25s) with automatic failover between LLM providers.
• ♾️ Unconstrained Autonomous Execution: Removed artificial tool round limits for complex, hundreds-step autonomous pipelines.
• 🎨 7 Curated Color Palettes: tokyo_night, dracula, catppuccin, monokai, nord, cyberpunk, and gruvbox.
• 📱 Mobile & Termux First: Smooth step-scroll animation for touch gestures, compact mini-banners for narrow viewports (<70 cols), and zero heavy C-extension dependencies.
• 🧠 Context Optimization: Automatic message history compaction when nearing token capacity thresholds.

📦 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.
• 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+C: Interrupt running generation / exit.
• 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.