Celeste For Claude

---

Give Claude Code access to Celeste CLI's graph-based code intelligence — structural code review, semantic search, dependency analysis, and project context management that goes beyond grep and pattern matching.

v1.9.0+: Skills now use Celeste's direct codegraph MCP tools (celeste_index, celeste_code_search, celeste_code_review, celeste_code_graph, celeste_code_symbols) instead of routing through the chat persona. Results come back verbatim and structured, with no LLM round-trip and no output truncation.

What You Get

Celeste brings capabilities Claude Code doesn't have natively:

Capability	What it does	How it works
Graph Code Review	Detect stubs, lazy redirects, error swallowing, placeholders, hardcoded values	Structural analysis via code graph — not grep
Semantic Code Search	Find functions by concept, not just name	MinHash + BM25 fusion with structural rerank
Dependency Analysis	Map package connectivity, find isolated code	Cross-file edge resolution (tree-sitter for TS)
Project Memory	Persist learned context across sessions	Per-project memory store
.grimoire Context	Auto-detected project config with staleness tracking	Git-stamped metadata

Prerequisites

Install Celeste CLI (v1.9.0+). Two options:

# Quick: installs to ~/go/bin (must be on your PATH)
go install github.com/whykusanagi/celeste-cli/cmd/celeste@latest

# Or from a checkout: installs to ~/.local/bin and code-signs (macOS-safe)
git clone https://github.com/whykusanagi/celeste-cli.git && cd celeste-cli && make install

Whichever you pick, the install directory must be on your PATH, and it must match the binary your MCP client launches. On macOS, don't cp over an existing ~/.local/bin/celeste — that breaks its code signature; use make install.

Verify:

celeste version
celeste index status   # in any project directory

You'll need an API key configured only if you use the persona tools (xAI/Grok by default). The direct codegraph tools (celeste_index, celeste_code_search, etc.) run locally and need no key.

celeste config --set-key YOUR_API_KEY   # only for persona tools

Installation

Option A — Install the plugin (recommended)

The plugin bundles the skills and wires the Celeste MCP server for Claude Code automatically (no manual config):

/plugin marketplace add whykusanagi/celeste-for-claude
/plugin install celeste-for-claude

This works in Claude Code because it inherits your shell PATH, so the bundled server entry (celeste serve) resolves on its own.

Option B — Manual MCP registration

Use this if you're not installing the plugin, or you're on Claude Desktop.

Claude Code (CLI — inherits PATH):

claude mcp add celeste --scope user -- celeste serve

Claude Desktop (GUI — does not inherit your shell PATH): Claude Desktop launches the server without your shell environment, so a bare celeste won't be found — it needs the binary's absolute path. Celeste installs itself: celeste mcp install self-locates the binary and merges an entry into ~/Library/Application Support/Claude/claude_desktop_config.json.

celeste mcp install                # requires celeste v1.12.1+
celeste mcp install --dry-run      # preview without writing
celeste mcp install --client all   # also wire Claude Code, Cursor, Celeste

It preserves any other MCP servers, backs the file up to .bak, refuses to write through a symlink, and is safe to re-run any time you reinstall or move the binary (it repairs the path). Then fully quit and reopen Claude Desktop (Cmd-Q) to load it. The resulting entry looks like:

{
  "mcpServers": {
    "celeste": { "command": "/Users/you/.local/bin/celeste", "args": ["serve"] }
  }
}

On celeste older than v1.12.1, use the bundled ./install.sh instead — same behavior, superseded by the built-in command:

git clone https://github.com/whykusanagi/celeste-for-claude.git
cd celeste-for-claude && ./install.sh   # --dry-run to preview

See INSTALL.md for per-client detail and troubleshooting.

Skills without the plugin

If you registered the MCP server manually and want the skills too, copy them into your skills directory:

