<img src="./archon-ui-main/public/archon-main-graphic.png" alt="Archon Main Graphic" width="853" height="422"> <a href="https://trendshift.io/repositories/13964" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13964" alt="coleam00%2FArchon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> Power up your AI coding assistants with your own custom knowledge base and task management as an MCP server <a href="#quick-start">Quick Start</a> • <a href="#upgrading">Upgrading</a> • <a href="#whats-included">What's Included</a> • <a href="#architecture">Architecture</a> • <a href="#troubleshooting">Troubleshooting</a>

🎯 What is Archon?

Archon is currently in beta! Expect things to not work 100%, and please feel free to share any feedback and contribute with fixes/new features! Thank you to everyone for all the excitement we have for Archon already, as well as the bug reports, PRs, and discussions. It's a lot for our small team to get through but we're committed to addressing everything and making Archon into the best tool it possibly can be!

Archon is the command center for AI coding assistants. For you, it's a sleek interface to manage knowledge, context, and tasks for your projects. For the AI coding assistant(s), it's a Model Context Protocol (MCP) server to collaborate on and leverage the same knowledge, context, and tasks. Connect Claude Code, Kiro, Cursor, Windsurf, etc. to give your AI agents access to:

Your documentation (crawled websites, uploaded PDFs/docs)
Smart search capabilities with advanced RAG strategies
Task management integrated with your knowledge base
Real-time updates as you add new content and collaborate with your coding assistant on tasks
Much more coming soon to build Archon into an integrated environment for all context engineering

This new vision for Archon replaces the old one (the agenteer). Archon used to be the AI agent that builds other agents, and now you can use Archon to do that and more.

It doesn't matter what you're building or if it's a new/existing codebase - Archon's knowledge and task management capabilities will improve the output of any AI driven coding.

🔗 Important Links

GitHub Discussions - Join the conversation and share ideas about Archon
Contributing Guide - How to get involved and contribute to Archon
Introduction Video - Getting started guide and vision for Archon
Archon Kanban Board - Where maintainers are managing issues/features
Dynamous AI Mastery - The birthplace of Archon - come join a vibrant community of other early AI adopters all helping each other transform their careers and businesses!

Quick Start

<a href="https://youtu.be/DMXyDpnzNpY"> <img src="https://img.youtube.com/vi/DMXyDpnzNpY/maxresdefault.jpg" alt="Archon Setup Tutorial" width="640" /> </a> 📺 Click to watch the setup tutorial on YouTube <a href="./archon-example-workflow">-> Example AI coding workflow in the video <-</a>

Prerequisites

Docker Desktop
Node.js 18+ (for hybrid development mode)
Supabase account (free tier or local Supabase both work)
OpenAI API key (Gemini and Ollama are supported too!)
(OPTIONAL) Make (see Installing Make below)

Setup Instructions

Clone Repository:
```
git clone -b stable https://github.com/coleam00/archon.git
```
```
cd archon
```
Note: The stable branch is recommended for using Archon. If you want to contribute or try the latest features, use the main branch with git clone https://github.com/coleam00/archon.git
Environment Configuration:
```
cp .env.example .env
# Edit .env and add your Supabase credentials:
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SERVICE_KEY=your-service-key-here
```
IMPORTANT NOTES:
- For cloud Supabase: They recently introduced a new type of service role key but use the legacy one (the longer one).
- For local Supabase: Set SUPABASE_URL to http://host.docker.internal:8000 (unless you have an IP address set up). To get SUPABASE_SERVICE_KEY run supabase status -o env.
Database Setup: In your Supabase project SQL Editor, copy, paste, and execute the contents of migration/complete_setup.sql
Start Services (choose one):

Full Docker Mode (Recommended for Normal Archon Usage)
```
docker compose up --build -d
```
This starts all core microservices in Docker:
- Server: Core API and business logic (Port: 8181)
- MCP Server: Protocol interface for AI clients (Port: 8051)
- UI: Web interface (Port: 3737)
Ports are configurable in your .env as well!
Configure API Keys:
- Open http://localhost:3737
- You'll automatically be brought through an onboarding flow to set your API key (OpenAI is default)

⚡ Quick Test

Once everything is running:

Test Web Crawling: Go to http://localhost:3737 → Knowledge Base → "Crawl Website" → Enter a doc URL (such as https://ai.pydantic.dev/llms.txt)
Test Document Upload: Knowledge Base → Upload a PDF
Test Projects: Projects → Create a new project and add tasks
Integrate with your AI coding assistant: MCP Dashboard → Copy connection config for your AI coding assistant

Installing Make

<details> <summary>🛠️ Make installation (OPTIONAL - For Dev Workflows)</summary>

Windows

# Option 1: Using Chocolatey
choco install make

# Option 2: Using Scoop
scoop install make

# Option 3: Using WSL2
wsl --install
# Then in WSL: sudo apt-get install make

macOS

# Make comes pre-installed on macOS
# If needed: brew install make

Linux

# Debian/Ubuntu
sudo apt-get install make

# RHEL/CentOS/Fedora
sudo yum install make

</details> <details> <summary>🚀 Quick Command Reference for Make</summary>

| Command | Description | | ----------------- | ------------------------------------------------------- | | make dev | Start hybrid dev (backend in Docker, frontend local) ⭐ | | make dev-docker | Everything in Docker | | make stop | Stop all services | | make test | Run all tests | | make lint | Run linters | | make install | Install dependencies | | make check | Check environment setup | | make clean | Remove containers and volumes (with confirmation) |

</details>

🔄 Database Reset (Start Fresh if Needed)

If you need to completely reset your database and start fresh:

<details> <summary>⚠️ Reset Database - This will delete ALL data for Archon!</summary>

Run Reset Script: In your Supabase SQL Editor, run the contents of migration/RESET_DB.sql

⚠️ WARNING: This will delete all Archon specific tables and data! Nothing else will be touched in your DB though.
Rebuild Database: After reset, run migration/complete_setup.sql to create all the tables again.
Restart Services:
```
docker compose --profile full up -d
```
Reconfigure:
- Select your LLM/embedding provider and set the API key again
- Re-upload any documents or re-crawl websites

The reset script safely removes all tables, functions, triggers, and policies with proper dependency handling.

</details>

📚 Documentation

Core Services

| Service | Container Name | Default URL | Purpose | | -------------------------- | -------------------------- | --------------------- | ------------------------------------------ | | Web Interface | archon-ui | http://localhost:3737 | Main dashboard and controls | | API Service | archon-server | http://localhost:8181 | Web crawling, document processing | | MCP Server | archon-mcp | http://localhost:8051 | Model Context Protocol interface | | Agents Service | archon-agents | http://localhost:8052 | AI/ML operations, reranking | | Agent Work Orders (optional) | archon-agent-work-orders | http://localhost:8053 | Workflow execution with Claude Code CLI |

Upgrading

To upgrade Archon to the latest version:

Pull latest changes:
```
git pull
```
Rebuild and restart containers:
```
docker compose up -d --build
```
This rebuilds containers with the latest code and restarts all services.
Check for database migrations:
- Open the Archon settings in your browser: http://localhost:3737/settings
- Navigate to the Database Migrations section
- If there are pending migrations, the UI will display them with clear instructions
- Click on each migration to view and copy the SQL
- Run the SQL scripts in your Supabase SQL editor in the order shown

What's Included

🧠 Knowledge Management

Smart Web Crawling: Automatically detects a

Archon

Install / Use

README