iloveAgents

Table of Contents

• Repository Highlights
• Feature Comparison
• What is iloveAgents?
• Why iloveAgents?
• Available Agents
• Agent Categories
• Supported Providers
• Battle Mode

• AI Workflow Builder (New)

• What you can do

• How sequential execution works
• Navigation
• Quick Start
• Getting Started
• Prerequisites
• Run Locally
• Troubleshooting
• Deploy Your Own
• How It Works
• Project Structure Overview
• Contributing
• Add a New Agent in 3 Steps
• Other Ways to Help
• Tech Stack
• Frequently Asked Questions
• Community
• License

Repository Highlights

• Open-source and community-driven — built and run entirely by contributors
• Supports multiple AI providers — OpenAI, Anthropic, and Google Gemini
• Battle Mode — compare model responses side by side
• Workflow Builder — chain multiple agents into a single automated run
• Browser-based — run AI agents directly in your browser
• Extensible architecture — add new agents easily
• Contributor-friendly — active community, easy to get started

Feature Comparison

A quick side-by-side look at the platform's core features:

What is iloveAgents?

iloveAgents is a clean, open source web platform where you can run AI agents directly in your browser.

No sign-up. No backend. No data collection. Just paste your API key and go.

Each agent is a focused tool that does one thing really well — summarize meeting notes, review code, generate SQL, write cold emails, and a lot more. The whole platform is config-driven, which means adding a new agent is as simple as adding one JavaScript object to a single file. No deep React knowledge needed.

Why iloveAgents?

• Your API key never leaves your browser. It goes directly to OpenAI, Anthropic, or Google. No middleman, no storage, no tracking.
• Zero setup. No .env files, no backend, no database. Clone and run in under a minute.
• Works with all major providers. OpenAI, Anthropic, and Google Gemini — switch between them at runtime.
• Built for contributors. Adding a new agent takes about 5 minutes and you don't need to know much React at all.

Available Agents

The complete list of agents has been moved to AGENTS.md for better organization and scalability.

Agent Categories

The repository contains AI agents for a wide variety of real-world use cases. The table below highlights the major categories available, helping new users quickly discover the project's capabilities.

Note: The repository currently contains 130+ AI agents spanning Engineering, Education, Marketing, Healthcare, Web3, Cybersecurity, and many other domains. For the complete list of agents and detailed descriptions, see AGENTS.md.

Supported Providers

Provider	Logo	Models	Get Your Key
OpenAI		GPT-4o, GPT-4o-mini	platform.openai.com
Anthropic		Claude Opus, Claude Sonnet	console.anthropic.com
Google Gemini		Gemini 2.5 Flash	aistudio.google.com

You can switch providers on any agent at runtime from the dropdown. No restart needed.

Battle Mode

Pit three AI providers against each other head-to-head.

1. Pick any agent from the full registry
2. Enter your input once — same prompt goes to all three
3. GPT-4o vs Claude Sonnet vs Gemini Flash generate outputs simultaneously
4. You pick the winner

Battle Mode has its own dark, dramatic UI with color-coded provider columns (gold for OpenAI, purple for Anthropic, blue for Gemini). Each provider loads independently — if one fails, the other two still work. Access it from the "Enter Battle Mode" button on the homepage or navigate directly to /battle.

🔗 AI Workflow Builder (New)

Chain multiple agents together and automate your entire process in one run.

Workflows let you connect agents in sequence — the output of each agent automatically becomes the input for the next. Build once, run with any input.

What you can do

• Build a workflow — pick up to 5 agents, arrange them in order, give the workflow a title
• Run it in one click — paste your input once, every step runs automatically in sequence
• Watch it execute — each step shows its own live status: waiting → running → done / failed
• Chain any agents — research → summarize → write LinkedIn post → done
• Community library — browse and run workflows shared by other users
• Real-time counters — usage counts update live as others run the same workflows
• Share workflows — one-click URL copy on any workflow detail page

How sequential execution works

Your Input
    │
    ▼
