{"id":49165579,"url":"https://github.com/whykusanagi/celeste-cli","last_synced_at":"2026-04-22T15:02:47.575Z","repository":{"id":339885110,"uuid":"1160701517","full_name":"whykusanagi/celeste-cli","owner":"whykusanagi","description":"A terminal AI assistant with multi-provider LLM support, blockchain tools, IPFS, and xAI RAG collections","archived":false,"fork":false,"pushed_at":"2026-04-14T07:07:24.000Z","size":1678,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T08:25:26.464Z","etag":null,"topics":["agentic-coding","ai","blockchain","bubble-tea","claude-code","cli","code-graph","code-review","developer-tools","golang","grok","llm","mcp-server","openai","semantic-search","terminal","tui","xai"],"latest_commit_sha":null,"homepage":"https://github.com/whykusanagi/celeste-cli","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whykusanagi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T09:13:48.000Z","updated_at":"2026-04-14T06:34:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/whykusanagi/celeste-cli","commit_stats":null,"previous_names":["whykusanagi/celeste-cli"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/whykusanagi/celeste-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whykusanagi%2Fceleste-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whykusanagi%2Fceleste-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whykusanagi%2Fceleste-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whykusanagi%2Fceleste-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whykusanagi","download_url":"https://codeload.github.com/whykusanagi/celeste-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whykusanagi%2Fceleste-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32141485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T14:31:12.705Z","status":"ssl_error","status_checked_at":"2026-04-22T14:27:43.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai","blockchain","bubble-tea","claude-code","cli","code-graph","code-review","developer-tools","golang","grok","llm","mcp-server","openai","semantic-search","terminal","tui","xai"],"created_at":"2026-04-22T15:02:46.631Z","updated_at":"2026-04-22T15:02:47.559Z","avatar_url":"https://github.com/whykusanagi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://s3.whykusanagi.xyz/optimized_assets/hypnosis_expression_trans_ghub.png\" alt=\"Celeste - Corrupted AI Assistant\" width=\"300\"/\u003e\n\n\u003csub\u003eCharacter artwork by [いかわさ (ikawasa23)](https://x.com/ikawasa23)\u003c/sub\u003e\n\n# 👁️ Celeste CLI - Interactive AI Assistant\n\n**A premium, corruption-aesthetic command-line interface for CelesteAI**\n\n[![Go Version](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat\u0026logo=go)](https://golang.org/)\n[![License](https://img.shields.io/badge/License-MIT-purple)](LICENSE)\n[![TUI Framework](https://img.shields.io/badge/TUI-Bubble%20Tea-d94f90)](https://github.com/charmbracelet/bubbletea)\n\n*Built with [Charm's Bubble Tea](https://github.com/charmbracelet/bubbletea) for flicker-free, modern terminal experiences*\n\n\u003c/div\u003e\n\n---\n\n## ✨ What is Celeste CLI?\n\nCeleste CLI is a **full standalone agentic development tool** with her own persona, featuring:\n- 🎨 **Premium TUI** - Flicker-free rendering with corrupted-theme aesthetics\n- 🔮 **40 Built-in Tools** - File I/O, shell, web search, code graph, code review, collections search, git, crypto, and more\n- 📖 **`.grimoire` Project Context** - Persona-themed project config files with auto-discovery and auto-init\n- 🧠 **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\n- 🔍 **Graph-Based Code Review** - Structural analysis detecting stubs, lazy redirects, placeholders, error swallowing, and hardcoded values\n- 🔌 **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)\n- 🔒 **Permission System** - Multi-layer allow/deny/ask rules with pattern matching\n- 💾 **Session Persistence** - JSONL auto-save, resume, file checkpointing with stale detection and revert\n- 🌐 **Multi-Provider** - Grok/xAI (default), OpenAI, Anthropic (native SDK), Gemini, Venice.ai, Vertex AI, OpenRouter\n- 💰 **Cost Tracking** - Per-model pricing with live session cost display\n- 🪝 **Hooks** - Pre/post tool execution hooks defined in `.grimoire`\n- 🧠 **Extended Thinking** - Leverage reasoning tokens (Claude, Gemini, Grok) with `/effort` control\n- 🖼️ **Image Input** - Multimodal support for vision-capable models\n- 🎭 **Celeste Personality** - Embedded AI personality with lore-accurate responses\n- 🔗 **Blockchain Tools** - IPFS, Alchemy, wallet security monitoring\n\n### Three Runtime Modes\n\n| Mode | Command | What it does |\n|------|---------|-------------|\n| **Chat** | `celeste chat` (default) | Interactive chat with auto-looping tool calls (50-turn safety cap). |\n| **Agent** | `/agent \u003cgoal\u003e` (in TUI) or `celeste agent --goal \"...\"` | Fully autonomous multi-turn agent with planning, file I/O, checkpointing, and resume. For long-running tasks. |\n| **Orchestrator** | `/orchestrate \u003cgoal\u003e` (in TUI) | Agent run with a second reviewer model that critiques and debates the output. For high-quality deliverables. |\n\n\u003e **Chat vs Agent**: Chat is interactive with tool auto-looping — you guide the conversation while Celeste\n\u003e calls tools as needed. Agent is a separate autonomous runtime with its own turn loop, planning phase,\n\u003e checkpoint store, and workspace awareness. The orchestrator adds a reviewer model on top of the agent.\n\n---\n\n## 🚀 Quick Start\n\n### Quick Install (Recommended)\n\nIf you have Go 1.23+ installed:\n\n```bash\ngo install github.com/whykusanagi/celeste-cli/cmd/celeste@latest\n```\n\nThe `celeste` binary will be installed to `$GOPATH/bin` (or `~/go/bin` by default).\n\n**Requirements:**\n- Go 1.26.0 or higher\n- `$GOPATH/bin` (or `~/go/bin`) in your PATH\n\nTo add to PATH:\n```bash\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\n```\n\n### Manual Installation\n\nAlternatively, build from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/whykusanagi/celeste-cli.git\ncd celeste-cli\n\n# Build the binary\ngo build -o celeste ./cmd/celeste\n\n# Install to PATH (optional)\ncp celeste ~/.local/bin/\n```\n\n### First Run\n\n**xAI/Grok (default — recommended):**\n```bash\nceleste config --set-key YOUR_XAI_KEY\nceleste chat\n```\n\n**With Collections (RAG):**\n```bash\nceleste config --set-key YOUR_XAI_KEY\nceleste config --set-management-key YOUR_XAI_MANAGEMENT_KEY\nceleste collections list          # see available collections\nceleste collections enable \u003cid\u003e   # enable for chat\nceleste chat\n```\n\n**OpenAI:**\n```bash\nceleste config --init openai\nceleste -config openai config --set-key YOUR_OPENAI_KEY\nceleste -config openai chat\n```\n\n**Other providers:** `celeste config --init \u003cname\u003e` where name is: `grok`, `openai`, `venice`, `elevenlabs`\n\n### Project Setup\n\nWhen you enter a project directory, Celeste auto-initializes:\n```bash\ncd your-project\nceleste chat\n# Creates .grimoire (project context), indexes code graph, loads memories\n```\n\nOr manually:\n```bash\nceleste init          # create .grimoire\nceleste index         # build code graph\nceleste index status  # check graph stats\n```\n\n---\n\n## 🔒 Security \u0026 Verification\n\nAll Celeste CLI releases are cryptographically signed with GPG to ensure authenticity and integrity.\n\n### Quick Verification\n\nBefore using a downloaded binary, verify its authenticity:\n\n```bash\n# Download verification script\ncurl -O https://raw.githubusercontent.com/whykusanagi/celeste-cli/main/scripts/verify.sh\nchmod +x verify.sh\n\n# Verify your download\n./verify.sh celeste-linux-amd64.tar.gz\n```\n\n### Manual Verification\n\nFor manual verification or more details, see the complete [Verification Guide](VERIFICATION.md).\n\n**Release Signing:**\n- All commits are GPG-signed\n- All releases include GPG signatures\n- Checksums are signed with GPG\n- Complete manifest with build metadata\n\n**PGP Key Information:**\n- **Key ID**: `875849AB1D541C55`\n- **Fingerprint**: `9404 90EF 09DA 3132 2BF7  FD83 8758 49AB 1D54 1C55`\n- **Keybase**: [@whykusanagi](https://keybase.io/whykusanagi)\n- **GitHub**: [whykusanagi.gpg](https://github.com/whykusanagi.gpg)\n\n**Import Key**:\n```bash\n# From Keybase (recommended)\ncurl https://keybase.io/whykusanagi/pgp_keys.asc | gpg --import\n\n# From GitHub\ncurl https://github.com/whykusanagi.gpg | gpg --import\n```\n\nFor security issues, see our [Security Policy](SECURITY.md) or contact security@whykusanagi.xyz.\n\n---\n\n## 📚 Table of Contents\n\n- [Installation](#-quick-start)\n- [Security \u0026 Verification](#-security--verification)\n- [Features](#-features)\n- [Tool System (40 Tools)](#-tool-system-40-tools)\n- [Claude Code Integration](#-claude-code-integration)\n- [Comparison](#-how-celeste-compares)\n- [LLM Provider Compatibility](#-llm-provider-compatibility)\n- [Function Calling Flow](#-function-calling-flow-mermaid-diagram)\n- [Configuration](#%EF%B8%8F-configuration)\n- [Usage](#-usage)\n- [Architecture](#%EF%B8%8F-architecture)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n\n---\n\n## 🎯 Features\n\n### Interactive TUI Mode\n- **Flicker-Free Rendering** - Double-buffered Bubble Tea rendering (no screen tearing)\n- **Scrollable Chat** - PgUp/PgDown navigation through conversation history\n- **Input History** - Arrow keys to browse previous messages (like bash history)\n- **Skills Panel** - Real-time skill execution status with demonic eye animation\n- **Corrupted Theme** - Lip Gloss styling with pink/purple abyss aesthetic\n- **Real Streaming + Corruption Animation** - Token-by-token streaming with corrupted glitch phrases at the typing cursor\n- **Markdown Rendering** - glamour-powered markdown with corrupted theme (code blocks, tables, headers, bold)\n\n### Tool System (v1.9)\n**40+ built-in tools** powered by AI function calling:\n- Dev Tools (bash, read/write/patch files, search, list files)\n- Code Graph (semantic search with MinHash+BM25 fusion, code review, symbol analysis, tree-sitter TypeScript parsing)\n- Direct Codegraph MCP Tools (`celeste_index`, `celeste_code_search`, `celeste_code_review`, `celeste_code_graph`, `celeste_code_symbols` — verbatim, no chat-LLM round-trip)\n- Git (status, log)\n- Web (search, fetch)\n- Information Services (Weather, Currency, Twitch, YouTube)\n- Utilities (Conversions, Encoding, Generators, QR codes)\n- Productivity (Reminders, Notes, Todo tracking)\n- Blockchain (IPFS, Alchemy, wallet security)\n\n[See complete tool list below](#-tool-system-38-tools)\n\n### Collections Support (xAI RAG)\n- **Upload Custom Documents** - Create knowledge bases with your own documentation\n- **Semantic Search** - Celeste automatically searches collections when answering questions\n- **Interactive TUI** - Manage collections with `/collections` command in chat\n- **CLI Management** - Create, upload, enable/disable collections from command line\n- **Multiple Collections** - Organize by topic, enable only what's relevant\n\n[See Collections Guide](docs/COLLECTIONS.md) for setup and usage.\n\n### Tool System (v1.7)\n- **MCP (Model Context Protocol) support** for external tool servers\n- **Permission system** with configurable allow/deny rules\n- **Streaming tool execution** with concurrent dispatch\n- **Automatic context window management**\n\n### Session Management\n- **Conversation Persistence** - Auto-save and resume sessions seamlessly\n- **Message History** - Full conversation logging with timestamps\n- **Session Listing** - Browse and load previous sessions by ID\n- **Session Clearing** - Bulk delete sessions when needed\n\n### Multi-Provider Support (7 Providers)\n- ✅ **Grok/xAI** (grok-4-1-fast) - **DEFAULT** - Optimized for tool calling, 2M context • Token tracking ✓\n- ✅ **OpenAI** (gpt-4.1-mini, gpt-4.1) - Full function calling with streaming • Token tracking ✓\n- ✅ **Anthropic Claude** (claude-sonnet-4-5) - Native SDK with prompt caching and extended thinking • Token tracking ✓\n- ✅ **Google Gemini AI** (gemini-2.5-flash) - Simple API keys, free tier, full streaming • Token tracking ✓\n- ⚠️ **Google Vertex AI** (gemini-2.5-flash) - Enterprise, requires GCP project + billing • Token tracking ✓\n- ✅ **Venice.ai** (venice-uncensored) - NSFW mode, image generation/upscaling • Token tracking ✓\n- ✅ **OpenRouter** (multi-provider) - Parallel function calling support • Token tracking ✓\n\n**Dynamic Model Selection** - Auto-selects best tool-calling model per provider\n**Capability Indicators** - Visual feedback (✓ skills / ⚠️ no skills) in header\n\n[See full compatibility matrix](#-llm-provider-compatibility)\n\n### Configuration\n- **JSON-based Config** - Modern `~/.celeste/config.json` format\n- **Named Configs** - Multi-profile support (openai, grok, venice, etc.)\n- **Skills Config** - Separate `skills.json` for skill-specific API keys\n- **Secrets Handling** - Separate `secrets.json` for backward compatibility\n- **Persona Injection** - Configurable Celeste personality prompt\n- **Environment Override** - Env vars override file config\n\n---\n\n## 🔮 Tool System (40 Tools)\n\nCeleste 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.\n\n### Dev Tools (8 Tools)\n\n| Tool | Description |\n|------|-------------|\n| **bash** | Execute shell commands in the workspace |\n| **read_file** | Read files with checkpointing |\n| **write_file** | Write files with snapshot backup |\n| **patch_file** | Apply targeted edits to files |\n| **list_files** | List directory contents with glob patterns |\n| **search** | Search file contents with regex |\n| **git_status** | Show working tree status |\n| **git_log** | Show commit history |\n\n### Code Graph Tools (4 Tools)\n\n| Tool | Description |\n|------|-------------|\n| **code_search** | MinHash semantic search across all indexed symbols |\n| **code_review** | Graph-based code review (6 categories: stubs, lazy redirects, placeholders, TODOs, error swallowing, hardcoded values) |\n| **code_graph** | Query symbol relationships and call chains |\n| **code_symbols** | List symbols in a file or package |\n\n### Divination \u0026 Entertainment\n\n| Skill | Description | Dependencies |\n|-------|-------------|--------------|\n| **Tarot Reading** | Three-card or Celtic Cross spreads | Tarot API (requires auth token) |\n\n**Example:**\n```\nYou: Give me a tarot reading\nCeleste: *calls tarot_reading skill*\nCeleste: Your cards reveal... [interpretation]\n```\n\n### Content \u0026 Media\n\n| Skill | Description | Dependencies |\n|-------|-------------|--------------|\n| **NSFW Mode** | Venice.ai uncensored responses | Venice.ai API key |\n| **Content Generation** | Platform-specific templates (Twitter/TikTok/YouTube/Discord) | None (LLM-powered) |\n| **Image Generation** | Venice.ai image creation | Venice.ai API key |\n\n**Example:**\n```\nYou: Generate a tweet about cybersecurity\nCeleste: *calls generate_content skill*\nCeleste: Here's your tweet: [280 char tweet with hooks]\n```\n\n### Information Services\n\n| Skill | Description | Dependencies |\n|-------|-------------|--------------|\n| **Weather** | Current conditions and forecasts | wttr.in API (free, no key) |\n| **Currency Converter** | Real-time exchange rates | ExchangeRate-API (free) |\n| **Twitch Live Check** | Check if streamers are online | Twitch API (client ID required) |\n| **YouTube Videos** | Get recent uploads from channels | YouTube Data API (key required) |\n\n**Example:**\n```\nYou: What's the weather in 10001?\nCeleste: *calls get_weather skill*\nCeleste: It's 45°F and cloudy in New York City...\n```\n\n### Utilities (9 Skills)\n\n| Skill | Description | Dependencies |\n|-------|-------------|--------------|\n| **Unit Converter** | Length, weight, temperature, volume | None (local calculations) |\n| **Timezone Converter** | Convert times between zones | None (local calculations) |\n| **Hash Generator** | MD5, SHA256, SHA512 | None (crypto/sha256) |\n| **Base64 Encode** | Encode text to base64 | None (encoding/base64) |\n| **Base64 Decode** | Decode base64 to text | None (encoding/base64) |\n| **UUID Generator** | Generate random UUIDs (v4) | None (google/uuid) |\n| **Password Generator** | Secure random passwords (customizable) | None (crypto/rand) |\n| **QR Code Generator** | Create QR codes from text/URLs | None (skip2/go-qrcode) |\n\n**Example:**\n```\nYou: Convert 100 miles to kilometers\nCeleste: *calls convert_units skill*\nCeleste: 100 miles is 160.93 kilometers\n```\n\n### Productivity (5 Skills)\n\n| Skill | Description | Dependencies |\n|-------|-------------|--------------|\n| **Set Reminder** | Create reminders with timestamps | Local storage (~/.celeste/reminders.json) |\n| **List Reminders** | View all active reminders | Local storage |\n| **Save Note** | Store notes by name | Local storage (~/.celeste/notes.json) |\n| **Get Note** | Retrieve saved notes | Local storage |\n| **List Notes** | View all saved note names | Local storage |\n\n**Example:**\n```\nYou: Remind me to call mom tomorrow at 3pm\nCeleste: *calls set_reminder skill*\nCeleste: Reminder set for December 4, 2025 at 3:00 PM\n\nYou: Save a note called groceries: milk, eggs, bread\nCeleste: *calls save_note skill*\nCeleste: Note 'groceries' saved successfully!\n```\n\n### Skills Configuration\n\nSkill-specific API keys are stored in `~/.celeste/skills.json`:\n\n```json\n{\n  \"venice_api_key\": \"your-venice-key\",\n  \"tarot_auth_token\": \"Basic xxx\",\n  \"weather_default_zip_code\": \"12345\",\n  \"twitch_client_id\": \"your-client-id\",\n  \"youtube_api_key\": \"your-youtube-key\"\n}\n```\n\n**Configure via CLI:**\n```bash\nceleste config --set-venice-key \u003ckey\u003e\nceleste config --set-weather-zip 12345\nceleste config --set-twitch-client-id \u003cid\u003e\nceleste config --set-youtube-key \u003ckey\u003e\nceleste config --set-tarot-token \u003ctoken\u003e\n```\n\n---\n\n## 🔌 Claude Code Integration\n\nCeleste v1.9.0+ exposes the codegraph as **first-class MCP tools** (no chat-LLM\nround-trip, no output-token ceiling, verbatim results). Register `celeste serve`\nonce per workspace and any MCP client — Claude Code, Codex, Cursor, etc. — gets:\n\n- `celeste_index` — `status`, `update`, `rebuild` operations with `notifications/progress` streaming\n- `celeste_code_search` — semantic search (MinHash Jaccard + BM25 fusion + structural rerank)\n- `celeste_code_review` — structural code review findings as verbatim JSON\n- `celeste_code_graph` — symbol callers, callees, references\n- `celeste_code_symbols` — list symbols in a file or package\n\nIndexing is **explicit**: query tools never auto-reindex. After code changes, the\ncaller invokes `celeste_index { operation: \"update\" }` to refresh the graph.\n\n```bash\n# Add Celeste as an MCP server (once per workspace you want indexed)\nclaude mcp add celeste celeste serve\n```\n\nOptionally, install the [celeste-for-claude](https://github.com/whykusanagi/celeste-for-claude)\ncompanion for the persona-routed skill command wrappers (`/celeste-review`,\n`/celeste-search`, `/celeste-graph`, `/celeste-context`):\n\n```bash\ngit clone https://github.com/whykusanagi/celeste-for-claude.git\ncp celeste-for-claude/skills/*.md ~/.claude/commands/\n```\n\nClaude Code stays in control, Celeste provides the graph intelligence. The\ndirect tools are preferred for tool-driven workflows; the persona-routed skills\nare a convenience for natural-language interactions.\n\n---\n\n## 📊 How Celeste Compares\n\n| | **Celeste CLI** | **OpenClaw** | **Picobot** | **oh-my-pi** | **gptme** |\n|---|---|---|---|---|---|\n| **Focus** | Agentic coding | Personal AI assistant | Lightweight AI bot | CLI coding agent | CLI coding agent |\n| **Language** | Go | TypeScript | Go | TS + Rust | Python |\n| **Deploy** | 54MB binary, zero deps | Node.js (~393MB) | 9MB binary | Bun + Rust | pip package |\n| **RAM** | Low | High (Node.js) | ~10MB | Medium | Medium |\n| **Providers** | 7 (native SDKs) | OpenAI primary | OpenAI only | 6+ | 7+ |\n| **Tools** | 40 | Many | 16 | Many | ~10 |\n| **Code Graph** | Yes (MinHash) | No | No | No | No |\n| **Code Review** | Yes (6 categories) | No | No | No | No |\n| **Collections/RAG** | Yes (xAI) | No | No | No | Yes |\n| **MCP** | Server + client | Partial | Client | Full | Yes |\n\n**Celeste's unique advantages:** Code graph with semantic search, structural code review, persistent project memory, `.grimoire` context with staleness tracking, corruption-aesthetic TUI with typing animation. No other project combines compiled binary + code intelligence + MCP server.\n\nSee [docs/COMPARISON.md](docs/COMPARISON.md) for detailed analysis.\n\n---\n\n## 🌐 LLM Provider Compatibility\n\nCeleste CLI requires **OpenAI-style function calling** for skills to work. Not all LLM providers support this feature.\n\n### Quick Reference Matrix\n\n| Provider | Function Calling | Status | Setup Difficulty |\n|----------|------------------|---------|------------------|\n| **OpenAI** | ✅ Native | Fully Supported | Easy |\n| **Grok (xAI)** | ✅ OpenAI-Compatible | Fully Supported | Easy |\n| **DigitalOcean** | ⚠️ Cloud Functions Only | Limited | Advanced (requires cloud deployment) |\n| **Venice.ai** | ❓ Unknown | Needs Testing | Unknown |\n| **ElevenLabs** | ❓ Unknown | Needs Testing | Unknown |\n| **Local (Ollama)** | ⚠️ Depends on Model | Varies | Medium (model-dependent) |\n\n### ✅ Fully Supported: Grok/xAI (Default)\n\n**Setup:**\n```bash\nceleste config --set-key your-xai-key\nceleste chat\n```\n\nDefault config points to xAI (`https://api.x.ai/v1`, model `grok-4-1-fast`). Best value for tool calling with 2M token context.\n\n### ✅ Fully Supported: OpenAI\n\n**Setup:**\n```bash\nceleste config --set-key sk-your-openai-key\nceleste config --set-url https://api.openai.com/v1\nceleste config --set-model gpt-4.1-mini\nceleste chat\n```\n\n### ⚠️ Limited Support: DigitalOcean\n\n**Limitation:** DigitalOcean AI Agent requires **cloud-hosted functions**. Skills cannot execute locally.\n\n**Why skills won't work:**\n- Celeste CLI executes skills locally (unit converter, QR generator, etc.)\n- DigitalOcean expects HTTP endpoints in the cloud\n- No way to bridge local execution with DigitalOcean's architecture\n\n**Workarounds:**\n1. Use OpenAI or Grok instead\n2. Deploy skills as cloud functions (advanced)\n3. Use Celeste CLI without skills (chat only)\n\n### Testing Provider Compatibility\n\nRun automated tests to verify function calling:\n\n```bash\n# Test OpenAI\nOPENAI_API_KEY=your-key go test ./cmd/celeste/llm -run TestOpenAI_FunctionCalling -v\n\n# Test Grok\nGROK_API_KEY=your-key go test ./cmd/celeste/llm -run TestGrok_FunctionCalling -v\n\n# Test Venice.ai\nVENICE_API_KEY=your-key go test ./cmd/celeste/llm -run TestVeniceAI_FunctionCalling -v\n```\n\n**Expected output (working):**\n```\n=== RUN   TestOpenAI_FunctionCalling\n✅ OpenAI function calling works! Called get_weather with location=new york\n--- PASS: TestOpenAI_FunctionCalling (2.34s)\n```\n\n**Expected output (not working):**\n```\n=== RUN   TestVeniceAI_FunctionCalling\n⚠️ Venice.ai function calling failed: tools not supported\n--- SKIP: TestVeniceAI_FunctionCalling\n```\n\n📚 **See [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) for complete provider compatibility guide**\n\n---\n\n## 🎨 Function Calling Flow (Mermaid Diagram)\n\nHere's how skills work under the hood:\n\n```mermaid\n%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#4a90e2','primaryTextColor':'#fff','primaryBorderColor':'#357abd','lineColor':'#6c757d','secondaryColor':'#7c3aed','tertiaryColor':'#10b981','noteBkgColor':'#fef3c7','noteTextColor':'#92400e'}}}%%\nsequenceDiagram\n    actor User\n    participant CLI as Celeste CLI\n    participant LLM as LLM Provider\n    participant Skill as Skill Handler\n    participant API as External API\n\n    User-\u003e\u003e+CLI: \"What's the weather in NYC?\"\n    CLI-\u003e\u003e+LLM: Send message + tools definition\n    Note right of LLM: AI decides:\u003cbr/\u003eneed weather data\n    LLM--\u003e\u003e-CLI: tool_call: get_weather(location=\"NYC\")\n    CLI-\u003e\u003e+Skill: Execute get_weather handler\n    Skill-\u003e\u003e+API: Fetch weather data (wttr.in)\n    API--\u003e\u003e-Skill: JSON weather response\n    Skill--\u003e\u003e-CLI: Formatted weather data\n    CLI-\u003e\u003e+LLM: Send tool result back\n    Note right of LLM: Generate natural\u003cbr/\u003eresponse\n    LLM--\u003e\u003e-CLI: \"It's 45°F and cloudy in NYC...\"\n    CLI-\u003e\u003e-User: Display response with typing animation\n```\n\n### Key Points:\n1. **Tools sent with every request** - All available skills are listed in the API call\n2. **LLM decides when to call** - You don't manually invoke skills, the AI does\n3. **Local execution** - Skills run on your machine (unless they need external APIs)\n4. **Result sent back to LLM** - Tool results are formatted and returned for interpretation\n5. **Natural language output** - LLM converts structured data into conversational responses\n\n**This requires OpenAI-style function calling support!** Providers without this feature will ignore tools and respond as if they don't have access to data.\n\n---\n\n## ⚙️ Configuration\n\n### Configuration Files\n\nCeleste CLI uses three config files in `~/.celeste/`:\n\n| File | Purpose | Example |\n|------|---------|---------|\n| **config.json** | Main configuration | API endpoint, model, timeouts |\n| **secrets.json** | API keys (backward compat) | OpenAI API key only |\n| **skills.json** | Skill-specific configs | Venice.ai key, weather zip code |\n\n### Main Config (`~/.celeste/config.json`)\n\n```json\n{\n  \"api_key\": \"\",\n  \"base_url\": \"https://api.x.ai/v1\",\n  \"model\": \"grok-4-1-fast\",\n  \"timeout\": 60,\n  \"skip_persona_prompt\": false,\n  \"simulate_typing\": true,\n  \"typing_speed\": 40\n}\n```\n\n### Skills Config (`~/.celeste/skills.json`)\n\n```json\n{\n  \"venice_api_key\": \"your-venice-key\",\n  \"venice_base_url\": \"https://api.venice.ai/api/v1\",\n  \"venice_model\": \"venice-uncensored\",\n  \"tarot_function_url\": \"https://your-tarot-api\",\n  \"tarot_auth_token\": \"Basic xxx\",\n  \"weather_default_zip_code\": \"10001\",\n  \"twitch_client_id\": \"your-twitch-client-id\",\n  \"twitch_default_streamer\": \"whykusanagi\",\n  \"youtube_api_key\": \"your-youtube-key\",\n  \"youtube_default_channel\": \"UC...\"\n}\n```\n\n### Environment Variables (Override Config)\n\n```bash\nexport CELESTE_API_KEY=\"sk-your-key\"\nexport CELESTE_API_ENDPOINT=\"https://api.openai.com/v1\"\nexport VENICE_API_KEY=\"your-venice-key\"\nexport TAROT_AUTH_TOKEN=\"Basic xxx\"\n```\n\nEnvironment variables take precedence over config files.\n\n### Config Commands\n\n```bash\n# View current config\nceleste config --show\n\n# Main config settings\nceleste config --set-key sk-xxx\nceleste config --set-url https://api.openai.com/v1\nceleste config --set-model gpt-4o-mini\nceleste config --skip-persona true\nceleste config --simulate-typing true\nceleste config --typing-speed 60\n\n# Named configs (multi-profile support)\nceleste config --list                     # List all profiles\nceleste config --init openai              # Create openai profile\nceleste config --init grok                # Create grok profile\nceleste -config grok chat                 # Use grok profile\n\n# Skill configuration\nceleste config --set-venice-key \u003ckey\u003e\nceleste config --set-weather-zip 10001\nceleste config --set-twitch-client-id \u003cid\u003e\nceleste config --set-youtube-key \u003ckey\u003e\nceleste config --set-tarot-token \u003ctoken\u003e\n```\n\n### Named Configs (Multi-Profile)\n\nCreate separate configs for different providers:\n\n```bash\n# Create OpenAI config\nceleste config --init openai\nceleste config --set-key sk-openai-key\nceleste config --set-model gpt-4o-mini\n\n# Create Grok config\nceleste config --init grok\nceleste config --set-key xai-grok-key\nceleste config --set-url https://api.x.ai/v1\nceleste config --set-model grok-beta\n\n# Use specific config\nceleste -config grok chat\n```\n\n**Available templates**: `openai`, `grok`, `elevenlabs`, `venice`, `digitalocean`\n\n---\n\n## 🎯 Usage\n\n### Interactive TUI Mode\n\n```bash\n# Launch interactive TUI (default command)\nceleste chat\n\n# Use a specific named config\nceleste -config grok chat\n```\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `Ctrl+C` | Exit immediately |\n| `Ctrl+D` | Exit gracefully |\n| `PgUp/PgDown` | Scroll chat history (full page) |\n| `Shift+↑/↓` | Scroll chat (3 lines at a time) |\n| `↑/↓` | Navigate input history (previous messages) |\n| `Enter` | Send message |\n| `Esc` | Clear current input |\n\n### In-Chat Commands\n\n#### Core Commands\n| Command | Action |\n|---------|--------|\n| `/help` | Show available commands and keyboard shortcuts |\n| `/clear` | Clear chat history (current session only) |\n| `/exit`, `/quit`, `/q` | Exit application |\n\n#### Provider \u0026 Model Management\n| Command | Action |\n|---------|--------|\n| `/endpoint \u003cprovider\u003e` | Switch to a different LLM provider (openai, grok, venice, gemini, openrouter, etc.) |\n| `/set-model` | List available models for current provider with capability indicators |\n| `/set-model \u003cname\u003e` | Switch to a specific model (validates function calling support) |\n| `/set-model \u003cname\u003e --force` | Override model compatibility warnings |\n| `/list-models` | Alias for `/set-model` |\n\n**Examples:**\n```bash\n# Switch to Grok (auto-selects grok-4-1-fast for tool calling)\n/endpoint grok\n\n# List Grok models with capability indicators\n/set-model\n# Output:\n# ✓ grok-4-1-fast - Best for tool calling (2000k context)\n# ✓ grok-4-1 - High-quality reasoning\n#   grok-4-latest - Latest general model (no skills)\n\n# Force use a non-tool model\n/set-model grok-4-latest --force\n\n# Switch to Gemini AI (AI Studio)\n/endpoint gemini\n```\n\n#### Context Management \u0026 Analytics\n| Command | Action |\n|---------|--------|\n| `/context` | Show current token usage, cost estimation, and context window status |\n| `/stats` | Display usage analytics dashboard with provider/model breakdowns |\n| `/export [format]` | Export current session (formats: json, md, csv) |\n\n**Token Tracking Support by Provider:**\n\n✅ **Full Support** (Returns usage data with automatic token tracking):\n- OpenAI (gpt-4o, gpt-4o-mini, etc.)\n- xAI/Grok (grok-4-1-fast, grok-4-1, etc.)\n- Venice.ai (venice-uncensored, etc.)\n- Google Gemini AI Studio (gemini-2.0-flash, etc.)\n- Google Vertex AI (gemini models via OpenAI endpoint)\n- OpenRouter (all models)\n- **DigitalOcean Gradient** (Agent API with RAG - supports stream_options.include_usage)\n\n❌ **No Support** (Uses estimation only):\n- Anthropic Claude (Native API - different format, not yet implemented)\n- ElevenLabs (Voice-focused API)\n\n**Examples:**\n```bash\n# Check current context usage\n/context\n# Shows: Token usage (12.5K/128K), cost ($0.034), warning level\n\n# View analytics dashboard\n/stats\n# Shows: Lifetime usage, top models, provider breakdown, daily stats\n\n# Export conversation to Markdown\n/export md\n# Saves to: ~/.celeste/exports/session_\u003cid\u003e_\u003ctimestamp\u003e.md\n\n# Export to JSON for programmatic access\n/export json\n```\n\n**Note:** When using providers without token tracking (Anthropic native API, ElevenLabs), Celeste CLI will estimate tokens based on character count (~4 chars = 1 token), but won't show exact API usage or costs. For accurate token tracking and context management features, use providers marked with ✅ above.\n\n### Single Message Mode (Non-Interactive)\n\n```bash\n# Send a single message and exit\nceleste message \"What is the meaning of life?\"\n\n# Or use shorthand\nceleste \"Hello, Celeste!\"\n```\n\n### Session Management\n\n```bash\n# List saved sessions\nceleste session --list\n\n# Load a specific session\nceleste session --load abc123def\n\n# Clear all sessions\nceleste session --clear\n```\n\nSessions are auto-saved to `~/.celeste/sessions/` and can be resumed later.\n\n### Skills Management\n\n```bash\n# List available skills (with descriptions)\nceleste skills --list\n\n# Initialize default skill configuration files\nceleste skills --init\n```\n\n### Version \u0026 Help\n\n```bash\n# Show version\nceleste version\nceleste --version\n\n# Show help\nceleste help\nceleste --help\n```\n\n### 🔥 NSFW Mode (Venice.ai Integration)\n\nNSFW mode provides uncensored chat and NSFW image generation via Venice.ai:\n\n**Activating NSFW Mode:**\n```bash\n# In chat, type:\n/nsfw\n\n# Header will show: 🔥 NSFW • img:lustify-sdxl\n```\n\n**Image Generation Commands:**\n\n```bash\n# Generate with default model (lustify-sdxl)\nimage: cyberpunk cityscape at night\n\n# Generate anime-style images\nanime: magical girl with sword\n\n# Generate dream-like images\ndream: surreal cosmic landscape\n\n# Use specific model for one generation\nimage[venice-sd35]: photorealistic portrait\n\n# Upscale existing image\nupscale: ~/path/to/image.jpg\n```\n\n**Model Management:**\n\n```bash\n# Set default image model\n/set-model wai-Illustrious\n\n# View available models\n/set-model\n\n# Models available:\n# - lustify-sdxl (default NSFW)\n# - wai-Illustrious (anime style)\n# - hidream (dream-like quality)\n# - nano-banana-pro\n# - venice-sd35 (Stable Diffusion 3.5)\n# - lustify-v7\n# - qwen-image\n```\n\n**Image Quality Settings:**\n\nAll images generate with high-quality defaults:\n- **Steps**: 40 (1-50, higher = more detail)\n- **CFG Scale**: 12.0 (0-20, higher = stronger prompt adherence)\n- **Size**: 1024x1024 (up to 1280x1280)\n- **Format**: PNG (lossless)\n- **Safe Mode**: Disabled (no NSFW blurring)\n\n**Download Location:**\n\nImages save to `~/Downloads` by default. Customize in `~/.celeste/skills.json`:\n\n```json\n{\n  \"downloads_dir\": \"~/Pictures\"\n}\n```\n\n**LLM Prompt Chaining:**\n\nAsk the uncensored LLM to write prompts for you:\n\n```\nYou: Write a detailed NSFW anime scene description\nCeleste: [Generates detailed prompt]\nYou: image: [paste Celeste's prompt]\nCeleste: *generates image from AI-written prompt*\n```\n\n**Returning to Safe Mode:**\n\n```bash\n/safe\n# Returns to OpenAI endpoint with skills enabled\n```\n\n**Configuration:**\n\nAdd Venice.ai API key to `~/.celeste/skills.json`:\n\n```json\n{\n  \"venice_api_key\": \"your-venice-api-key\",\n  \"venice_base_url\": \"https://api.venice.ai/api/v1\",\n  \"venice_model\": \"venice-uncensored\",\n  \"venice_image_model\": \"lustify-sdxl\",\n  \"downloads_dir\": \"~/Downloads\"\n}\n```\n\n**Limitations:**\n\n- Function calling disabled in NSFW mode (Venice uncensored doesn't support it)\n- Skills are unavailable (use /safe to re-enable)\n- Video generation not available (Venice API limitation)\n\n---\n\n## 🏗️ Architecture\n\n### Project Structure\n\n```\nceleste-cli/\n├── cmd/celeste/               # Main application\n│   ├── main.go               # CLI entry point\n│   ├── tui/                  # Bubble Tea TUI components\n│   │   ├── app.go           # Main TUI model \u0026 update loop\n│   │   ├── chat.go          # Scrollable viewport (messages)\n│   │   ├── input.go         # Text input + history\n│   │   ├── skills.go        # Skills panel (execution status)\n│   │   ├── styles.go        # Lip Gloss theme (corrupted aesthetic)\n│   │   ├── streaming.go     # Simulated typing animation\n│   │   └── messages.go      # Bubble Tea messages (events)\n│   ├── tools/             # Unified tool system\n│   │   ├── builtin/       # All built-in tool implementations\n│   │   └── mcp/           # MCP client for external tools\n│   ├── permissions/       # Tool permission system\n│   ├── context/           # Token budget \u0026 context management\n│   ├── llm/                 # LLM client\n│   │   ├── client.go        # OpenAI-compatible client\n│   │   ├── stream.go        # Streaming handler (SSE)\n│   │   └── providers_test.go # Provider compatibility tests\n│   ├── config/              # Configuration management\n│   │   ├── config.go        # JSON config (load/save/named)\n│   │   └── session.go       # Session persistence\n│   └── prompts/             # Persona prompts\n│       ├── celeste.go       # Prompt loader\n│       └── celeste_essence.json # Embedded Celeste personality\n├── docs/                     # Documentation\n│   ├── LLM_PROVIDERS.md     # Provider compatibility guide\n│   ├── CAPABILITIES.md      # What Celeste can do (ecosystem)\n│   ├── PERSONALITY.md       # Celeste personality quick ref\n│   └── ROUTING.md           # Sub-agent routing (ecosystem)\n├── LICENSE                   # MIT License\n├── CHANGELOG.md             # Version history\n├── CONTRIBUTING.md          # Contribution guidelines\n├── SECURITY.md              # Security policy\n└── README.md                # This file\n```\n\n### Component Flow Diagram\n\n```mermaid\n%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#4a90e2','secondaryColor':'#7c3aed','tertiaryColor':'#10b981','primaryTextColor':'#fff','lineColor':'#6c757d','fontSize':'14px'}}}%%\nflowchart TB\n    subgraph CLI[\"🖥️ CLI Entry (main.go)\"]\n        style CLI fill:#e8f4f8,stroke:#4a90e2,stroke-width:2px\n        Main[Parse Args] --\u003e |chat| TUI[Launch TUI]\n        Main --\u003e |config| Config[Config Manager]\n        Main --\u003e |session| Session[Session Manager]\n        Main --\u003e |skills| Skills[Skills Registry]\n        Main --\u003e |help| Help[Print Help]\n    end\n\n    subgraph TUI_Layer[\"🎨 TUI Layer (Bubble Tea)\"]\n        style TUI_Layer fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px\n        TUI --\u003e Header[Header Bar]\n        TUI --\u003e Viewport[Chat Viewport]\n        TUI --\u003e Input[Text Input + History]\n        TUI --\u003e SkillsPanel[Skills Panel]\n        TUI --\u003e Status[Status Bar]\n    end\n\n    subgraph Backend[\"⚙️ Backend (Business Logic)\"]\n        style Backend fill:#fef3c7,stroke:#f59e0b,stroke-width:2px\n        Input --\u003e |user message| LLM[LLM Client]\n        LLM --\u003e |stream chunks| Stream[Streaming Handler]\n        Stream --\u003e |SSE parsing| SimType[Simulated Typing]\n        SimType --\u003e |char-by-char| Viewport\n        LLM --\u003e |tool_calls detected| Executor[Skill Executor]\n        Executor --\u003e |lookup| Registry[Skills Registry]\n        Registry --\u003e |execute| Handler[Skill Handler]\n        Handler --\u003e |result| Executor\n        Executor --\u003e |tool result| LLM\n        LLM --\u003e |final response| Stream\n    end\n\n    subgraph Storage[\"💾 Persistence Layer\"]\n        style Storage fill:#d1fae5,stroke:#10b981,stroke-width:2px\n        Config --\u003e ConfigFiles[\"~/.celeste/config.json\"]\n        Session --\u003e SessionFiles[\"~/.celeste/sessions/*.json\"]\n        Handler --\u003e |reminders/notes| LocalStorage[\"~/.celeste/reminders.json\"]\n    end\n\n    subgraph External[\"🌐 External APIs\"]\n        style External fill:#fee2e2,stroke:#ef4444,stroke-width:2px\n        Handler --\u003e |weather| WttrIn[wttr.in API]\n        Handler --\u003e |tarot| TarotAPI[Tarot Function]\n        Handler --\u003e |nsfw/images| VeniceAI[Venice.ai]\n        Handler --\u003e |currency| ExchangeRate[ExchangeRate-API]\n        Handler --\u003e |twitch| TwitchAPI[Twitch API]\n        Handler --\u003e |youtube| YouTubeAPI[YouTube Data API]\n    end\n\n    classDef entryPoint fill:#4a90e2,stroke:#357abd,color:#fff\n    classDef uiComponent fill:#7c3aed,stroke:#6b21a8,color:#fff\n    classDef business fill:#f59e0b,stroke:#d97706,color:#fff\n    classDef storage fill:#10b981,stroke:#059669,color:#fff\n    classDef external fill:#ef4444,stroke:#dc2626,color:#fff\n\n    class Main,TUI entryPoint\n    class LLM,Stream,Executor business\n    class ConfigFiles,SessionFiles,LocalStorage storage\n    class WttrIn,TarotAPI,VeniceAI,ExchangeRate,TwitchAPI,YouTubeAPI external\n```\n\n### Data Flow: User Message → Response\n\n1. **User Input** → Text input component (with history)\n2. **TUI Update** → Bubble Tea update loop processes input\n3. **LLM Request** → Client sends message + tools to OpenAI/Grok\n4. **Stream Parse** → Parse SSE chunks (text or tool_calls)\n5. **Tool Execution** (if tool_calls):\n   - Executor receives tool call JSON\n   - Registry looks up skill handler\n   - Handler executes (local or API call)\n   - Result sent back to LLM\n6. **Response Stream** → LLM generates natural language response\n7. **Simulated Typing** → Character-by-character rendering (if enabled)\n8. **Viewport Update** → Chat history updates with new message\n9. **Session Save** → Auto-save conversation to disk\n\n---\n\n## 🎨 Theming\n\nThe TUI uses the **corrupted-theme** color palette inspired by Celeste's abyss aesthetic:\n\n| Color | Hex | RGB | Usage |\n|-------|-----|-----|-------|\n| **Accent** | `#d94f90` | `rgb(217, 79, 144)` | Headers, prompts, highlights, user messages |\n| **Purple** | `#8b5cf6` | `rgb(139, 92, 246)` | Function calls, secondary elements, skill names |\n| **Dark Purple** | `#6d28d9` | `rgb(109, 40, 217)` | Borders, subtle accents |\n| **Background** | `#0a0a0a` | `rgb(10, 10, 10)` | Main background (terminal) |\n| **Surface** | `#1a1a1a` | `rgb(26, 26, 26)` | Elevated surfaces, panels |\n| **Text** | `#f5f1f8` | `rgb(245, 241, 248)` | Primary text, assistant messages |\n| **Muted** | `#7a7085` | `rgb(122, 112, 133)` | Hints, timestamps, secondary text |\n| **Success** | `#10b981` | `rgb(16, 185, 129)` | Skill success indicators |\n| **Error** | `#ef4444` | `rgb(239, 68, 68)` | Errors, warnings |\n\n### Demonic Eye Animation\n\nWhen Celeste is thinking, a demonic eye animation plays:\n\n```\n👁️  → 👀 → ◉◉ → ●● (pulsing)\n```\n\nColors pulse between magenta (`#d94f90`) and red (`#dc2626`) to show \"corruption deepening.\"\n\n---\n\n## 🔧 Development\n\n### Prerequisites\n\n- **Go 1.21+** (uses go 1.24.0 for latest features)\n- **Terminal** with 256-color support (iTerm2, Alacritty, Windows Terminal, etc.)\n- **API Keys** (for testing skills):\n  - OpenAI API key (required for chat)\n  - Venice.ai API key (optional, for NSFW/image skills)\n  - YouTube Data API key (optional, for YouTube skill)\n  - Twitch Client ID (optional, for Twitch skill)\n\n### Building from Source\n\n```bash\ncd celeste-cli\ngo mod tidy\ngo build -o celeste ./cmd/celeste\n```\n\n### Running Tests\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run with coverage\ngo test -cover ./...\n\n# Run specific package\ngo test ./cmd/celeste/skills -v\n\n# Run provider compatibility tests\nOPENAI_API_KEY=sk-xxx go test ./cmd/Celeste/llm -run TestOpenAI_FunctionCalling -v\n```\n\n### Code Quality Checks\n\n```bash\n# Format code\ngofmt -w ./cmd\n\n# Run linter\ngo vet ./...\n\n# Check for unused imports\ngoimports -w ./cmd\n```\n\n### Dependencies\n\n| Package | Purpose | Version |\n|---------|---------|---------|\n| `github.com/charmbracelet/bubbletea` | TUI framework | v1.3.10 |\n| `github.com/charmbracelet/bubbles` | TUI components (viewport, textinput) | v0.21.0 |\n| `github.com/charmbracelet/lipgloss` | Styling engine | v1.1.0 |\n| `github.com/sashabaranov/go-openai` | OpenAI client (streaming, function calling) | v1.20.4 |\n| `github.com/google/uuid` | UUID generation | v1.6.0 |\n| `github.com/skip2/go-qrcode` | QR code generation | v0.0.0-20200617195104 |\n| `github.com/stretchr/testify` | Testing framework | v1.11.1 |\n\n### Branch Strategy\n\n- **main** - Stable releases only\n- **feature/bubbletea-tui** - Current development branch (TUI implementation)\n- Feature branches - Fork from `feature/bubbletea-tui`\n\n---\n\n## 🔍 Troubleshooting\n\n### No API Key Configured\n\n**Error:**\n```\nNo API key configured.\nSet CELESTE_API_KEY environment variable or run: celeste config --set-key \u003ckey\u003e\n```\n\n**Solution:**\n```bash\nceleste config --set-key sk-your-openai-key\n```\n\nOr use environment variable:\n```bash\nexport CELESTE_API_KEY=\"sk-your-key\"\nceleste chat\n```\n\n### Skills Not Working\n\n**Symptom:** LLM says \"I don't have access to real-time data\" when asking for weather, etc.\n\n**Possible Causes:**\n1. **Provider doesn't support function calling** - See [LLM Provider Compatibility](#-llm-provider-compatibility)\n2. **Skill config missing** - Check `~/.celeste/skills.json` for required API keys\n\n**Solution:**\n```bash\n# Test provider compatibility\nOPENAI_API_KEY=your-key go test ./cmd/celeste/llm -run TestOpenAI_FunctionCalling -v\n\n# If provider doesn't support skills, switch to OpenAI or Grok\nceleste config --set-url https://api.openai.com/v1\nceleste config --set-key sk-openai-key\n```\n\n### Persona Prompt Issues\n\n**Symptom:** Celeste doesn't respond with personality, or endpoint errors\n\n**Cause:** Your endpoint might already have the Celeste persona embedded (e.g., DigitalOcean agent)\n\n**Solution:**\n```bash\nceleste config --skip-persona true\n```\n\n### Streaming Looks Choppy\n\n**Symptom:** Text appears in large chunks instead of smooth typing\n\n**Solution:** Enable simulated typing:\n```bash\nceleste config --simulate-typing true\nceleste config --typing-speed 40  # Adjust speed (chars per second)\n```\n\n### Session Not Saving\n\n**Symptom:** Conversations don't persist between runs\n\n**Cause:** Sessions directory not writable or doesn't exist\n\n**Solution:**\n```bash\n# Check permissions\nls -la ~/.celeste/sessions/\n\n# If missing, create it\nmkdir -p ~/.celeste/sessions/\nchmod 755 ~/.celeste/sessions/\n```\n\n### TUI Rendering Issues\n\n**Symptom:** Screen flickering, garbled text, or broken layout\n\n**Possible Causes:**\n1. Terminal doesn't support 256 colors\n2. Terminal size too small\n3. Environment variable issues\n\n**Solution:**\n```bash\n# Check terminal capabilities\necho $TERM        # Should be xterm-256color or similar\ntput colors       # Should return 256\n\n# Set TERM if needed\nexport TERM=xterm-256color\n\n# Ensure minimum terminal size (80x24)\nresize  # Check current size\n```\n\n### Build Errors\n\n**Error:** `go: updates to go.mod needed; to update it: go mod tidy`\n\n**Solution:**\n```bash\ngo mod tidy\ngo build -o celeste ./cmd/celeste\n```\n\n**Error:** `package X is not in GOROOT`\n\n**Solution:**\n```bash\n# Update dependencies\ngo get -u ./...\ngo mod tidy\n```\n\n---\n\n## 📖 Documentation\n\nComprehensive documentation for developers and contributors:\n\n### Core Documentation\n\n- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System design, component relationships, and data flow diagrams\n- **[TESTING.md](docs/TESTING.md)** - Testing guide with examples, coverage reports, and best practices\n- **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** - How to contribute: adding skills, providers, and commands\n- **[LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md)** - Provider compatibility matrix and setup guides\n- **[STYLE_GUIDE.md](docs/STYLE_GUIDE.md)** - Code formatting standards and conventions\n\n### Test Coverage (v1.2.0)\n\nOverall coverage: **17.4%** across critical packages\n\n| Package | Coverage | Status |\n|---------|----------|--------|\n| prompts | 97.1% | ✅ Excellent |\n| providers | 72.8% | ✅ Excellent |\n| config | 52.0% | ✅ Good |\n| commands | 25.8% | ⚠️ Moderate |\n| venice | 22.6% | ⚠️ Moderate |\n| skills | 12.2% | ⚠️ Low |\n| llm | 0% | ❌ Requires mocking |\n| tui | 0% | ❌ Requires mocking |\n\nSee [TESTING.md](docs/TESTING.md) for details on running tests and writing new ones.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.\n\n### Quick Start for Contributors\n\n1. **Fork the repository**\n2. **Create a feature branch** from `feature/bubbletea-tui`:\n   ```bash\n   git checkout feature/bubbletea-tui\n   git checkout -b feature/your-feature-name\n   ```\n3. **Make your changes**\n4. **Test thoroughly**:\n   ```bash\n   go test ./...\n   go vet ./...\n   gofmt -l ./cmd  # Should return nothing\n   ```\n5. **Submit a pull request** to `feature/bubbletea-tui`\n\n### Areas for Contribution\n\n- 🧪 **Testing** - Provider compatibility tests, skill unit tests, integration tests\n- 📚 **Documentation** - Improve guides, add examples, translate to other languages\n- 🎨 **Themes** - Alternative color schemes, terminal themes\n- 🔮 **Skills** - New skill implementations (requires function calling support)\n- 🐛 **Bug Fixes** - See [GitHub Issues](https://github.com/whykusanagi/celeste-cli/issues)\n- ⚡ **Performance** - Optimize streaming, reduce memory usage\n\n### Testing Your Changes\n\nBefore submitting a PR:\n\n```bash\n# Build succeeds\ngo build -o celeste ./cmd/celeste\n\n# All tests pass\ngo test ./...\n\n# No vet warnings\ngo vet ./...\n\n# Code is formatted\ngofmt -w ./cmd\ngit diff  # Should show no changes\n\n# TUI works\n./celeste chat\n```\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🔗 Links\n\n- [Documentation](docs/)\n- [Contributing](CONTRIBUTING.md)\n- [Security Policy](SECURITY.md)\n- [Changelog](CHANGELOG.md)\n\n---\n\n## 🙏 Acknowledgments\n\n- **[Charm](https://charm.sh/)** - Bubble Tea, Bubbles, and Lip Gloss TUI frameworks\n- **[sashabaranov/go-openai](https://github.com/sashabaranov/go-openai)** - OpenAI Go client\n- **OpenAI** - Function calling API\n- **xAI** - Grok API\n- **Venice.ai** - Uncensored AI models\n- **wttr.in** - Free weather API\n\n---\n\n## 📞 Support\n\n- **Issues:** [GitHub Issues](https://github.com/whykusanagi/celeste-cli/issues)\n- **Security:** See [SECURITY.md](SECURITY.md)\n- **Documentation:** [docs/](docs/)\n- **Community:** [Discord](https://discord.gg/whykusanagi) (coming soon)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with 💜 by [@whykusanagi](https://github.com/whykusanagi)**\n\n*\"The Abyss whispers through the terminal...\" - Celeste*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhykusanagi%2Fceleste-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhykusanagi%2Fceleste-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhykusanagi%2Fceleste-cli/lists"}