Skip to content

README_EN.md

Latest commit

 

History

History
240 lines (166 loc) · 7.77 KB

README_EN.md

File metadata and controls

240 lines (166 loc) · 7.77 KB
Raw

Tiny-agent

A Completely Frontend-Driven AI Agent Project, No Server Required

English | 简体中文

License React TypeScript WebLLM

🌐 Official Website | 📖 Documentation | 🚀 Quick Start

📺 Demo Video

Watch Demo Video

Complete demonstration video showcasing tiny-agent executing complex tasks

✨ Features

🌐 Fully Browser-Based

  • Zero Server Dependency: All AI inference runs entirely in the browser using WebLLM and WebGPU
  • No API Key Required: No third-party APIs needed, completely free to use - save hundreds or thousands of dollars in API costs
  • Complete Privacy: All data stays on your local device, never uploaded

💰 Cost Savings: Traditional cloud-based AI APIs can cost $0.002-0.03 per 1K tokens. With WebLLM running locally in your browser, you pay $0 - no matter how much you use. This means unlimited AI interactions without worrying about API bills.

🏗️ Advanced Agent Architecture

  • Planning Agent Pattern: Complete planning-execution-rethinking loop
  • State Machine Controller: IDLE → PLANNING → EXECUTING → RETHINKING → DONE
  • UI and Agent Layer Separation: Clear architectural boundaries, easy to maintain and extend
  • Dual LLM System: Separate LLM instances for planning and tool execution

💾 Data Persistence

  • IndexedDB Storage: Conversation history, file attachments, and tool results all persisted locally
  • Session Management: Complete multi-turn conversation support
  • File Attachment System: Support for attaching generated files in responses

🔌 MCP Protocol Support

  • Model Context Protocol: Full support for MCP protocol
  • MCP Bridge Extension: Chrome extension to solve CORS limitations
  • Extensible Tool System: Easily add new tools and capabilities

⚡ Performance Optimization

  • WebGPU Acceleration: Hardware acceleration for near-native performance
  • Streaming Responses: Real-time streaming output with instant feedback
  • React 19 Compiler: Automatic optimization for faster rendering
  • Web Workers: LLM inference runs in separate threads, non-blocking UI

🛠️ Built-in Tools

  • Code Expert: Code generation and software engineering tasks
  • JavaScript Executor: Execute JavaScript in a sandboxed environment
  • Writing Expert: Writing and content creation assistance

To Be Done

  • Context memory

🏛️ Project Architecture

tiny-agent/
├── app/
│   └── web-app/              # React 19 + Vite frontend application
│       ├── src/
│       │   ├── components/   # UI components
│       │   ├── stores/       # MobX state management
│       │   ├── pages/        # Page components
│       │   └── stream/       # Streaming processing
│       └── public/           # Static assets
├── packages/
│   ├── agent-core/           # Agent core logic
│   │   ├── src/
│   │   │   ├── core/         # State machine controller
│   │   │   ├── service/      # Service layer
│   │   │   ├── storage/      # IndexedDB storage
│   │   │   └── tools/        # Built-in tools
│   ├── web-llm/              # Custom @mlc-ai/web-llm fork
│   ├── mcp-bridge-extension/ # Chrome extension (MCP CORS solution)
│   └── utils/                # Shared utilities
└── docs/                     # Project documentation

Core Architecture Highlights

  1. Monorepo Design: Multi-package project managed with pnpm workspaces
  2. State Machine Pattern: Agent execution follows strict state transitions
  3. Streaming Architecture: End-to-end streaming from LLM to UI
  4. Type Safety: TypeScript strict mode with complete type definitions
  5. Modular Tool System: Easy to extend through clear interfaces

🚀 Tech Stack

Frontend

  • React 19 - Latest React version with React Compiler support
  • TypeScript 5.9 - Type-safe development experience
  • Vite 7 - Next-generation frontend build tool
  • Tailwind CSS - Utility-first CSS framework
  • shadcn/ui - High-quality UI components
  • Radix UI - Accessible UI primitives
  • MobX - Simple, scalable state management

AI/LLM

  • @mlc-ai/web-llm - Browser-based LLM inference (custom fork) - eliminates expensive API costs
  • WebGPU - Hardware-accelerated graphics and compute API
  • Web Workers - Multi-threaded LLM inference

Infrastructure

  • pnpm - Fast, disk space efficient package manager
  • Turbo - High-performance build system
  • IndexedDB - Browser-side database
  • Chrome Extension (Manifest V3) - MCP CORS solution

📦 Installation and Usage

Prerequisites

  • Node.js >= 18
  • pnpm >= 8
  • Modern browser with WebGPU support (Chrome/Edge 113+)

Install Dependencies

# Clone the repository
git clone https://github.com/RichDavidMu/tiny-agent.git
cd tiny-agent

# Install dependencies
pnpm install

Development Mode

# Start development server
pnpm dev

# Or start only web-app
cd app/web-app
pnpm dev

Build for Production

# Build all packages
pnpm build

# Or build only web-app
cd app/web-app
pnpm build

Install MCP Bridge Extension (Optional)

If you need to use MCP features:

  1. Build the extension:
cd packages/mcp-bridge-extension
pnpm build
  1. Load the extension in Chrome:
    • Open chrome://extensions/
    • Enable "Developer mode"
    • Click "Load unpacked"
    • Select the packages/mcp-bridge-extension/dist directory

🎯 Usage Guide

  1. First Use: On first launch, the LLM model will automatically download and cache in your browser (approximately 2-4GB)
  2. Start Chatting: Enter your questions or tasks in the chat interface
  3. Agent Execution: The agent will automatically plan, execute tasks, and provide real-time feedback
  4. View Results: After task completion, you can view generated files and detailed execution process

🔧 Configuration

Debug Logging

Enable debug logging in general settings:

  • Web App Logs: Frontend application debug information
  • Agent Core Logs: Agent core logic debug information

Logs are controlled via the localStorage.debug field (format: web-app*,agent-core*)

Theme

Supports light and dark themes, switchable in general settings.

📝 Roadmap

  • Context Management: Smarter context window management and compression
  • More Tools: Expand built-in tool set
  • Model Selection: Support switching between multiple LLM models
  • Export Features: Export conversation history and generated files

🤝 Contributing

Contributions are welcome! Feel free to submit Issues or Pull Requests.

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

  • WebLLM - Browser-based LLM inference engine that eliminates API costs and enables truly free AI applications
  • shadcn/ui - Beautiful UI components
  • Radix UI - Accessible UI primitives

📮 Contact

Made with ❤️ by the tiny-agent team