┌─────────────┐
│  Agent  1   │  e.g. Research Agent
└──────┬──────┘
       │ output
    ▼
┌─────────────┐
│  Agent  2   │  e.g. PDF Summarizer
└──────┬──────┘
       │ output
    ▼
┌─────────────┐
│  Agent  3   │  e.g. LinkedIn Post Writer
└─────────────┘
       │
    Final Output

If any step fails, the workflow stops at that step and shows you exactly what went wrong — with a Retry button. On success, you can copy all outputs at once.

Navigation

Quick Start

Get the project running quickly with the following commands:

git clone https://github.com/AditthyaSS/iloveAgents.git
cd iloveAgents
npm install
npm run dev

For complete setup instructions, environment variables, and troubleshooting, see the Getting Started section below.

Getting Started

Prerequisites

• Node.js v18+
• npm or yarn

Run Locally

# Clone the repository
git clone https://github.com/AditthyaSS/iloveAgents.git
cd iloveAgents

# Install dependencies
npm install

# Start the dev server
npm run dev

Open http://localhost:5173 in your browser. No API provider keys are required in a .env file because they are entered at runtime and never stored anywhere.

However, local development requires a .env.local file for Supabase features like Workflows.

Create a .env.local file in the root directory:

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Note: AI provider API keys are still entered at runtime and are never stored anywhere.

Troubleshooting

Missing or Invalid VITE_SUPABASE_URL

If you encounter connection errors, verify that the VITE_SUPABASE_URL in your .env.local file matches your Supabase project URL.

Missing or Invalid VITE_SUPABASE_ANON_KEY

Make sure the VITE_SUPABASE_ANON_KEY is copied correctly from your Supabase project's API settings.

Supabase Connection Failures

• Verify that your Supabase project is active.
• Confirm that both environment variables are present and correct.
• Ensure there are no extra spaces or quotation marks in .env.local.

Environment Variables Not Loading

If you recently created or updated .env.local, restart the development server:

Stop the development server and start it again:

npm run dev

Still Having Problems?

Before opening an issue, verify that:

• .env.local is in the project root.
• Variable names start with VITE_.
• The values are copied correctly from your Supabase dashboard.

Deploy Your Own

1. Fork this repository
2. Import to Vercel or any static host
3. Deploy — zero configuration needed

The included vercel.json handles SPA routing automatically.

How It Works

src/
├── agents/
│   ├── definitions/          # Each agent in its own file (auto-collected)
│   │   ├── pdf-summarizer.js
│   │   ├── code-reviewer.js
│   │   └── ... more agent definitions
│   ├── categories.js         # CATEGORIES constant
│   └── registry.js           # Auto-collects all definitions via import.meta.glob
├── components/
│   ├── AgentRunner.jsx       # Generic agent execution UI
│   ├── AgentCard.jsx         # Agent card for the homepage grid
│   ├── ApiKeyBar.jsx         # Provider and API key input
│   ├── OutputRenderer.jsx    # Renders markdown/text/JSON output
│   ├── ScorecardOutput.jsx   # Visual scorecard for JSON output
│   ├── BattleNavbar.jsx      # Battle Mode navigation bar
│   ├── Navbar.jsx            # Top navigation
│   ├── Sidebar.jsx           # Agent sidebar
│   └── ...
├── hooks/
│   └── useWorkflows.js       # Workflow data operations (fetch, save, realtime)
├── lib/
│   ├── llmAdapter.js         # Unified API adapter for all providers
│   ├── supabase.js           # Realtime data client
│   └── useApiKey.js          # API key state management
├── pages/
│   ├── HomePage.jsx          # Landing page with agent grid
│   ├── AgentPage.jsx         # Individual agent page
│   ├── WorkflowLibrary.jsx   # 🆕 Public workflow library with live counters
│   ├── WorkflowBuilder.jsx   # 🆕 Drag-and-drop agent chain builder
│   ├── WorkflowDetail.jsx    # 🆕 Single workflow view with realtime stats
│   ├── WorkflowRunner.jsx    # 🆕 Sequential agent execution engine
│   ├── BattleModeLanding.jsx # Battle Mode entry page
│   ├── BattleModeSetup.jsx   # Battle configuration
│   ├── BattleModeArena.jsx   # Three-column battle arena
│   └── BattleModeWinner.jsx  # Winner announcement
└── main.jsx

