Celebrimbot

An autonomous AI coding agent embedded directly into your JetBrains IDE.

Celebrimbot is an IntelliJ Platform plugin that brings a full multi-agent AI system into your IDE. It can read your project files, write and modify code, execute terminal commands, search the web, inspect git history, and hold natural conversations — all from a single chat panel anchored to your IDE window.

Unlike simple autocomplete tools, Celebrimbot operates as an agentic loop: it routes requests intelligently, executes tasks locally when possible, escalates to cloud planning only when needed, and retries failures automatically — without leaving your editor.

How It Works

Celebrimbot uses a six-layer architecture — each layer named after a character from Tolkien's legendarium:

User Message
     |
     v
+-------------+
|   Gandalf   |  <- Router: Local Qwen + conversation history
+-------------+
     |                    |                          |
   CHAT              EASY_TASK                 COMPLEX_TASK
     |                    |                          |
  Galadriel          Aragorn (Local)           Elrond (Local)
  (chat reply)       multi-task planner        enriches context
                          |                          |
               Samwise / Frodo /            Celebrimbor (Cloud)
               Legolas & Gimli              master planner
               execute tasks                     |
                          |              Samwise / Frodo /
                    Treebeard (Cloud)     Legolas & Gimli
                    Ent Reviewer          execute tasks
                    reflection loop            |
                          |              Treebeard (Cloud)
                       Bilbo (Local)     Ent Reviewer
                       session summary   reflection loop
                                                     |
                                              Bilbo (Local)
                                              session summary

The Fellowship

Router Logic (Gandalf)

Gandalf receives the full conversation history. If the same request has been asked before without success, it automatically escalates to COMPLEX_TASK.

AI Provider Priority

Each character's provider is configurable per-project in Settings. The table below shows the default priority chain.

All four providers — Local, Alibaba Qwen Cloud, Google Gemini, Amazon Q Developer — are selectable per-character. Amazon Q Developer authenticates via the SSO token written by the Amazon Q JetBrains plugin (no separate API key needed). The local model runs entirely on your machine via java-llama.cpp — no internet required for most operations.

Features

• Conversational AI — natural chat with full project context awareness
• Autonomous code editing — reads files, applies changes directly in the editor
• File management — create, edit, delete files via natural language
• Terminal execution — runs shell commands from within the IDE
• Web search — searches DuckDuckGo and fetches pages, no API key required
• Project scanning — list files, grep across the codebase, find by name, file stats
• Git integration — status, log, diff, blame, branch — all from chat
• Multi-agent loop — Gandalf routes → Aragorn/Elrond plan → Celebrimbor refines → Samwise executes → Bilbo summarizes
• Smart three-way routing — CHAT / EASY_TASK / COMPLEX_TASK with history awareness (Gandalf)
• Offline-first — embedded Qwen 2.5 Coder 1.5B runs locally with no API calls
• Multi-provider fallback — Local Qwen → Alibaba Cloud (Qwen Plus) → Google Gemini → Claude Sonnet 4.6 (via Amazon Q Developer)
• Secure credential storage — API keys stored via IntelliJ PasswordSafe, never in plain text
• Per-project settings — each project can use a different provider and model
• Standalone CLI — celebrimbot forge / scan / serve / mcp-stdio / undo for use outside the IDE (via server:shadowJar)
• HTTP bridge — embedded Ktor server for remote invocation from other tools
• Dynamic Tool Registry — all capabilities self-describe as JSON schemas; planners receive auto-generated tool lists, adding a new tool requires zero prompt editing
• Shadow Log (Auto-Undo) — every file is backed up before being written or deleted; celebrimbot undo restores the last session from .celebrimbot/shadow_log/
• Council's Review (Validation Loop) — after every write_code, the build command runs automatically; up to 3 self-correction cycles with error feedback before escalating
• Elrond's Palantír (BM25 Index) — lightweight local semantic index; COMPLEX_TASK planning retrieves the top-8 relevant files instead of sending the full project skeleton
• MCP Bridge (Beacons of Gondor) — MCP-compliant JSON-RPC 2.0 server over HTTP (POST /mcp) and Stdio (celebrimbot mcp-stdio) for Claude Desktop and other MCP hosts
• Treebeard (Ent Reviewer) — critic agent between Workers and Bilbo; reviews completed work against the original request; triggers up to 2 re-planning cycles if incomplete; never hasty, never satisfied with placeholder code
• Ollama-Compatible API — drop-in replacement for Ollama; works with Open WebUI, ProjectCompass, llama-index, and any Ollama/OpenAI-compatible client
• OpenAI-Compatible Endpoint — POST /v1/chat/completions for llama-index, LangChain, and other OpenAI SDK clients

