ICECODE is a self-hosted AI agent platform I built by unifying three open-source projects (Hermes, OpenCode, ClawX) into one cohesive system. It runs entirely on your machine — no data leaves your network.
What it does
- Multi-Agent Swarm — pipeline and parallel orchestration: agents collaborate, pass context, and vote on answers
- Local RAG — FAISS + sentence-transformers, 100% offline — index any file, search semantically
- 26-Page Web UI — dashboard, chat, kanban, goals, swarm, knowledge, MCP, benchmark, and more
- Cost Optimizer — semantic cache (skip duplicate API calls), context compressor, smart model router
- 174 REST API routes with auto-docs (FastAPI)
- 34 platform gateways — WhatsApp, Telegram, Discord, Slack, Email, WeChat, Feishu, and 27 more
- 14 LLM providers — Anthropic, OpenAI, Ollama, Gemini, Mistral, Bedrock, Azure, OpenRouter...
- 90+ agent tools — file, web, browser, terminal, vision, kanban, MCP, code execution
- Self-learning skills — agents learn new skills at runtime, stored across sessions
- Reinforcement learning environment for agent improvement
- WebSocket chat — bidirectional with cancel support
- Token tracking + cost — per-session usage across all providers
Quick start
[1m
╔══════════════════════════════════════════════════════╗
║ ICECODE Super-Agent Network — Installer ║
║ v2.0.0 ║
╚══════════════════════════════════════════════════════╝
[0m
[0;33m→[0m Checking Python version...
[0;32m✓[0m Python 3.12 found
[0;32m✓[0m Virtual environment already exists
[0;33m→[0m Installing Python dependencies...
Starting ICECODE server on http://localhost:13210...
[32m23:36:33[0m | [1mINFO [0m | React UI served at /desktop/
INFO: Started server process [423207]
INFO: Waiting for application startup.
[32m23:36:33[0m | [1mINFO [0m | ============================================================
[32m23:36:33[0m | [1mINFO [0m | ICECODE Super-Agent Network v2.0.0 starting...
[32m23:36:33[0m | [1mINFO [0m | Port: 13210
[32m23:36:33[0m | [1mINFO [0m | DB: ~/.icecode/data/icecode.db
[32m23:36:33[0m | [1mINFO [0m | Home: /home/claudiu/.icecode
[32m23:36:33[0m | [1mINFO [0m | ============================================================
[32m23:36:33[0m | [1mINFO [0m | [✓] Database initialized at ~/.icecode/data/icecode.db
[32m23:36:33[0m | [1mINFO [0m | [✓] Self-learning system ready
[32m23:36:33[0m | [1mINFO [0m | [✓] Cron scheduler ready
[32m23:36:33[0m | [1mINFO [0m | [✓] Goals system (Ralph Loop) ready
[32m23:36:33[0m | [1mINFO [0m | [✓] Knowledge auto-index task started
[32m23:36:33[0m | [1mINFO [0m | All ICECODE systems online.
INFO: Application startup complete.
ERROR: [Errno 98] error while attempting to bind on address ('0.0.0.0', 13210): address already in use
INFO: Waiting for application shutdown.
[32m23:36:33[0m | [1mINFO [0m | ICECODE shutting down...
INFO: Application shutdown complete.
Architecture
Cost Optimizer (new in v2)
The cost optimizer has three components that work together automatically:
Semantic Cache — uses sentence-transformer embeddings + cosine similarity (≥0.92 threshold). If you ask a semantically similar question to a previous one, it returns the cached answer instantly — zero API tokens consumed.
Context Compressor — when conversation history exceeds 3000 tokens, older messages are summarized instead of sent verbatim. Keeps the last 6 messages intact.
Smart Model Router — analyzes prompt complexity (score 1-10) and routes to the cheapest capable model. Simple questions go to cheap models, complex reasoning goes to powerful ones.
Multi-Agent Swarm
Two orchestration modes:
Pipeline: agents run sequentially, each building on the previous output.
Parallel: all agents receive the same input simultaneously, results are merged.
Built-in templates: Research & Write, Code Review, Brainstorm, Security Audit.
Local RAG
No API keys needed. No data leaves your machine.
- Supports , , , , , , ,
- Chunk strategy: sliding window (512 tokens, 50 overlap)
- Embeddings: (90MB, runs locally)
- Vector store: FAISS IndexFlatL2
- Persistence:
Index a directory:
{"detail":[{"type":"json_invalid","loc":["body",0],"msg":"JSON decode error","input":{},"ctx":{"error":"Expecting value"}}]}
Tech stack
Backend — Python 3.12 · FastAPI · Uvicorn · SQLite · Pydantic v2 · FAISS · sentence-transformers · Loguru
Frontend — Single HTML file, no build step · Pure JS ES2022 · CSS variables · Server-Sent Events + WebSocket
TypeScript — pnpm workspaces · turbo · CLI with Ink TUI · 14 LLM provider protocols · MCP client
Desktop — Electron 33
Infrastructure — Docker · GitHub Actions CI · pytest (108 tests) · ruff
Links
- GitHub: https://github.com/iceslim409/icecode
- Demo GIF in README shows all major pages
- MIT-style non-commercial license (ICECODE-NC-1.0)
If you try it, I'd love to hear what you think. Issues and PRs welcome.