1. Registry — Each agent is its own file in src/agents/definitions/. The registry auto-collects them via import.meta.glob — just drop a file in and it appears.
2. LLM Adapter — A single runAgent() function in llmAdapter.js handles all three providers through one unified interface.
3. Agent Runner — AgentRunner.jsx builds the input form from the config, constructs the prompt, and renders the response.
4. Battle Mode — BattleModeArena.jsx fires the same prompt to GPT-4o, Claude Sonnet, and Gemini Flash simultaneously and lets you pick the winner.
5. Workflow Builder — WorkflowRunner.jsx chains agents sequentially using the same runAgent() adapter — output of step N becomes input of step N+1, with per-step status cards and real-time usage counters.
6. No backend — Every API call goes directly from your browser to the provider. Nothing passes through our servers because there are no servers.

Project Structure Overview

Contributing

iloveAgents is built by the community. Every contribution matters — whether it is a new agent, a bug fix, a UI improvement, or just fixing a typo.

Add a New Agent in 3 Steps

1. Create a new file in src/agents/definitions/ named your-agent-id.js:

export default {
  id: 'your-agent-id',
  name: 'Your Agent Name',
  description: 'One-line description.',
  category: 'Category',
  icon: 'IconName',               // from lucide.dev/icons
  provider: 'any',                // 'openai' | 'anthropic' | 'gemini' | 'any'
  defaultProvider: 'openai',
  model: 'gpt-4o',
  inputs: [
    {
      id: 'field_id',
      label: 'Field Label',
      type: 'textarea',           // text | textarea | code | select | multiselect
      placeholder: 'Hint text...',
      required: true,
    },
  ],
  systemPrompt: `Your system prompt here.`,
  outputType: 'markdown',         // markdown | text | json
}

The registry auto-collects it — no need to edit registry.js.

2. Run npm run dev and test your agent with a real API key.

3. Open a PR. That is it!

See CONTRIBUTING.md for the full guide.

Other Ways to Help

• 🐛 Fix a bug
• 🎨 Improve the UI or UX
• ♿ Improve accessibility
• 📝 Improve the docs
• 🧪 Add tests

Tech Stack

❓ Frequently Asked Questions

Do I need a backend to run the project?

No. Most features run entirely in the browser without a backend. However, Workflow-related features require Supabase, which is configured using a .env.local file.

Where can I obtain API keys for OpenAI, Anthropic, or Google Gemini?

You can create API keys from the official provider dashboards. Enter the keys directly in the application at runtime—they are never stored by the project.

Why isn't my .env.local file being detected?

Make sure .env.local is placed in the project root, uses the correct VITE_ variable names, and restart the development server after making changes.

Is Supabase required for all features?

No. Supabase is only required for Workflow-related functionality. Basic agent execution works without it.

What is the difference between Battle Mode and Workflow Builder?

Battle Mode compares responses from multiple AI providers using the same prompt, while Workflow Builder lets you chain multiple AI agents together into a sequential workflow.

How do I add a new AI agent?

Create a new agent definition inside src/agents/definitions/, test it locally with npm run dev, and submit a pull request following the contribution guidelines.

Which Node.js version is recommended?

Use Node.js v18 or later, as listed in the project prerequisites.

Where can I find the contribution guidelines?

See the CONTRIBUTING.md file for coding standards, pull request instructions, and contribution workflow.

Community

• Support — stuck on something? Drop a comment on your issue and I will reply within 24 hours
• Hall of Fame — every person who has contributed to iloveAgents
• Maintainers — who runs this project

👥 Contributors

Thanks to all contributors ❤️

License

Licensed under the MIT License — use it, fork it, build on it.