Available Actions

Ollama-Compatible API

Celebrimbot exposes a full Ollama-compatible API, making it a drop-in replacement for Ollama. Point any Ollama client to http://localhost:16180 and it works.

Supported Endpoints

Use with Open WebUI

# Start Celebrimbot + Open WebUI
docker compose --profile ui up

# Open WebUI at http://localhost:3000
# It auto-discovers models via /api/tags

Use with ProjectCompass

In your .env file:

OLLAMA_HOST=http://localhost:16180

ProjectCompass will use Celebrimbot for chat completion via llama-index.

Note: For RAG embeddings, you still need Ollama with nomic-embed-text. Celebrimbot does not yet support embedding models.

Use with any OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="http://localhost:16180/v1", api_key="not-needed")
response = client.chat.completions.create(
    model="qwen2.5-coder:1.5b",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Available Models

Download models via API or CLI:

# Via CLI
java -jar server/build/libs/celebrimbot.jar download-model -m qwen-7b

# Via API (like Ollama)
curl -d '{"model":"qwen2.5-coder:7b"}' http://localhost:16180/api/pull

Requirements

• IntelliJ IDEA 2025.2+ (or any JetBrains IDE based on platform 252+)
• Java 21+
• ~1.2 GB disk space for the local model (downloaded automatically on first use)
• Optional: Alibaba Cloud API key for cloud-powered planning
• Optional: Google Gemini API key as secondary fallback
• Optional: Amazon Q Developer (authenticated via the Amazon Q JetBrains plugin — no separate API key)

Installation

From JetBrains Marketplace:

Settings → Plugins → Marketplace → search Celebrimbot → Install

Manually:

Download the latest release and install via:

Settings → Plugins → ⚙️ → Install plugin from disk...

Configuration

Open Settings → Tools → Celebrimbot

The local embedded model (qwen2.5-coder-1.5b-instruct-q4_k_m.gguf) is downloaded automatically to your IDE system directory on first inference. If a partial/corrupted download is detected, it is deleted and re-downloaded automatically.

Usage

Open the Celebrimbot tool window (right side panel) and start chatting.

Examples:

You: hello
Celebrimbot: [🧝 Galadriel] Hello! How can I help you today?

You: create a python file with a function that computes levenshtein similarity
[⚔️ Aragorn: preparing the task...]
[🌿 Samwise: executing task...]
Celebrimbot: ✅ Code written to src/levenshtein.py
Celebrimbot: ✅ All tasks completed!

You: delete src/levenshtein.py
[⚔️ Aragorn: preparing the task...]
[🌿 Samwise: executing task...]
Celebrimbot: ✅ Deleted src/levenshtein.py
Celebrimbot: ✅ All tasks completed!

You: search online for kotlin coroutines timeout example
[⚔️ Aragorn: preparing the task...]
[🌿 Samwise: executing task...]
Celebrimbot: Summary: ...
Celebrimbot: ✅ All tasks completed!

You: refactor the service to use the new interfaces
[🧙 Elrond: preparing the brief...]
[💎 Celebrimbor: forging the plan...]
[🌿 Samwise: executing 3 task(s)...]
Celebrimbot: ✅ All tasks completed!

The header shows 🖥️ N ☁️ N — local inference count vs cloud planner calls — so you always know how many API calls were made.

Tech Stack

Development

The project is split into three Gradle modules:

# Plugin development
./gradlew plugin:runIde          # Run plugin in sandbox IDE
./gradlew plugin:buildPlugin     # Build distributable ZIP
./gradlew plugin:verifyPlugin    # Verify compatibility
./gradlew plugin:test            # Run plugin tests

# Server / CLI
./gradlew server:shadowJar       # Build standalone CLI fat JAR
./gradlew server:test            # Run server tests

# Core library
./gradlew core:test              # Run core unit tests
./gradlew core:compileKotlin     # Compile core module

CLI usage (after server:shadowJar):

java -jar server/build/libs/celebrimbot.jar forge "create a Python file with a fibonacci function"
java -jar server/build/libs/celebrimbot.jar scan
java -jar server/build/libs/celebrimbot.jar serve --port 16180
java -jar server/build/libs/celebrimbot.jar mcp-stdio
java -jar server/build/libs/celebrimbot.jar undo
java -jar server/build/libs/celebrimbot.jar download-model --list
java -jar server/build/libs/celebrimbot.jar download-model -m qwen-7b

Docker (team server):

./gradlew server:shadowJar       # Build first
docker compose up                # Starts Celebrimbot server only
docker compose --profile ui up   # Starts Celebrimbot + Open WebUI (http://localhost:3000)
docker compose --profile with-ollama up  # Starts with Ollama sidecar
curl localhost:16180/health      # Health check
curl localhost:16180/api/tags    # List available models (Ollama-compatible)

Memory Management

The local GGUF model uses lazy loading with automatic unload:

• The model is NOT loaded at IDE startup (zero extra RAM on boot)
• On first user message, the model loads (~2s delay)
• After 60 seconds of inactivity, the model is automatically unloaded from RAM
• The timeout is configurable in Settings → Tools → Celebrimbot

This means PyCharm stays lightweight when you're not actively using Celebrimbot.

Project Structure

celebrimbot/
├── core/                              # Zero IntelliJ deps — pure Kotlin + llama + Gson
│   └── src/main/kotlin/.../
│       ├── engine/
│       │   ├── LazyModelManager       # Lazy-load + auto-unload timer for GGUF models
│       │   └── ChatTemplateFormatter  # Chat template formatting (ChatML, Llama3, Phi3)
│       ├── io/
│       │   ├── FileOperator           # Interface for file operations
│       │   ├── HeadlessFileOperator    # java.nio implementation (standalone)
│       │   ├── ShadowLogOperator      # Interface for shadow log backup/undo
│       │   ├── HeadlessShadowLogOperator # java.nio shadow log implementation
│       │   ├── ShadowedFileOperator   # Decorator: intercepts writes/deletes for backup
│       │   ├── TerminalOperator       # Interface for terminal execution
│       │   ├── HeadlessTerminalOperator # ProcessBuilder implementation
│       │   ├── LlmEngine             # Interface for LLM inference
│       │   ├── StandaloneLlmEngine    # llama.cpp with LazyModelManager delegation
│       │   ├── WebSearchOperator      # Interface for web search + fetch_page
│       │   ├── DuckDuckGoSearchOperator # DuckDuckGo implementation
│       │   ├── ProjectScanOperator    # Interface for project scanning
│       │   ├── HeadlessProjectScanOperator # java.nio implementation
│       │   ├── GitOperator           # Interface for git operations
│       │   └── HeadlessGitOperator    # ProcessBuilder git implementation
│       ├── index/
│       │   └── PalantirIndex          # BM25 semantic index (build, query, save, load)
│       ├── mcp/
│       │   ├── McpRouter              # JSON-RPC 2.0 dispatcher (MCP method handlers)
│       │   └── McpTransport           # Compact JSON-RPC response/error formatting
│       ├── model/
│       │   ├── CelebrimbotPlan        # CelebrimbotTask data class
│       │   ├── CelebrimbotTool        # Tool interface, ToolParam, ToolResult, ToolCategory
│       │   └── TreebeardReviewResult  # Treebeard's verdict
│       ├── parser/
│       │   └── PlanParser             # JSON plan parsing from LLM output
│       ├── registry/
│       │   ├── ToolRegistry           # Central tool vault with toJsonSchema()
│       │   └── tools/Tools            # 15 tool implementations wrapping all operators
│       └── settings/
│           ├── LocalAiModel           # GGUF model catalogue (enum)
│           └── AgentConfig            # Per-character provider configuration
│
├── plugin/                            # IntelliJ Platform plugin
│   └── src/main/kotlin/.../
│       ├── services/
│       │   ├── CelebrimbotAgentOrchestrator  # Multi-agent loop
│       │   ├── CelebrimbotLlmService  # AI provider abstraction
│       │   ├── CelebrimbotEmbeddedEngine # IDE model download + inference
│       │   ├── LocalModelManager      # IDE wrapper for LazyModelManager
│       │   ├── ValidationService      # Build system detection + Council's Review
│       │   └── TreebeardReviewService # Ent Reviewer: reflection loop
│       ├── settings/
│       │   ├── CelebrimbotSettingsState # Persistent per-project configuration
│       │   ├── CelebrimbotSettingsConfigurable # Settings UI panel
│       │   └── CelebrimbotPasswordSafe # Secure API key storage
│       ├── toolWindow/
│       │   └── CelebrimbotToolWindowFactory # Chat UI panel
│       ├── startup/
│       │   └── CelebrimbotStartupActivity # Model download (no eager load) + Palantír refresh
│       └── io/
│           ├── IdeFileOperator        # PSI/VFS implementation (IDE mode)
│           └── IdeTerminalOperator    # IDE terminal implementation
│
├── server/                            # Standalone CLI + HTTP server (Docker-ready)
│   └── src/main/kotlin/.../
│       ├── cli/
│       │   └── CelebrimbotCLI        # Clikt CLI (forge / scan / serve / mcp-stdio / undo / download-model)
│       ├── http/
│       │   └── CelebrimbotServer     # Ktor HTTP server (all routes wired here)
│       └── ollama/
│           ├── ModelRouter            # Maps Ollama-style model names to GGUF files
│           └── OllamaRoutes           # Full Ollama-compatible API (/api/chat, /api/generate, etc.)
│
├── core/src/main/resources/prompts/   # Shared LLM system prompts (all characters)
├── plugin/src/main/resources/         # META-INF/plugin.xml, icons, messages
├── Dockerfile                         # Server container image
└── docker-compose.yml                 # Celebrimbot + optional Open WebUI + optional Ollama

Provider Benchmark Results

The following results come from an automated LLM-as-a-Judge evaluation (src/test/testData/eval/run_eval.py) run across 12 provider configurations and 8 test cases, using Claude Sonnet 4.6 (via Amazon Q Developer) as the judge. Full results are in EVAL_REPORT.md.

How the Eval Works

The evaluation framework is a standalone Python script that runs the full Celebrimbot agent pipeline headlessly — no IDE required. Each test case defines a natural-language input, the expected routing decision (CHAT / EASY_TASK / COMPLEX_TASK), and a set of judge criteria.

Test cases (src/test/testData/eval/eval_suite.json) cover:

• Routing accuracy (does Gandalf classify greetings, single-file tasks, and multi-file tasks correctly?)
• Planner quality (does Elrond produce a valid JSON brief with all required fields?)
• Worker output quality (does Frodo write syntactically valid Python with the requested classes/methods?)
• Reviewer behaviour (does Treebeard flag incomplete work when a README is too short?)
• Summary quality (does Bilbo address the user as "Mellow" in Tolkienian style?)

How it runs:

1. For each configuration, the script spins up a HeadlessPipeline in a temporary directory
2. The pipeline calls the configured LLM backend (Amazon Q Developer via SSO token, or Ollama for local models) for each character
3. After execution, the judge (Claude Sonnet 4.6 via Amazon Q Developer) receives the full agent trace, internal logs, and written file contents, then scores the run 0–10 and flags specific issues
4. Results are aggregated into EVAL_REPORT.md and per-configuration JSON files in build/eval/

To run it yourself:

# Requires: Amazon Q Developer SSO login + Ollama for local models
brew install ollama && ollama serve &
ollama pull qwen2.5-coder:1.5b qwen2.5-coder:7b llama3.1:8b deepseek-coder:6.7b phi3.5
python3 src/test/testData/eval/run_eval.py

Final Ranking

Key Findings

The optimal configuration is: Claude Sonnet 4.6 (via Amazon Q Developer) for planners + a 7B+ local model for workers.

The top three configurations all share the same pattern: Claude Sonnet 4.6 (via Amazon Q Developer) handles Gandalf (routing), Elrond (context enrichment), Celebrimbor (master planning), and Treebeard (review), while a local model runs Aragorn, Frodo, Legolas & Gimli, Galadriel, and Bilbo. This hybrid approach outperforms using Claude Sonnet 4.6 for everything (9.0 vs 8.6) while minimising cloud API calls.

Local 7B models are competitive workers. Qwen 2.5 Coder 7B and Llama 3.1 8B running fully locally (no cloud) both score 7.8/10 — higher than the "Claude Sonnet 4.6 core only" configuration (8.4/10 but with more cloud calls). For teams that need full offline operation, Qwen 7B or Llama 8B are viable.

DeepSeek Coder 6.7B underperforms its size. Despite being comparable in size to Qwen 7B, DeepSeek scores only 4.9/10 all-local and 6.1/10 as a worker. It frequently refuses tasks with "I can't assist with that" and produces malformed JSON, making it unreliable for agentic pipelines.

Qwen 2.5 Coder 1.5B is too small for reliable routing and planning. At 4.9/10 all-local, it misroutes simple greetings as COMPLEX_TASK and produces incomplete JSON plans. It is only viable as a Frodo/worker when paired with a cloud planner.

Phi-3.5 Mini (3.8B) punches above its weight as a worker. Paired with Claude Sonnet 4.6 planners it reaches 9.0/10 — matching Qwen 7B at a fraction of the RAM footprint (~2.5 GB vs ~4.5 GB). Best choice for resource-constrained environments.

Recommended Configurations

License

This project is based on the IntelliJ Platform Plugin Template.