Celeste Cli

Character artwork by いかわさ (ikawasa23)

👁️ Celeste CLI - Interactive AI Assistant

A premium, corruption-aesthetic command-line interface for CelesteAI

[](https://golang.org/) [](LICENSE) [](https://github.com/charmbracelet/bubbletea)

Built with Charm's Bubble Tea for flicker-free, modern terminal experiences

---

✨ What is Celeste CLI?

Celeste CLI is a full standalone agentic development tool with her own persona, featuring:

• 🎨 Premium TUI - Flicker-free rendering with corrupted-theme aesthetics
• 🔮 45 Built-in Tools - File I/O, shell, web search, code graph, code review, collections search, git, crypto, subagent orchestration, and more
• 📖 .grimoire Project Context - Persona-themed project config files with auto-discovery and auto-init
• 🧠 Code Graph + Semantic Search - MinHash + BM25 fused ranking with LSH band table for sub-linear queries, structural rerank; tree-sitter TypeScript parsing for accurate call-graph edges; embedded celeste-stopwords v1.0.0 noise filter
• 🔍 Graph-Based Code Review - Structural analysis detecting stubs, lazy redirects, placeholders, error swallowing, and hardcoded values
• 🔌 Direct Codegraph MCP Tools - celeste_index, celeste_code_search, celeste_code_review, celeste_code_graph, celeste_code_symbols served verbatim from the cached graph (no chat-LLM round-trip, no max_tokens ceiling, streaming progress notifications)
• 🔒 Permission System - Multi-layer allow/deny/ask rules with pattern matching
• 💾 Session Persistence - JSONL auto-save, resume, file checkpointing with stale detection and revert
• 🌐 Multi-Provider - Grok/xAI (default), OpenAI, Anthropic (native SDK), Gemini, Venice.ai, Vertex AI, OpenRouter, Sakana AI
• 💰 Cost Tracking - Per-model pricing with live session cost display
• 🪝 Hooks - Pre/post tool execution hooks defined in .grimoire
• 🧠 Extended Thinking - Leverage reasoning tokens (Claude, Gemini, Grok) with /effort control
• 🖼️ Image Input - Multimodal support for vision-capable models
• 🎭 Celeste Personality - Embedded AI personality with lore-accurate responses
• 🔗 Blockchain Tools - IPFS, Alchemy, wallet security monitoring

Three Runtime Modes

| Mode | Command | What it does | |------|---------|-------------| | Chat | celeste chat (default) | Interactive chat with auto-looping tool calls (50-turn safety cap). | | Agent | /agent (in TUI) or celeste agent --goal "..." | Fully autonomous multi-turn agent with planning, file I/O, checkpointing, and resume. For long-running tasks. | | Orchestrator | /orchestrate (in TUI) | Agent run with a second reviewer model that critiques and debates the output. For high-quality deliverables. |

> Chat vs Agent: Chat is interactive with tool auto-looping — you guide the conversation while Celeste > calls tools as needed. Agent is a separate autonomous runtime with its own turn loop, planning phase, > checkpoint store, and workspace awareness. The orchestrator adds a reviewer model on top of the agent.

---

🚀 Quick Start

Quick Install (Recommended)

If you have Go 1.26+ installed:

go install github.com/whykusanagi/celeste-cli/cmd/celeste@latest

The celeste binary will be installed to $GOPATH/bin (or ~/go/bin by default).

Requirements:

• Go 1.26.0 or higher
• $GOPATH/bin (or ~/go/bin) in your PATH

No Go toolchain? Download a pre-built, signed binary for your platform from the Releases page and verify it (see [Security & Verification](#-security--verification) below).

To add to PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Manual Installation

Alternatively, build from source:

# Clone the repository
git clone https://github.com/whykusanagi/celeste-cli.git
cd celeste-cli

# Build + install to ~/.local/bin (handles macOS code-signing for you)
make install

> macOS note: don't cp the binary over an existing ~/.local/bin/celeste — > on Apple Silicon that invalidates its ad-hoc code signature and the kernel will > SIGKILL it at launch (zsh: killed celeste). make install builds straight to > the destination and re-signs. If you install by hand, build directly to the > target and re-sign: > > ``bash > go build -o ~/.local/bin/celeste ./cmd/celeste > codesign --force --sign - ~/.local/bin/celeste # macOS only > ``

First Run

xAI/Grok (default — recommended):

celeste config --set-key YOUR_XAI_KEY
celeste chat

With Collections (RAG):

celeste config --set-key YOUR_XAI_KEY
celeste config --set-management-key YOUR_XAI_MANAGEMENT_KEY
celeste collections list          # see available collections
celeste collections enable    # enable for chat
celeste chat

OpenAI:

celeste config --init openai
celeste -config openai config --set-key YOUR_OPENAI_KEY
celeste -config openai chat

Sakana (Fugu):

celeste config --init sakana
celeste -config sakana config --set-url https://api.sakana.ai/v1 --set-key YOUR_SAKANA_KEY --set-model fugu
celeste -config sakana chat

Get a key from the Fugu install (curl -fsSL https://sakana.ai/fugu/install | bash) or your Sakana account. Use --set-model fugu-ultra for the heavier multi-agent variant.

Other providers: celeste config --init where name is: grok, openai, venice, elevenlabs, sakana

Project Setup

When you enter a project directory, Celeste auto-initializes:

cd your-project
celeste chat
# Creates .grimoire (project context), indexes code graph, loads memories

Or manually:

celeste init          # create .grimoire
celeste index         # build code graph
celeste index status  # check graph stats

---

🔒 Security & Verification

All Celeste CLI releases are cryptographically signed with GPG to ensure authenticity and integrity.

Quick Verification

Before using a downloaded binary, verify its authenticity:

# Download verification script
curl -O https://raw.githubusercontent.com/whykusanagi/celeste-cli/main/scripts/verify.sh
chmod +x verify.sh

# Verify your download
./verify.sh celeste-linux-amd64.tar.gz

Manual Verification

For manual verification or more details, see the complete [Verification Guide](VERIFY.md).

Release Signing:

• All commits are GPG-signed
• All releases include GPG signatures
• Checksums are signed with GPG
• Complete manifest with build metadata

PGP Key Information:

• Key ID: 875849AB1D541C55
• Fingerprint: 9404 90EF 09DA 3132 2BF7 FD83 8758 49AB 1D54 1C55
• Keybase: @whykusanagi
• GitHub: whykusanagi.gpg

Import Key — use the repository copy; it carries the signing subkey the releases are signed with:

# From this repository (recommended — complete key with signing subkey)
curl -O https://raw.githubusercontent.com/whykusanagi/celeste-cli/main/whykusanagi.asc
gpg --import whykusanagi.asc

# Cross-check the primary fingerprint against the key GitHub serves:
gpg --fingerprint 940490EF09DA31322BF7FD83875849AB1D541C55
#   → 9404 90EF 09DA 3132 2BF7  FD83 8758 49AB 1D54 1C55

For security issues, see our [Security Policy](SECURITY.md) or contact security@whykusanagi.xyz.

---

📚 Table of Contents

• [Installation](#-quick-start)
• [Security & Verification](#-security--verification)
• [Features](#-features)
• [Tool System (45 Tools)](#-tool-system-45-tools)
• [Claude Code Integration](#-claude-code-integration)
• [Comparison](#-how-celeste-compares)
• [LLM Provider Compatibility](#-llm-provider-compatibility)
• [Function Calling Flow](#-function-calling-flow-mermaid-diagram)
• [Configuration](#%EF%B8%8F-configuration)
• [Usage](#-usage)
• [Architecture](#%EF%B8%8F-architecture)
• [Documentation](#-documentation)
• [Contributing](#-contributing)

---

🎯 Features

Interactive TUI Mode

• Flicker-Free Rendering - Double-buffered Bubble Tea rendering (no screen tearing)
• Scrollable Chat - PgUp/PgDown navigation through conversation history
• Input History - Arrow keys to browse previous messages (like bash history)
• Skills Panel - Real-time skill execution status with demonic eye animation
• Corrupted Theme - Lip Gloss styling with pink/purple abyss aesthetic
• Real Streaming + Corruption Animation - Token-by-token streaming with corrupted glitch phrases at the typing cursor
• Markdown Rendering - glamour-powered markdown with corrupted theme (code blocks, tables, headers, bold)

Tool System (v1.10)

45 built-in tools powered by AI function calling:

• Dev Tools (bash, read/write/patch files, search, list files)
• Code Graph (semantic search with MinHash+BM25 fusion, code review, symbol analysis, tree-sitter TypeScript parsing)
• Direct Codegraph MCP Tools (celeste_index, celeste_code_search, celeste_code_review, celeste_code_graph, celeste_code_symbols — verbatim, no chat-LLM round-trip)
• Git (status, log)
• Web (search, fetch)
• Information Services (Weather, Currency, Twitch, YouTube)
• Utilities (Conversions, Encoding, Generators, QR codes)
• Productivity (Reminders, Notes, Todo tracking)
• Blockchain (IPFS, Alchemy, wallet security)
• Subagent Orchestration (spawn_agent, post_message)

[See complete tool list below](#-tool-system-44-tools)

Collections Support (xAI RAG)

• Upload Custom Documents - Create knowledge bases with your own documentation
• Semantic Search - Celeste automatically searches collections when answering questions
• Interactive TUI - Manage collections with /collections command in chat
• CLI Management - Create, upload, enable/disable collections from command line
• Multiple Collections - Organize by topic, enable only what's relevant

[See Collections Guide](docs/COLLECTIONS.md) for setup and usage.

Tool System (v1.7)

• MCP (Model Context Protocol) support for external tool servers
• Permission system with configurable allow/deny rules
• Streaming tool execution with concurrent dispatch
• Automatic context window management

Session Management

• Conversation Persistence - Auto-save and resume sessions seamlessly
• Message History - Full conversation logging with timestamps
• Session Listing - Browse and load previous sessions by ID
• Session Clearing - Bulk delete sessions when needed

Multi-Provider Support (8 Providers)

• ✅ Grok/xAI (grok-4.20-0309-non-reasoning) - DEFAULT - reliable tool calling, no reasoning-token burn, never routes to the cost-prohibitive grok-4.3 • Token tracking ✓
• ✅ OpenAI (gpt-4.1-mini, gpt-4.1) - Full function calling with streaming • Token tracking ✓
• ✅ Anthropic Claude (claude-sonnet-4-5) - Native SDK with prompt caching and extended thinking • Token tracking ✓
• ✅ Google Gemini AI (gemini-2.5-flash) - Simple API keys, free tier, full streaming • Token tracking ✓
• ⚠️ Google Vertex AI (gemini-2.5-flash) - Enterprise, requires GCP project + billing • Token tracking ✓
• ✅ Venice.ai (venice-uncensored) - NSFW mode, image generation/upscaling • Token tracking ✓
• ✅ OpenRouter (multi-provider) - Parallel function calling support • Token tracking ✓
• ✅ Sakana AI (fugu, fugu-ultra) - 1M context, OpenAI-compatible chat completions, deep reasoning • Token tracking ✓

Dynamic Model Selection - Auto-selects best tool-calling model per provider Capability Indicators - Visual feedback (✓ skills / ⚠️ no skills) in header

[See full compatibility matrix](#-llm-provider-compatibility)

Configuration

• JSON-based Config - Modern ~/.celeste/config.json format
• Named Configs - Multi-profile support (openai, grok, venice, etc.)
• Skills Config - Separate skills.json for skill-specific API keys
• Secrets Handling - Separate secrets.json for backward compatibility
• Persona Injection - Configurable Celeste personality prompt
• Environment Override - Env vars override file config

---

🔮 Tool System (45 Tools)

Celeste CLI uses OpenAI-compatible function calling to power its tools. You don't invoke tools directly — you chat naturally, and the AI decides when to call them.

Dev Tools (9 Tools)

| Tool | Description | |------|-------------| | bash | Execute shell commands in the workspace | | readfile | Read files with checkpointing | | writefile | Write files with snapshot backup | | patchfile | Apply targeted edits to files | | splicefile | Move a region between files by anchors/line-ranges (deterministic, no model-routed bytes) | | listfiles | List directory contents with glob patterns | | search | Search file contents with regex | | gitstatus | Show working tree status | | git_log | Show commit history |

Code Graph Tools (6 Tools)

| Tool | Description | |------|-------------| | codesearch | MinHash semantic search across all indexed symbols | | codereview | Graph-based code review (6 categories: stubs, lazy redirects, placeholders, TODOs, error swallowing, hardcoded values) | | codegraph | Query symbol relationships and call chains | | codesymbols | List symbols in a file or package | | codeimpact | Blast-radius analysis: which callers are affected by a changed symbol | | codesnapshot | Save and diff graph state to track what changed between sessions |

> v1.10 accuracy improvements: STUB detection now skips dunder methods (__init__, __lt__, …), @abstractmethod-decorated methods, and methods on Protocol/ABC/ABCMeta classes — eliminating the largest classes of false positives. Decorator @syntax calls and @property.setter assignments are now captured as call edges, producing more accurate impact/caller counts.

Subagent Orchestration Tools (2 Tools)

| Tool | Description | |------|-------------| | spawnagent | Spawn a subagent to handle a subtask; supports DAG dependencies, worktree isolation, and background execution | | postmessage | Post a message to another subagent's mailbox by element name for loosely-coupled coordination |

You never call these directly — you describe multi-step work in chat and Celeste decides when to delegate. The parameters below show what the model can specify:

spawn_agent parameters:

| Parameter | Type | Description | |-----------|------|-------------| | goal | string | (required) What the subagent should accomplish | | workspace | string | Working directory (defaults to current workspace) | | task_id | string | Unique ID for DAG dependency references | | depends_on | array of strings | Task IDs that must finish before this subagent starts | | max_turns | integer | Max agent turns (default 20; raise for complex tasks, lower for simple lookups) | | isolate_worktree | boolean | Run in its own git worktree so concurrent subagents can't conflict on the same files; merged back on success, removed afterward. Requires a git repo. Default false. | | background_after | integer | Seconds before auto-backgrounding a slow subagent so the parent resumes immediately. Result appears in /agents when it finishes. 0 = foreground/blocking (default). | | persona | object | Override personality sliders (flirt, warmth, register, lewdness, r18) or load a named preset |

post_message parameters:

| Parameter | Type | Description | |-----------|------|-------------| | to | string | (required) Recipient element name (fire, water, earth, light, dark, wind, …) | | message | string | (required) Message body delivered when the recipient agent next starts |

TUI commands:

/agents                   List all spawned subagents and their status (waiting/running/completed/failed)
/agents resume        Resume a failed subagent from it

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [whykusanagi](https://github.com/whykusanagi)
- **Source:** [whykusanagi/celeste-cli](https://github.com/whykusanagi/celeste-cli)
- **License:** MIT
- **Homepage:** https://github.com/whykusanagi/celeste-cli

Install and usage instructions live in the source repository linked above.