# Celeste Cli

> Agentic terminal AI assistant with a Bubble Tea TUI, code-graph review, semantic search, multi-provider LLMs, and MCP tools.

- **Type:** MCP server
- **Install:** `agentstack add mcp-whykusanagi-celeste-cli`
- **Verified:** Pending review
- **Seller:** [whykusanagi](https://agentstack.voostack.com/s/whykusanagi)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [whykusanagi](https://github.com/whykusanagi)
- **Source:** https://github.com/whykusanagi/celeste-cli
- **Website:** https://github.com/whykusanagi/celeste-cli

## Install

```sh
agentstack add mcp-whykusanagi-celeste-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Character artwork by [いかわさ (ikawasa23)](https://x.com/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](https://github.com/charmbracelet/bubbletea) 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:

```bash
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](https://github.com/whykusanagi/celeste-cli/releases) page and verify
it (see [Security & Verification](#-security--verification) below).

To add to PATH:
```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```

### Manual Installation

Alternatively, build from source:

```bash
# 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):**
```bash
celeste config --set-key YOUR_XAI_KEY
celeste chat
```

**With Collections (RAG):**
```bash
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:**
```bash
celeste config --init openai
celeste -config openai config --set-key YOUR_OPENAI_KEY
celeste -config openai chat
```

**Sakana (Fugu):**
```bash
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:
```bash
cd your-project
celeste chat
# Creates .grimoire (project context), indexes code graph, loads memories
```

Or manually:
```bash
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:

```bash
# 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](https://keybase.io/whykusanagi)
- **GitHub**: [whykusanagi.gpg](https://github.com/whykusanagi.gpg)

**Import Key** — use the repository copy; it carries the signing subkey the
releases are signed with:
```bash
# 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 |
| **read_file** | Read files with checkpointing |
| **write_file** | Write files with snapshot backup |
| **patch_file** | Apply targeted edits to files |
| **splice_file** | Move a region between files by anchors/line-ranges (deterministic, no model-routed bytes) |
| **list_files** | List directory contents with glob patterns |
| **search** | Search file contents with regex |
| **git_status** | Show working tree status |
| **git_log** | Show commit history |

### Code Graph Tools (6 Tools)

| Tool | Description |
|------|-------------|
| **code_search** | MinHash semantic search across all indexed symbols |
| **code_review** | Graph-based code review (6 categories: stubs, lazy redirects, placeholders, TODOs, error swallowing, hardcoded values) |
| **code_graph** | Query symbol relationships and call chains |
| **code_symbols** | List symbols in a file or package |
| **code_impact** | Blast-radius analysis: which callers are affected by a changed symbol |
| **code_snapshot** | 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 |
|------|-------------|
| **spawn_agent** | Spawn a subagent to handle a subtask; supports DAG dependencies, worktree isolation, and background execution |
| **post_message** | 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-whykusanagi-celeste-cli
- Seller: https://agentstack.voostack.com/s/whykusanagi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.