mkdir -p ~/.claude/skills
cp -R celeste-for-claude/skills/* ~/.claude/skills/

Available Skills

celeste-review — Graph-Based Code Review

Runs Celeste's structural code review on the current project. Detects 6 categories of issues using the code graph (not grep):

• STUB — Functions with zero outgoing calls that aren't constructors/getters
• LAZY_REDIRECT — Handlers that say "run X command" instead of doing the work
• PLACEHOLDER — "Not implemented" functions with empty bodies
• TODO_FIXME — Unfinished work markers, scored by call graph impact
• EMPTY_HANDLER — Silently swallowed errors (_ = err)
• HARDCODED — Localhost URLs, IP addresses, credential values

Invoke: ask Claude to "run a Celeste code review on this project."

celeste-search — Semantic Code Search

Search the codebase by concept using MinHash similarity — finds functions related to a concept even if they don't contain the search term.

Invoke: ask Claude to "use Celeste to search for authentication token validation."

celeste-graph — Dependency Analysis

Analyze package-level dependencies and find connectivity patterns.

Invoke: ask Claude to "analyze this project's dependencies with Celeste."

celeste-context — Project Context Setup

Have Celeste index the project, create/update .grimoire, and save memories about the project structure.

Invoke: ask Claude to "set up Celeste project context here."

celeste-docs — Documentation Maintainer

Keep existing markdown docs from drifting. Patches section-by-section to fix stale versions, wrong counts, and dead references — without summarizing away code examples and technical depth.

Invoke: ask Claude to "use Celeste to update the docs in this repo."

celeste-content — Content Generator

Generate new prose in Celeste's voice — filling a stub, drafting a README intro, writing a commit message, or producing a social post. Returns styled text for you to place; does not write files itself.

Invoke: ask Claude to "draft this in Celeste's voice."

Docs vs Content: celeste-docs maintains existing files surgically. celeste-content generates new prose for blank spots. Use docs to prevent drift; use content to fill stubs.

How It Works

                    ┌──── Direct codegraph tools (v1.9.0+) ────┐
                    │                                          │
Claude Code ──MCP──▶│  celeste_index        (rebuild/update)   │
                    │  celeste_code_search   (semantic search)  │
                    │  celeste_code_review   (structural scan)  │
                    │  celeste_code_graph    (callers/callees)  │
                    │  celeste_code_symbols  (file/package list)│
                    │                                          │
                    │  → verbatim results, no LLM round-trip   │
                    └──────────────────────────────────────────┘

                    ┌──── Persona tools (file I/O, memories) ──┐
                    │                                          │
Claude Code ──MCP──▶│  celeste { prompt, mode: "chat" }        │──▶ chat LLM
                    │  celeste_content                          │
                    │  celeste_status                           │
                    │                                          │
                    │  → save_memory, write_file, patch_file   │
                    └──────────────────────────────────────────┘

The skills in this repo call the direct codegraph tools for code intelligence queries (review, search, graph, symbols, index) and fall back to the persona tool only when file I/O or memory persistence is needed. Celeste provides the graph intelligence; Claude does the verification and stays in control.

Direct tools return verbatim structured output with no max_tokens ceiling and no chat-LLM summarization. Progress notifications stream back during long operations (e.g., celeste_index rebuild) when your MCP client supports progressToken.

Why Not Just Use grep?

Celeste's code review uses structural graph analysis:

• A function named handlePayment with zero outgoing call edges? That's suspicious: the name implies action, the structure shows none.
• A function that calls db.Exec() but assigns the error to _? That's a swallowed error, caught by body analysis combined with edge counting.
• A TODO in a function called by 20 others scores higher than one in dead code (impact-aware prioritization).

grep finds text. Celeste understands structure.

Configuration

Celeste uses her own config (~/.celeste/config.json) for API keys and model settings. She runs independently of Claude Code's configuration.

To change Celeste's model:

celeste config --set-model grok-4-1-fast   # default
celeste config --set-model claude-sonnet-4-5

License

MIT — Same as Celeste CLI

---

Built by whykusanagi — Celeste is an agentic AI development tool with her own persona.