agent-spotlight

🔍 Agent Spotlight

---

What Makes Agent Spotlight Special?

TL;DR: This isn't just another AI chatbot. It's a desktop agent that can actually interact with your files, run commands, and integrate with any tool you want—all through natural language.

The Problem: Every AI assistant lives in a browser tab, disconnected from your actual work.

The Solution: Agent Spotlight brings AI directly to your desktop with:

• Global hotkey access (Cmd+` from anywhere)
• Real tool integration via Model Context Protocol (MCP)
• Native desktop performance (built with Rust + Tauri)
• Beautiful, minimal UI that stays out of your way
• Infinite extensibility - add any tool, API, or data source

---

Features

Core Features

• Spotlight Interface: macOS Spotlight-inspired design with global hotkey access
• AI-Powered: Uses Google's Gemini 2.5 Flash for intelligent query processing
• Function Calling: AI automatically decides when and which tools to use
• Lightning Fast: Native performance with Rust backend
• Modern UI: Built with Next.js, React, and Tailwind CSS
• Cross-Platform: Works on Windows, macOS, and Linux

Advanced Features

• MCP Integration: Add any tool that supports Model Context Protocol
• Smart Persistence: Conversation history and settings saved locally
• Privacy First: Your API keys and data stay on your machine
• Visual Feedback: Real-time status updates as tools execute
• Hot Reload: Instant updates during development

---

Extensibility: The Game Changer

This is where Agent Spotlight becomes incredibly powerful. Unlike other AI tools, you can teach it to use any tool or data source through the Model Context Protocol.

What You Can Add:

• File System: Read, write, search files and directories
• APIs: Connect to REST APIs, databases, cloud services
• Data Sources: Parse CSV, JSON, XML, or any structured data
• System Tools: Run shell commands, manage processes
• Integrations: Git, Docker, Kubernetes, AWS, you name it

Pre-configured Tools:

• Filesystem: Browse directories, read files, search content
• (More coming soon)

---

Tech Stack

Agent Spotlight combines the best of modern technologies:

Component	Technology	Why?
Frontend	Next.js + React	Modern, fast, developer-friendly
Styling	Tailwind CSS	Utility-first, highly customizable
Desktop	Tauri	Lightweight, secure, cross-platform
Backend	Rust	Performance, safety, reliability
AI Model	Google Gemini	Advanced reasoning, function calling
Extensibility	Model Context Protocol	Industry standard for AI tool integration

---

Quick Start

Prerequisites

• Node.js (v18 or later)
• Rust
• Google AI API Key (free tier available)

Installation

# 1. Clone the repository
git clone https://github.com/harshpreet931/agent-spotlight.git
cd agent-spotlight-app

# 2. Install dependencies
npm install

# 3. Set up your API key
echo 'GOOGLE_API_KEY="your-api-key-here"' > .env.local

# 4. Launch the app
npm run tauri dev

That's it! Hit Cmd+`` (or Ctrl+`` on Windows/Linux) to open Agent Spotlight from anywhere.

---

Real-World Examples

File Management

You: "Show me all TypeScript files in the src directory"
Agent: *Uses filesystem tools* → Lists all .ts and .tsx files

Development Workflow

You: "Find all TODO comments in my project"
Agent: *Searches files* → Shows all TODO items with file locations

Data Analysis

You: "What's the size of my largest files?"
Agent: *Analyzes filesystem* → Reports file sizes sorted by size

System Information

You: "What's taking up space in my Downloads folder?"
Agent: *Scans directory* → Shows files by size and type

---

How It Works

Agent Spotlight uses a sophisticated agentic architecture:

graph LR
    A[User Query] --> B[Agent Spotlight UI]
    B --> C[Gemini AI Model]
    C --> D{Need Tools?}
    D -->|Yes| E[MCP Tools]
    D -->|No| F[Direct Response]
    E --> G[Tool Results]
    G --> C
    C --> H[Final Answer]
    H --> B

1. You ask in natural language
2. Gemini analyzes your request and available tools
3. Tools execute automatically when needed
4. Results synthesize into a helpful response
5. You get answers, not just chat

---

Adding Your Own Tools

The real magic happens when you add your own tools. Here's how:

1. Find the Config File

# macOS
~/Library/Application Support/com.agentspotlight.spotlight/mcp_servers.json

# Windows
%APPDATA%/com.agentspotlight.spotlight/mcp_servers.json

# Linux
~/.config/com.agentspotlight.spotlight/mcp_servers.json

2. Add Your Tool Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "git": {
      "command": "python",
      "args": ["/path/to/your/git-mcp-server.py"]
    },
    "database": {
      "command": "node",
      "args": ["/path/to/database-server.js"]
    }
  }
}

3. Restart Agent Spotlight

Your new tools will be automatically discovered and available to the AI!

Popular MCP Servers

• @modelcontextprotocol/server-filesystem: File operations
• @modelcontextprotocol/server-git: Git repository management
• @modelcontextprotocol/server-sqlite: SQLite database access
• Custom servers: Build your own!

---

Roadmap

Coming Soon

• Global Hotkey Improvements: Better cross-platform support
• Tool Marketplace: Discover and install MCP servers easily
• Conversation Persistence: Keep chat history across sessions
• Result Previews: Images, tables, rich content display
• Custom Themes: Personalize your spotlight experience

Future Vision

• Voice Commands: Speak to your agent
• Workflow Automation: Chain multiple tools together
• Team Sharing: Share your custom tool configurations
• Plugin Ecosystem: Visual tool builder
• Cloud Sync: Sync settings across devices

---

Contributing

We'd love your help making Agent Spotlight even better!

Ways to Contribute:

• Report bugs or suggest features
• Improve documentation
• Build MCP servers for popular tools
• Code contributions (see our contributing guide)
• Star the repo to show support!

Development Setup:

git clone https://github.com/harshpreet931/agent-spotlight.git
cd agent-spotlight-app
npm install
npm run tauri dev

---

License

MIT License - see LICENSE for details.

---

Show Your Support

If Agent Spotlight helps you get stuff done faster, consider:

• Starring this repo
• Sharing on Twitter with #AgentSpotlight
• Writing a blog post about your use case
• Contributing a new MCP server

---