🕵️ Research Agent TUI

An autonomous AI research agent equipped with a beautiful, responsive, and native Terminal User Interface (TUI) powered by React and Ink. It uses the Vercel AI SDK to stream real-time reasoning and dynamically fetch and scrape the web for deep research tasks.

(Note: Replace with your actual screenshot)

✨ Features

• Modern React-based Terminal UI: Built with Ink, delivering a sleek Claude Code / Codex-style chat experience directly in your terminal.
• Native Scrolling: Messages flow naturally in the terminal buffer, preserving your history without "swallowing" text or breaking standard terminal scroll.
• Agentic Web Search: Uses Tavily as the primary AI search engine for ultra-fast, structured data retrieval.
• Rate-Limited Fallback: If no API key is provided, the agent gracefully falls back to a custom, rate-limited DuckDuckGo scraper.
• Streaming & Parallel Tool Execution: Watch the AI think, execute multiple web searches simultaneously, and stream answers in real-time.
• Vercel AI SDK: Leverages the industry standard AI SDK for robust tool handling and LLM interactions.

🚀 Quick Start

1. Requirements

• Node.js >= 18
• An OpenAI-compatible API key (e.g., DeepSeek, OpenAI, or Vultr AI)
• (Recommended) Tavily API Key for stable, unblocked web searches.

2. Installation

Clone the repository and install dependencies:

git clone https://github.com/yourusername/research-agent-tui.git
cd research-agent-tui
npm install

3. Environment Setup

Create a .env file in the root directory (you can copy .env.example):

cp .env.example .env

Open .env and configure your API keys:

# Highly Recommended for stable searches:
TAVILY_API_KEY=tvly-your-tavily-key

(Note: If you are using a custom OpenAI-compatible endpoint like Vultr, ensure src/services/vultr.ts is pointed to your provider).

4. Run the Agent

Start the agent in development mode:

npm run dev

Type your research query and watch the agent orchestrate web searches, read pages, and synthesize the information right in your terminal!

🧠 Architecture

• src/ui/App.tsx: The core React/Ink application. Handles layout, user input, and the Vercel AI SDK stream loop.
• src/tools/web-search.ts: The search executor. Automatically routes between Tavily (if configured) or DuckDuckGo.
• src/tools/scraper.ts: Extracts clean, readable text from target URLs using Cheerio.
• src/services/vultr.ts: Configures the OpenAI provider instance for the LLM.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a Pull Request if you have ideas for new tools, better UI components, or additional search integrations.

📄 License

This project is licensed under the MIT License.