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

🚀 Features

• 🖥️ 3-Segment Layout: Real-time context header (tokens, RAM, latency, provider/model), scrollable history viewport with collapsible blocks, and dynamic multi-line composer.
• 🔄 Multi-Provider Failover: Native streaming integration with OpenAI, OpenRouter, Anthropic, DeepSeek, Groq, Ollama, LM Studio, and more. Automatically fails over to backup providers on rate limits (429) or server errors (5xx).
• 🛠️ Autonomous Agent Tools:
  • bash_run: Sandboxed execution with timeout and output capture.
  • read_file & write_file: Atomic file read/write with automatic backup generation.
  • edit_file: Smart fuzzy matching and targeted block replacement.
  • diff_files & /apply: Unified diff generator and staged hunk applicator.
  • web_search & web_fetch: DuckDuckGo query integration and readable text extraction.
  • bg_task: Background task runner with detached output streams.
  • tree_view: Directory visualizer with gitignore-awareness.
• 🎨 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.