{
  "markdown": "# Crustly 🥐\n\n<p align=\"center\">\n  <img src=\"docs/images/crustly-badge.png\" alt=\"Crustly — AI coding assistant, built with Rust\" width=\"320\">\n</p>\n\n**High-Performance Terminal AI Assistant for Software Development**\n\n> A blazingly fast, memory-efficient terminal-based AI assistant written in Rust.\n> Rust reimplementation of Crush with 95%+ feature parity and superior performance.\n\n[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)\n[![License](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](LICENSE.md)\n[![CI](https://github.com/jyjeanne/crustly/actions/workflows/ci.yml/badge.svg)](https://github.com/jyjeanne/crustly/actions/workflows/ci.yml)\n```\n   ___             _   _\n  / __|_ _ _  _ __| |_| |_  _\n | (__| '_| || (_-<  _| | || |\n  \\___|_|  \\_,_/__/\\__|_|\\_, |\n                         |__/\n        🥐 Flaky & Fast\n```\n\n---\n\n## Table of Contents\n\n- [📸 Screenshots](#-screenshots)\n- [🎯 Main Coding Features](#-main-coding-features)\n- [✨ What's New](#-whats-new)\n- [🔒 Interactive Approval System](#-interactive-approval-system)\n- [⚠️ Important Disclaimers](#️-important-disclaimers)\n- [🌐 Supported AI Providers](#-supported-ai-providers)\n- [🧩 Reference Coding Models & Hardware Requirements](#-reference-coding-models--hardware-requirements)\n- [🚀 Quick Start](#-quick-start)\n- [📋 A Note on Claude Max and GitHub Copilot](#-a-note-on-claude-max-and-github-copilot)\n- [🏠 Running Crustly with Local LLMs](#-running-crustly-with-local-llms)\n- [💡 Best Practices for Using Crustly](#-best-practices-for-using-crustly)\n- [👨‍💻 Why Crustly for Coding?](#-why-crustly-for-coding)\n- [📋 Plan Mode — Structured Task Planning](#-plan-mode--structured-task-planning)\n- [🧠 Native Skills — /review & /spec](#-native-skills--review--spec)\n- [🧪 Manual Testing Guide](#-manual-testing-guide)\n- [📊 Performance](#-performance)\n- [🏗️ Architecture](#️-architecture)\n- [📁 Project Structure](#-project-structure)\n- [🔍 Debug and Logging](#-debug-and-logging)\n- [🛠️ Development](#️-development)\n- [📖 Documentation](#-documentation)\n- [🤝 Contributing](#-contributing)\n- [🐛 Known Issues & Platform-Specific Notes](#-known-issues--platform-specific-notes)\n- [📄 License](#-license)\n- [🙏 Acknowledgments](#-acknowledgments)\n- [📞 Support](#-support)\n- [📈 Status](#-status)\n\n---\n\n## 📸 Screenshots\n\n### Main Interface\n![Crustly Main Interface](docs/screenshots/main-screen.png)\n*Interactive chat interface with syntax highlighting and real-time streaming*\n\n### Deep Code Analysis\n![Deep Code Analysis](docs/screenshots/deeply-analyse.png)\n*Comprehensive code analysis with detailed insights and suggestions*\n\n### AI Thinking Mode\n![AI Thinking Mode](docs/screenshots/thinking-mode.png)\n*Watch the AI reasoning process in real-time as it analyzes your code*\n\n### Help & Commands\n![Help Screen](docs/screenshots/help-screnn.png)\n*Built-in help system and keyboard shortcuts for efficient navigation*\n\n---\n\n## 🎯 Main Coding Features\n\n**Your AI coding assistant that lives in your terminal.**\n\n### ⚡ **Core Capabilities**\n\n| Feature | Description | Benefit |\n|---------|-------------|---------|\n| 🔧 **Built-in Tools** | 22 tools: files, shell, web, agents, skills | Direct code manipulation from chat |\n| 🔒 **Interactive Approval** | Permission dialogs for dangerous operations | Full control over what AI can do |\n| 🎨 **Syntax Highlighting** | 100+ languages with line numbers | Beautiful code display in terminal |\n| 🏠 **Local LLM Support** | Run with LM Studio/Ollama | 100% private, $0 cost, offline |\n| 💬 **Multi-line Input** | Paste entire functions | Natural code interaction |\n| 🧠 **Session Context** | Persistent conversation memory | Maintains project context |\n| ⌨️ **Terminal Native** | Fast keyboard shortcuts | No context switching |\n| 💰 **Cost Tracking** | Per-message token & cost | Budget control |\n| 🌊 **Streaming** | Real-time token-by-token rendering | See code as it's written |\n| 🧠 **Reasoning Display** | DeepSeek-R1 / QwQ-32B thinking blocks | Understand AI reasoning, press `t` to expand |\n\n### 🚀 **Quick Example**\n\n```bash\n$ crustly\n\nYou: \"Read src/main.rs\"\nCrustly: [reads file with syntax highlighting]\n\nYou: \"Add error handling to the database connection\"\nCrustly: [modifies file with write tool]\n\nYou: \"Run cargo test\"\nCrustly: [executes] ✅ 145 tests passed\n\nYou: \"Generate documentation for this module\"\nCrustly: [creates comprehensive docs]\n```\n\n### 🔒 **Privacy First**\n\n```bash\n# Use local LLMs for sensitive code\n# 100% private - code never leaves your machine\n# See \"Using Crustly with Local LLMs\" section below\n```\n\n### 💡 **Perfect For**\n\n- ✅ **Code Generation** - Functions, tests, entire modules\n- ✅ **Debugging** - Error analysis and fixes with context\n- ✅ **Refactoring** - Improve code quality\n- ✅ **Documentation** - Generate docs, comments, READMEs\n- ✅ **Code Review** - Get feedback on your code, or run `/review` for a multi-pass automated audit\n- ✅ **Learning** - Understand complex concepts\n- ✅ **Terminal Workflow** - Stay in your flow, no browser tabs\n\n---\n\n## ✨ What's New\n\n### Unreleased — Native `/review` and `/spec` Skills\n\nTwo new slash commands work in any project with zero setup, on top of a\ngeneric fix to how `/`-commands are handled. See\n[🧠 Native Skills](#-native-skills--review--spec) below for the full\nwriteup, or the skill source directly at\n[src/llm/tools/builtin_skills/](src/llm/tools/builtin_skills/).\n\n- **`/review`** — multi-pass automated code review of the current diff, a\n  PR, a branch, or a path. Independent correctness/guideline-compliance/\n  security passes dispatch in parallel via the `agent` tool, then a\n  second, skeptical pass filters every finding by confidence before\n  anything is reported — a review that cries wolf gets ignored.\n  `--comment` posts a summary via `gh`, `--fix` applies the surviving\n  findings.\n- **`/spec`** — native Specification-Driven Development:\n  `specify → plan → tasks → implement → analyze`, writing versioned\n  artifacts to `specs/<NNN>-<slug>/`. One skill, phase inferred from\n  trailing args — `/spec \"feature description\"` starts a new feature,\n  `/spec plan` / `/spec tasks` / `/spec implement` / `/spec analyze`\n  advance it. Includes a constitution gate (simplicity / anti-abstraction\n  / integration-first) during planning. Modeled on the `spec-driven`\n  schema from the same author's external\n  [rustyspec](https://github.com/jyjeanne/rustyspec) and\n  [solidspec](https://github.com/jyjeanne/solidspec) projects — named the\n  polyvalent default among solidspec's 7 workflow schemas — but unlike\n  those (separate CLIs that must hand off to an external agent),\n  `implement` runs natively in this session: Crustly already is the\n  agent, so it drives `task_manager`/`write_file`/`edit_file`/`bash`\n  directly and checks off `tasks.md` as it builds.\n- **Fixed:** nothing previously routed a typed `/<name>` to the `skill`\n  tool that could load it — `/review`, `/spec`, or any project-defined\n  skill just sent literal text to the model instead of triggering. Slash\n  input now resolves any unmatched `/<name>` through the same lookup\n  order `SkillTool` uses (project `.crustly/skills/`, `.claude/skills/`,\n  user-global, then a small set of built-ins compiled into the binary)\n  before falling back to a plain chat message — off the blocking-safe\n  `spawn_blocking` path, so the filesystem walk never stalls TUI\n  rendering.\n\n### Unreleased — In-Process llama.cpp Provider\n\nA third local-inference path, alongside the OpenAI-compatible route and\nnative Ollama: `providers.llama_cpp` loads a `.gguf` file **directly into\nthe Crustly process** via [`llama-cpp-2`](https://github.com/utilityai/llama-cpp-rs) —\nno Ollama daemon, no LM Studio server, no port to start. See\n[docs/guides/LLAMA_CPP_GUIDE.md](docs/guides/LLAMA_CPP_GUIDE.md) for setup\nand [llama-cpp-2-integration-plan.md](llama-cpp-2-integration-plan.md) for\nthe full technical design and phase-by-phase implementation record.\n\n- **Streaming, tool calling, GPU offload** — token-by-token streaming,\n  the same printed-JSON tool-call recovery Ollama falls back to, and six\n  optional GPU backend features (`llama-cpp-cuda`/`-metal`/`-vulkan`/`-rocm`/`-opencl`/`-mkl`)\n  with a startup warning if `n_gpu_layers` is set without a matching\n  feature compiled in.\n- **Grammar-constrained tool calling** (`--features llama-cpp-llguidance`) —\n  the moment a response commits to a bare-JSON tool call, decoding swaps\n  mid-stream to a sampler that can only produce tokens forming a valid\n  call to one of the tools actually offered. Ships with the fixes from two\n  rounds of code review: the swap trigger requires the model to have\n  already typed a real offered tool's name (not just an opening brace, to\n  avoid hijacking legitimate JSON-shaped prose into a fabricated call),\n  and the sampler swap correctly carries over repeat-penalty history and\n  RNG state instead of discarding it.\n- **Local model management** — `Ctrl+G` TUI dialog (pick a downloaded\n  `.gguf`, download a new one by URL or `hf:org/repo/file.gguf` shorthand\n  with a live progress bar, delete with `Del`) and CLI equivalents\n  (`crustly llama-cpp list|pull|rm`).\n- **Idle-unload** — `providers.llama_cpp.idle_unload_secs` frees the\n  loaded model and its context after a configurable idle period, reloading\n  on the next request.\n- **Fixed:** responses echoed the requested model name instead of the\n  model actually loaded, breaking `ModelRouter`'s tier-based auto-routing\n  for this provider.\n\n### v0.5.2 — Local-Model Reliability & Per-Model Tuning\n\nA hardening pass driven by end-to-end testing of the full agentic tool loop\nagainst local Ollama models (qwen2.5-coder, gemma4, ornith).\n\n#### Per-Model Ollama Settings\nDifferent models want different tuning, and one global set silently degrades\nevery model but the one it was tuned for. Sampling and context can now be set\nper model:\n\n```toml\n[providers.ollama.models.\"gemma4:12B\"]\nnum_ctx = 32768        # verbose reasoners need room, or they exhaust the\ntemperature = 0.6      # window mid-turn and never reach their tool call\n\n[providers.ollama.models.\"qwen2.5-coder:7b\"]\ntemperature = 0.2      # low temperature for tool-use / coding\n```\n\nEach field falls back to the provider-level `[providers.ollama]` value when\nunset. The per-model `num_ctx` is also what context compaction budgets\nagainst (`context_window` resolves through the same value), so the requested\nand assumed windows can never drift. Applied identically at startup and when\nswitching models with `Ctrl+W` — both go through a single construction path.\n\n#### Approval That Means Yes\nThe `security.allow_bash` allowlist is now strictly a **no-prompt shortcut**,\nnot a wall:\n\n- Allowlisted, operator-free commands run silently (as before).\n- Anything else — including commands with shell operators such as\n  `mkdir x && cd x && cargo init` — **prompts, showing the full command\n  verbatim, and your approval runs exactly that**. Previously these were\n  silently refused *after* you approved them, which broke every local\n  model's natural `cd <dir> && <cmd>` workflow.\n- Operator commands are **never** auto-trusted (the allowlist checks only\n  the first token, so `ls && rm -rf /` always prompts), and Plan/read-only\n  mode still rejects them outright.\n\n#### Reasoning-Only Answers Surfaced, Not Blank\nReasoning models (ornith, DeepSeek-R1, QwQ — and gemma under context\npressure) sometimes put their *entire* answer in the thinking channel and\nreturn no visible text. That used to render as an empty message with a\ncollapsed `[Thinking ▸]` toggle. The reasoning is now promoted to the\nvisible answer with a clear *\"this model returned only its reasoning\"*\nnotice — display-only, never persisted into the history the model sees.\n\n#### Tool Calls Recovered from Prose\nSome model templates print tool calls as text instead of populating Ollama's\n`tool_calls` field. Recovery now also handles calls wrapped in ```json\nfences *inside* explanatory prose (qwen2.5-coder's retry pattern after a\nrejected command) — strictly: only fenced blocks, only offered tools, only\nexplicit arguments. Bare JSON mentioned in prose is still never executed.\n\n#### Reliability & UX Fixes\n- **Fixed the \"Message not found\" crash** that broke every `crustly run`\n  invocation: sqlx-sqlite does not auto-commit `INSERT ... RETURNING`, so on\n  the file-backed WAL pool the new row was invisible to the next pooled\n  connection. Message creation now commits an explicit transaction.\n- **Fixed the tool-loop detector falsely aborting** consecutive\n  `edit_file`/`write_file`/`read_file` calls to *different* paths (it read\n  the wrong input key, so distinct calls shared one signature).\n- **`Ctrl+W` model switch keeps your config** — it used to rebuild a bare\n  provider, dropping per-model settings, sampling, `num_ctx`, `keep_alive`.\n- **TUI timestamps are shown in local time** (they were rendered in UTC).\n- **`Ctrl+K` (clear session) is refused while a response is generating**,\n  instead of deleting messages out from under the in-flight request.\n- **Model-not-found errors are actionable** — deleting the configured\n  default model from Ollama now yields \"install it with `ollama pull`,\n  switch with `Ctrl+W`, or update `default_model` in config.toml\" instead\n  of a raw JSON error body.\n- **`--model` CLI flag** — override the configured default model for a\n  single invocation of any command: `crustly --model \"gemma4:12B\" run \"...\"`.\n- **Chat input no longer renders underlined** — the textarea widget\n  underlines the cursor line by default, which in a chat input is all the\n  text being typed.\n\n### v0.5.0 — Gemini Provider & Claude Code / Qwen Compatibility\n\n#### Native Google Gemini Provider\nGemini joins Anthropic and OpenAI as a third fully-implemented cloud provider. It also serves Google's open-weight **Gemma 3/4** models through the same API — no local GPU or Ollama required, and Gemma usage through the Gemini API is free of charge. Supports streaming, function calling, vision, extended thinking (`thinkingConfig`/`includeThoughts`), and JSON/structured output (`responseSchema`). See the **Supported AI Providers** section below for setup.\n\n#### `apply_patch` Tool\nA new 22nd built-in tool: real Codex-compatible multi-file patch support, so the model can describe a coordinated set of file edits in a single structured patch instead of issuing one `edit_file` call per file.\n\n#### Claude Code / Qwen Compatibility Layer\nA round of interoperability fixes so Crustly's tool set behaves the same way regardless of which model is driving it:\n\n- **Tool name alias layer** — models trained on Claude Code's or Qwen's tool names resolve to Crustly's built-in tools without a prompt-side mapping\n- **`file_path`/`directory` argument aliases and `shell` field compatibility** — accepts the parameter names Claude Code and Qwen actually send\n- **`grep` defaults to regex** and both **`grep`/`glob` now respect `.gitignore`**, matching Claude Code/qwen-code semantics\n- **Prior-read enforcement** — `edit_file`, `write_file`, and `apply_patch` now require the target file to have been read first in the session, catching a class of blind overwrite mistakes\n- **Hardened Qwen Hermes tool-call parsing** — resilient to truncated or malformed JSON tool calls, and MCP tool naming/`edit_file` schema is now compatible with Qwen/Claude Code\n\n#### Bug Fixes & Dependency Upgrades\n- Fixed the macOS-only path boundary check incorrectly rejecting valid paths to not-yet-existing files under a symlinked root\n- Updated the markdown renderer for the `pulldown-cmark` 0.13 API\n- Completed the `ratatui` 0.28 → 0.30 upgrade, migrating off the now-unmaintained `tui-textarea`\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full history, including the Phase 4\ntool parity release, real-time streaming, reasoning display, context\ncompaction, smart model routing, parallel tool dispatch, provider failover,\nthe sandbox/permission policy, episodic memory, the codebase index, MCP\nintegration, AWS Bedrock support, and the native Ollama provider.\n\n---\n\n### 🆚 **Why Choose Crustly?**\n\n| You Want | Crustly Delivers |\n|----------|------------------|\n| Privacy | ✅ Local LLM support, data stays on your machine |\n| Cost Control | ✅ Token tracking + free local inference |\n| Terminal Native | ✅ No GUI, perfect for CLI lovers |\n| File Operations | ✅ Built-in read/write/execute tools |\n| Context Awareness | ✅ Persistent sessions, never lose context |\n| Beautiful Code | ✅ Syntax highlighting for 100+ languages |\n| Fast Workflow | ✅ Keyboard shortcuts, streaming responses |\n\n---\n\n## 🔒 Interactive Approval System\n\n**Crustly gives you complete control over dangerous operations with beautiful interactive approval dialogs.**\n\n### How It Works\n\nWhen Claude wants to modify files or execute commands, Crustly pauses and asks for your permission:\n\n```\n┌────────────────────────────────────────────────────┐\n│ ⚠️  PERMISSION REQUIRED                            │\n├────────────────────────────────────────────────────┤\n│ 🔒 Permission Request                              │\n│                                                    │\n│ Claude wants to use the tool: write_file          │\n│                                                    │\n│ Description: Write content to a file...            │\n│                                                    │\n│ ⚠️  Capabilities:                                   │\n│    • WriteFiles                                    │\n│    • SystemModification                            │\n│                                                    │\n│ Parameters:                                        │\n│    path: \"config.json\"                             │\n│    content: \"{ \\\"debug\\\": true }\"                  │\n│                                                    │\n│ [A]pprove  [D]eny  [V]iew Details  [Esc] Cancel  │\n└────────────────────────────────────────────────────┘\n```\n\n### Security Features\n\n✅ **Dangerous operations always require approval:**\n- File writes (`write_file`)\n- Shell commands (`bash`)\n- System modifications\n\n✅ **Safe operations proceed automatically:**\n- File reads (`read_file`)\n- Information queries\n\n✅ **Full transparency:**\n- See exactly what Claude wants to do\n- View all parameters before deciding\n- Toggle detailed JSON view with `V` key\n\n✅ **Complete control:**\n- Press `A` or `Y` to approve\n- Press `D` or `N` to deny\n- Press `Esc` to cancel\n- No way to bypass (unless explicitly configured)\n\n### Auto Mode (Explicitly Bypassing Approval)\n\nPress `Shift+Tab` to cycle through three levels of autonomy, shown at all\ntimes in the status bar:\n\n| Level | Behavior |\n|-------|----------|\n| `⚙ Interactive` (default) | Every dangerous tool call prompts, as above. |\n| `⚡ AutoPlan` | Low-risk tools (reads, searches, etc.) run without prompting. `bash`, `write_file`, `edit_file`, and `code_exec` still prompt. |\n| `⚡⚡ FullAuto` | Nothing prompts, including `bash`/`write_file`/`edit_file`/`code_exec`. Use with care. |\n\nTwo things stay true no matter which level is active:\n- The `[security]` config policy (`deny_tools`, `deny_paths`, `allow_bash`)\n  is a separate, earlier check and is **never** bypassed by Auto Mode —\n  it's the hard floor.\n- Every auto-approved action is logged identically to a manually-approved\n  one, so there's a full audit trail regardless of which level was active.\n\nStarts at `Interactive` by default; set `[plan_mode].mode` in\n`config.toml` (`\"interactive\"` / `\"auto_plan\"` / `\"full_auto\"`) to change\nthe starting level, or just cycle it with `Shift+Tab` mid-session.\n\n`crustly run --yolo`/`crustly run --auto-approve` is a related but\nseparate mechanism for the non-interactive CLI path\n(`crustly run \"<prompt>\"`), not the TUI - it always bypasses everything\nunconditionally, with no `AutoPlan`-style tiering.\n\n### Example Workflow\n\n```bash\nYou: \"Create a config file with debug enabled\"\n\n[Approval Dialog Appears]\nClaude wants to: write_file\nPath: config.json\nContent: { \"debug\": true }\n\n[You Press 'A']\n\nClaude: ✅ \"I've created the config file at config.json\"\n```\n\n**Your safety is our priority.** Every dangerous operation requires your explicit approval.\n\n---\n\n## ⚠️ Important Disclaimers\n\n### 🚧 Development Status\n\n**Crustly is currently under active development.** While functional, it is not yet production-ready and may contain bugs or incomplete features.\n\n### 💰 Token Cost Responsibility\n\n**You are responsible for monitoring and managing your own API usage and costs.**\n\n- We are **NOT responsible** for token cost overload from paid cloud AI services (Anthropic Claude, OpenAI, etc.)\n- API costs are your responsibility - always monitor your usage\n- Set up billing alerts with your cloud provider\n- Consider using local LLMs (LM Studio, Ollama) for cost-free operation\n\n### 🔧 Support Limitations\n\n**We are NOT responsible for troubleshooting issues with paid cloud AI services.**\n\n- Cloud API issues should be directed to the respective providers\n- Billing questions should go to Anthropic, OpenAI, etc.\n- We provide the tool, you manage your API relationships\n\n### 💡 Recommendations\n\n✅ **Always monitor your API usage dashboard**\n✅ **Set billing limits with your cloud provider**\n✅ **Test with small requests first**\n✅ **Use local LLMs for cost-free development**\n✅ **Review pricing before using cloud APIs**\n\n> **By using Crustly, you acknowledge these risks and responsibilities.**\n\n---\n\n## 🌐 Supported AI Providers\n\nCrustly currently has **3 fully implemented cloud providers**: **Anthropic**, **OpenAI**, and **Google Gemini**. The OpenAI provider is compatible with any OpenAI-compatible API, enabling local LLMs and alternative providers.\n\n### Implemented Providers\n\n#### ✅ Anthropic Claude (Fully Supported)\n- **Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku\n- **Setup**: `export ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY\"`\n- **Features**: Streaming, tools, vision (via Claude), cost tracking\n\n#### ✅ OpenAI (Fully Supported)\n- **Models**: GPT-4 Turbo, GPT-4, GPT-3.5 Turbo\n- **Setup**: `export OPENAI_API_KEY=\"sk-YOUR_KEY\"`\n- **Features**: Streaming, tools, cost tracking\n- **Compatible with**: Any OpenAI-compatible API endpoint\n\n#### ✅ Google Gemini (Fully Supported — also serves Gemma)\n- **Models**: gemini-3-pro, gemini-2.5-pro/flash/flash-lite, gemini-2.0-flash, and Google's open-weight **Gemma 4** (`gemma-4-31b-it`, `gemma-4-26b-a4b-it`) and **Gemma 3** models served through the same API\n- **Setup**: `export GEMINI_API_KEY=\"AIza...\"` (get a free key at [aistudio.google.com](https://aistudio.google.com/apikey))\n- **Features**: Streaming, function calling, vision, extended thinking (`thinkingConfig`/`includeThoughts`), JSON/structured output (`responseSchema`)\n- **Why it matters for Gemma**: running Gemma 4/3 through this provider needs no local GPU, no Ollama, and Gemma usage through the Gemini API is free of charge — set `default_model = \"gemma-4-31b-it\"` under `[providers.gemini]` to use it. See `config.toml.example` for a ready-to-use snippet.\n\n### OpenAI-Compatible Providers\n\nThe OpenAI provider works with **any OpenAI-compatible API**, including:\n\n| Provider | Status | Setup |\n|----------|--------|-------|\n| **LM Studio** | ✅ Tested | `OPENAI_BASE_URL=\"http://localhost:1234/v1\"` |\n| **Ollama** | ✅ Compatible | `OPENAI_BASE_URL=\"http://localhost:11434/v1\"` |\n| **LocalAI** | ✅ Compatible | `OPENAI_BASE_URL=\"http://localhost:8080/v1\"` |\n| OpenRouter | 🟡 Compatible | `OPENAI_BASE_URL=\"https://openrouter.ai/api/v1\"` |\n| Groq | 🟡 Compatible | `OPENAI_BASE_URL=\"https://api.groq.com/openai/v1\"` |\n\n### Additional Providers\n\n| Provider | Status | Notes |\n|----------|--------|-------|\n| **AWS Bedrock** | ✅ Supported | Enable with `--features aws-bedrock`; uses standard AWS credentials |\n| Azure OpenAI | 📅 Planned | — |\n| Cerebras | 📅 Planned | — |\n| Huggingface | 📅 Planned | — |\n\n#### ✅ Native Ollama (via `ollama-rs`)\n\nIn addition to the OpenAI-compatible route above (`OPENAI_BASE_URL=\"http://localhost:11434/v1\"`),\nCrustly has a **native** Ollama provider built on [`ollama-rs`](https://github.com/pepperoni21/ollama-rs),\nenabled with `--features ollama` (or `all-llm`). It talks to Ollama's own `/api/chat` protocol instead\nof the OpenAI shim, which unlocks:\n\n- `keep_alive` / `num_ctx` control, plus **per-model overrides** — give each installed model its\n  own sampling and context window via `[providers.ollama.models.\"<name>\"]` blocks (see What's New)\n- Runtime performance metrics in the TUI header and under each reply: generation throughput\n  (tokens/sec), model load time, warm vs. cold start — none of this is available through the\n  OpenAI-compatible endpoint\n- **`Ctrl+D` Model Download dialog** — pull a model without leaving the TUI: type a name or pick\n  from suggestions (already-installed models plus a curated list), watch a live progress bar, and\n  cancel with `Esc` if you change your mind. Ollama has no online search API, so suggestions are a\n  starting point, not a catalog search — you can always type any `repo:tag` you know.\n- Model management from the command line:\n\n  ```bash\n  crustly ollama list                              # locally installed models\n  crustly ollama pull qwen2.5-coder:7b              # download a model, with live progress\n  crustly ollama rm qwen2.5-coder:7b                # delete a model\n  crustly ollama show qwen2.5-coder:7b              # license, parameters, template, capabilities\n  crustly ollama embed nomic-embed-text \"some text\"  # generate an embedding vector\n  ```\n\nConfigure it with `[providers.ollama]` in `config.toml` (see `config.toml.example`) or\n`OLLAMA_HOST`/`OLLAMA_MODEL` environment variables. Both the native and OpenAI-compatible routes to\nOllama can be configured side by side; see [`ollama-rs-integration-plan.md`](./ollama-rs-integration-plan.md)\nfor the full design and current status.\n\n#### ✅ In-process llama.cpp (via `llama-cpp-2`, no server)\n\nA third local-inference path, structurally different from the two above:\n`providers.llama_cpp` (enabled with `--features llama-cpp`, compiles native\nC++) loads a `.gguf` file **directly into the Crustly process**, via\n[`llama-cpp-2`](https://github.com/utilityai/llama-cpp-rs). No Ollama\ndaemon, no LM Studio server, no port to start.\n\n- Zero idle memory footprint outside an active Crustly session — no\n  background process exists to be idle.\n- Direct control over GPU offload (`n_gpu_layers`, six backend features:\n  `llama-cpp-cuda`/`-metal`/`-vulkan`/`-rocm`/`-opencl`/`-mkl`) and thread\n  count, without going through a server's own defaults.\n- Same tool-calling reliability mechanism as native Ollama's fallback path\n  (printed-JSON recovery, shared code — `src/llm/provider/tool_call_recovery.rs`),\n  optionally upgraded with a syntax guarantee via `--features llama-cpp-llguidance`\n  (grammar-constrained decoding for bare-JSON tool calls — see the\n  [guide](docs/guides/LLAMA_CPP_GUIDE.md#grammar-constrained-tool-calling-optional)).\n- **`Ctrl+G` Local Models dialog** — the TUI equivalent of Ollama's `Ctrl+D`:\n  pick an already-downloaded `.gguf` file to switch to (shows a \"Loading\n  model…\" state while it loads — not instant, unlike Ollama's swap), type a\n  URL or `hf:org/repo/file.gguf` shorthand to download a new one with a live\n  progress bar, or `Del` a file you no longer want.\n- Model management from the command line:\n\n  ```bash\n  crustly llama-cpp list                                                              # locally downloaded .gguf files\n  crustly llama-cpp pull hf:Qwen/Qwen2.5-Coder-7B-Instruct-GGUF/qwen2.5-coder-7b-instruct-q4_k_m.gguf\n  crustly llama-cpp rm qwen2.5-coder-7b-instruct-q4_k_m.gguf                           # asks for confirmation\n  ```\n\nTrade-offs versus the server-based routes above: requires building from\nsource with the extra Cargo feature (native C++ compilation); switching\nmodels means unloading and reloading a multi-GB file rather than Ollama's\nnear-instant swap; no sharing one loaded model across multiple clients.\nConfigure it with `[providers.llama_cpp]` in `config.toml` (see\n`config.toml.example`). See\n**[docs/guides/LLAMA_CPP_GUIDE.md](docs/guides/LLAMA_CPP_GUIDE.md)** for\nthe full setup guide and\n**[llama-cpp-2-integration-plan.md](./llama-cpp-2-integration-plan.md)**\nfor the technical design and current implementation status.\n\n### Environment Variables\n\n| Variable | Provider | Required |\n|----------|----------|----------|\n| `ANTHROPIC_API_KEY` | Anthropic Claude | ✅ For Anthropic |\n| `OPENAI_API_KEY` | OpenAI / Compatible APIs | ✅ For OpenAI |\n| `OPENAI_BASE_URL` | OpenAI-compatible APIs | Optional (for custom endpoints) |\n| `OLLAMA_HOST` (or `OLLAMA_BASE_URL`) | Native Ollama (`--features ollama`) | Optional (default: `http://localhost:11434`) |\n| `OLLAMA_MODEL` | Native Ollama (`--features ollama`) | Optional (default model override) |\n\n### Example Configuration\n\n```bash\n# Linux/Mac\nexport ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY_HERE\"\nexport OPENAI_API_KEY=\"sk-YOUR_OPENAI_KEY\"\n\n# Windows PowerShell\n$env:ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY_HERE\"\n$env:OPENAI_API_KEY=\"sk-YOUR_OPENAI_KEY\"\n```\n\n### Local LLMs (No API Key Required)\n\nYou can also use Crustly with **local LLMs** for 100% private, cost-free operation:\n- **LM Studio** - Desktop app with OpenAI-compatible API ✅ **Ready to use!**\n- **Ollama** - Command-line local model runner ✅ **Ready to use!**\n- **LocalAI** - Self-hosted OpenAI alternative ✅ **Ready to use!**\n\n**Quick Start with LM Studio:**\n```bash\n# 1. Start LM Studio with a model loaded\n# 2. Set environment variable\nexport OPENAI_BASE_URL=\"http://localhost:1234/v1\"\n\n# 3. Run Crustly\ncargo run\n```\n\nSee [LM_STUDIO_GUIDE.md](docs/guides/LM_STUDIO_GUIDE.md) for complete setup instructions.\n\n---\n\n## 🧩 Reference Coding Models & Hardware Requirements\n\nThree models cover the three roles a coding agent needs — writing code, planning/reasoning, and reviewing/documenting — and are Crustly's current reference points for each:\n\n| Model | Role | Params | Context (Crustly) | Provider | Serving |\n|---|---|---|---|---|---|\n| **[Qwen3-Coder-Next](https://huggingface.co/Qwen/Qwen3-Coder-Next)** ⭐ | Primary coding agent | 80B MoE (~3B active/token) | 256K | `providers.qwen` (local) | vLLM / SGLang |\n| **Qwen3.6-27B** | Reasoning & planning | 27B dense | 256K (open-weight); cloud releases may support up to 1M | `providers.qwen` (local or DashScope) | vLLM / SGLang / DashScope |\n| **Gemma 4 26B** (`gemma-4-26b-a4b-it`) | Architecture, docs, review | 25.2B MoE (~3.8B active/token) | 128K via Gemini API; up to 256K on the Ollama-hosted GGUF | `providers.gemini` (free) or native Ollama | Gemini API or Ollama |\n\nAll three are wired up in Crustly's provider layer today: `qwen3-coder-next` and `qwen3.6-27b` are registered in the Qwen provider with their real 256K context window, and the provider auto-selects the OpenAI tool-call parser for Qwen3-Coder-Next to match its documented vLLM/SGLang serving recipe. Gemma 4 26B is served through the Gemini provider free of charge, or locally via `ollama pull gemma4:26b`. See [QWEN_INTEGRATION.md](docs/guides/QWEN_INTEGRATION.md) for Qwen setup/config and [LM_STUDIO_GUIDE.md](docs/guides/LM_STUDIO_GUIDE.md#gemma-4-google) for the Gemma 4 hardware breakdown.\n\n### Hardware requirements\n\n> Figures below are estimated from published parameter counts using standard quantization overhead (~0.55–0.6 bytes/param at Q4/INT4, 2 bytes/param at BF16/FP16) — the same method used elsewhere in this README and in [LM_STUDIO_GUIDE.md](docs/guides/LM_STUDIO_GUIDE.md). Check each model's card for vendor-confirmed numbers before provisioning production hardware.\n\n#### Qwen3-Coder-Next (80B MoE, ~3B active/token)\n\nDesigned for datacenter/workstation vLLM or SGLang serving rather than a single consumer GPU — the full expert set must be resident for production-grade throughput.\n\n| Deployment | VRAM | System RAM | Notes |\n|---|---|---|---|\n| **BF16/FP16 (vLLM/SGLang default)** | ~160 GB | 32 GB+ | Needs multi-GPU, e.g. 2× A100/H100 80GB, or split across 4× 48GB workstation GPUs with tensor parallelism |\n| **AWQ/GPTQ INT4 (vLLM quantized)** | ~45–50 GB | 32 GB+ | Fits a single 80GB A100/H100, or 2× 24GB consumer GPUs (e.g. RTX 4090) with tensor parallelism |\n| Disk | ~45 GB (INT4) – ~160 GB (BF16 safetensors) | — | — |\n\n```bash\nvllm serve Qwen/Qwen3-Coder-Next \\\n    --enable-auto-tool-choice \\\n    --tool-call-parser qwen3_coder\n```\n\nNo local GPU? Use DashScope cloud instead (`api_key` + `region` under `[providers.qwen]` — see [QWEN_INTEGRATION.md](docs/guides/QWEN_INTEGRATION.md)) once Qwen3-Coder-Next is available there.\n\n#### Qwen3.6-27B (27B dense)\n\nComparable footprint to other 27B-class dense models already in this README (Gemma-3-27B-IT, Qwen2.5-Coder-32B).\n\n| Deployment | VRAM | System RAM | Notes |\n|---|---|---|---|\n| **Q4_K_M (GGUF via Ollama/LM Studio)** | ~20 GB | 40 GB | Best speed/quality balance for local use |\n| **BF16/FP16 (vLLM/SGLang)** | ~54 GB | 32 GB+ | Fits a single 80GB A100/H100 |\n| Cloud (DashScope) | none | none | Recommended default for the reasoning/planning tier if you don't have a spare GPU |\n\n#### Gemma 4 26B (25.2B MoE, ~3.8B active/token)\n\n| Deployment | VRAM | System RAM | Notes |\n|---|---|---|---|\n| **Gemini API** (`providers.gemini`) | none | none | Free of charge, 128K context, no GPU or Ollama required — recommended default |\n| **Ollama** (`ollama pull gemma4:26b`, Q4_K_M) | ~12 GB | 32 GB | Up to 256K context locally; see the exact config snippet in [LM_STUDIO_GUIDE.md](docs/guides/LM_STUDIO_GUIDE.md#gemma-4-google) |\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Rust 1.75+** - [Install Rust](https://rustup.rs/)\n- **API Key** from your preferred provider (see Supported AI Providers above)\n- **SQLite** (bundled with sqlx)\n- **Git** (optional)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/jyjeanne/crustly.git\ncd crustly\n\n# Build the project\ncargo build --release\n\n# Set your API key (choose your preferred provider)\nexport ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY_HERE\"\n# or\nexport OPENAI_API_KEY=\"sk-YOUR_OPENAI_KEY\"\n# See \"Supported AI Providers\" section for all options\n\n# Initialize configuration (optional)\ncargo run -- init\n\n# Run interactive mode\ncargo run\n```\n\n### First Run\n\n1. **Set your API key** (choose your preferred provider):\n\n**Option A: Secure OS Keyring (Recommended)**\n```bash\n# Store API key securely in OS credential manager\ncargo run -- keyring set anthropic YOUR_API_KEY_HERE\n# or\ncargo run -- keyring set openai YOUR_API_KEY_HERE\n\n# List stored keys\ncargo run -- keyring list\n\n# View stored key (displays in terminal)\ncargo run -- keyring get anthropic\n```\n\nBenefits:\n- ✅ Encrypted by OS (Windows Credential Manager / macOS Keychain / Linux Secret Service)\n- ✅ Not stored in plaintext files\n- ✅ Automatically loaded on startup\n- ✅ Secure and persistent\n\n**Option B: Environment Variables (Temporary)**\n```bash\n# Example with Anthropic (Linux/Mac)\nexport ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY_HERE\"\n\n# Example with OpenAI (Linux/Mac)\nexport OPENAI_API_KEY=\"sk-YOUR_OPENAI_KEY\"\n\n# Windows PowerShell\n$env:ANTHROPIC_API_KEY=\"sk-ant-api03-YOUR_KEY_HERE\"\n# or\n$env:OPENAI_API_KEY=\"sk-YOUR_OPENAI_KEY\"\n```\n\n> 💡 Crustly automatically tries keyring first, then falls back to environment variables.\n> 💡 See the **Supported AI Providers** section above for the complete list of environment variables.\n\n2. **Launch the TUI:**\n```bash\ncargo run\n```\n\n3. **Start chatting:**\n   - Type your message\n   - Press `Enter` to send (`Shift+Enter`/`Alt+Enter` for a new line,\n     `Ctrl+Enter` still works too)\n   - Press `Ctrl+H` to see all available commands and help\n   - Press `Ctrl+C` to quit\n\n> 💡 **Tip:** Press `Ctrl+H` at any time to display the comprehensive help screen with all keyboard shortcuts and features!\n\n### Usage\n\n```bash\n# Interactive TUI mode (default)\ncargo run\n# or\ncargo run -- chat\n\n# Non-interactive mode (single command)\ncargo run -- run \"What is Rust?\"\n\n# With JSON output\ncargo run -- run --format json \"List 3 programming languages\"\n\n# With markdown output\ncargo run -- run --format markdown \"Explain async/await\"\n\n# Initialize configuration\ncargo run -- init\n\n# Show current configuration\ncargo run -- config\n\n# Show configuration with secrets\ncargo run -- config --show-secrets\n\n# Initialize database\ncargo run -- db init\n\n# Show database statistics\ncargo run -- db stats\n\n# Enable debug mode (creates log files)\ncargo run -- -d\n# or\ncargo run -- --debug\n\n# Log management commands\ncargo run -- logs status    # Check logging status\ncargo run -- logs view      # View recent logs\ncargo run -- logs clean     # Clean old log files\n```\n\n---\n\n## 📋 A Note on Claude Max and GitHub Copilot\n\n**Crustly only supports model providers through official, compliant APIs.**\n\nWe do not support or endorse any methods that rely on personal Claude Max and GitHub Copilot accounts or OAuth workarounds, which violate Anthropic and Microsoft's Terms of Service.\n\n### Official API Access Only\n\n✅ **Supported & Compliant:**\n- Anthropic API (with official API key from console.anthropic.com)\n- OpenAI API (with official API key)\n- Local LLMs (LM Studio, Ollama, LocalAI)\n- Any OpenAI-compatible API endpoint with proper authorization\n\n❌ **Not Supported & Against ToS:**\n- Using Claude Max subscription through unofficial methods\n- Using GitHub Copilot through OAuth workarounds\n- Reverse-engineered or unofficial API endpoints\n- Account-sharing or credential-borrowing schemes\n\n### Why This Matters\n\n- **Legal Compliance** - Using unofficial methods violates provider Terms of Service\n- **Account Safety** - Your accounts could be suspended or banned\n- **Security Risks** - Unofficial methods may expose your credentials\n- **Ethical Development** - We respect provider agreements and policies\n\n### Recommended Alternatives\n\nIf you can't afford cloud API costs, consider these legitimate alternatives:\n1. **Local LLMs** - Run models on your own hardware (see section below)\n2. **API Credits** - Many providers offer free trial credits\n3. **Educational Programs** - Some providers offer discounts for students/researchers\n\n---\n\n## 🏠 Running Crustly with Local LLMs\n\nCrustly runs entirely offline for 100% private, $0-cost inference, via\nthree different paths — two against a local model server, one with no\nserver at all. Full step-by-step setup, troubleshooting, and model\nrecommendations now live in dedicated guides:\n\n### LM Studio\nDesktop app with a built-in model downloader and an OpenAI-compatible local\nserver. Recommended if you want a GUI for browsing and swapping models.\nSee **[docs/guides/LM_STUDIO_GUIDE.md](docs/guides/LM_STUDIO_GUIDE.md)** for\ninstallation, model recommendations (Qwen2.5-Coder, Gemma 4, Llama, Ornith\n9B), troubleshooting, and performance benchmarks.\n\n### Ollama\nLightweight background service with short, memorable model names — the\nrecommended local backend since it needs no GUI and reconnects instantly.\nSee **[docs/guides/OLLAMA_GUIDE.md](docs/guides/OLLAMA_GUIDE.md)** for\ninstallation, model pulls, multi-model workflows, and troubleshooting.\n\n### llama.cpp (no server, in-process)\nSkips the server entirely: loads a `.gguf` file directly into the Crustly\nprocess itself via the `llama-cpp-2` crate — no daemon to install or keep\nrunning, at the cost of a from-source build (`--features llama-cpp`,\ncompiles native C++) and a slower model-switch than Ollama's near-instant\nswap. See **[docs/guides/LLAMA_CPP_GUIDE.md](docs/guides/LLAMA_CPP_GUIDE.md)**\nfor build requirements, getting a model, GPU acceleration, and\ntroubleshooting — and\n**[llama-cpp-2-integration-plan.md](llama-cpp-2-integration-plan.md)** for\nthe full technical design.\n\n### Configuring `crustly.toml`\nAll three routes are configured the same way, through `crustly.toml` or\nenvironment variables. See\n**[docs/guides/CONFIGURATION_GUIDE.md](docs/guides/CONFIGURATION_GUIDE.md)**\nfor the full option reference, file locations per OS, and example configs for\nLM Studio, Ollama, cloud APIs, and hybrid setups.\n\n---\n\n## 💡 Best Practices for Using Crustly\n\nEffective prompts are specific, reference real files/functions, and state the\ndesired outcome — Crustly's tools do the exploration for you. See\n**[docs/guides/PROMPT_BEST_PRACTICES.md](docs/guides/PROMPT_BEST_PRACTICES.md)**\nfor sample prompts by task type (codebase exploration, debugging, feature\nimplementation, documentation, dependency analysis), patterns to avoid, and a\nfull example workflow session.\n\n---\n\n## 👨‍💻 Why Crustly for Coding?\n\nA closer look at the coding-specific feature set — tool execution, syntax\nhighlighting, session context, streaming, cost tracking — plus common coding\ntask walkthroughs, a typical developer workflow, and a comparison with other\nterminal coding assistants. See\n**[docs/CODING_FEATURES.md](docs/CODING_FEATURES.md)** for the full writeup.\n\n---\n\n## 📋 Plan Mode — Structured Task Planning\n\nFor complex, multi-step work, ask Crustly to plan first: it breaks the task\ninto a reviewable, dependency-ordered set of steps you approve before\nanything executes. See **[docs/PLAN_MODE_USER_GUIDE.md](docs/PLAN_MODE_USER_GUIDE.md)**\nfor the full workflow, keyboard shortcuts, `PLAN.md` format, plan lifecycle,\nsample prompts, troubleshooting, and FAQ.\n\n---\n\n## 🧠 Native Skills — /review & /spec\n\nSkills are `SKILL.md` prompt files the `skill` tool can load — Crustly\nships two built into the binary so they work in any project with no setup,\nand any project can override either by dropping its own\n`.crustly/skills/<name>/SKILL.md` (or `.claude/skills/<name>/SKILL.md`)\nof the same name.\n\n### `/review` — multi-pass code review\n\n```\n/review                  # review the current diff / open PR\n/review 123               # review PR #123\n/review --comment         # also post a summary comment via gh\n/review --fix             # apply the surviving findings\n```\n\nIndependent correctness, guideline-compliance, and security passes\ndispatch in parallel via the `agent` tool, each scoped to only the\nrelevant diff and context. A second, skeptical pass then tries to\ndisprove each finding before it's reported — findings that don't survive\nscrutiny are dropped rather than shown, on the theory that a review that\ncries wolf gets ignored.\n\n### `/spec` — Specification-Driven Development\n\n```\n/spec Add CSV export to reports   # start a new feature: specs/001-.../spec.md\n/spec plan                        # architecture plan + constitution gate\n/spec tasks                       # phased, traceable task breakdown\n/spec implement                   # builds it natively, checks off tasks.md\n/spec analyze                     # traceability + test verdict: READY / NEEDS WORK\n```\n\nOne skill, phase inferred from the trailing argument. Every feature gets\na versioned `spec.md` → `plan.md` → `tasks.md` under `specs/<NNN>-<slug>/`,\nso scope and requirements survive contact with an AI agent instead of\nbeing renegotiated silently mid-implementation.\n\nThe workflow is modeled on the `spec-driven` schema from the same\nauthor's [rustyspec](https://github.com/jyjeanne/rustyspec) and\n[solidspec](https://github.com/jyjeanne/solidspec) — external CLI tools\nimplementing several SDD methodologies, of which `spec-driven` is\ndocumented as the polyvalent default. The key difference here: those\ntools are separate processes that must shell out to an external agent's\nCLI for the `implement` phase. Crustly doesn't need to — `implement` runs\nnatively in the same session, driving `task_manager`, `write_file`,\n`edit_file`, and `bash` directly against `tasks.md`.\n\n### Writing your own\n\nAny `.crustly/skills/<name>/SKILL.md` in your project (or\n`~/.config/crustly/skills/<name>/SKILL.md` globally) becomes a slash\ncommand automatically — no registration step. Run `/skills` to see every\nskill currently discoverable, project-local and built-in alike.\n\n---\n\n## 🧪 Manual Testing Guide\n\nFor a hands-on pass covering setup verification, interactive chat, session\nmanagement, cost tracking, multi-turn context, and configuration management,\nsee **[docs/guides/MANUAL_TESTING_GUIDE.md](docs/guides/MANUAL_TESTING_GUIDE.md)**.\n\n---\n\n## 📊 Performance\n\n### Test Suite Performance\n\n| Test Suite | Tests | Time | Status |\n|------------|-------|------|--------|\n| Unit Tests | 163 | ~2.3s | ✅ |\n| Integration Tests | 9 | ~0.1s | ✅ |\n| **Total** | **172** | **~2.4s** | **✅** |\n\n### Database Operations\n\n| Operation | Time | Notes |\n|-----------|------|-------|\n| Session creation | < 10ms | In-memory SQLite |\n| Message insert | < 5ms | With token tracking |\n| Message list query | < 20ms | Per session |\n| Session list query | < 30ms | All sessions |\n\n### Application Performance\n\n| Metric | Current | Target | Status |\n|--------|---------|--------|--------|\n| Test Execution | ~2.7s | < 5s | ✅ |\n| Startup Time | TBD | < 50ms | 📊 Needs benchmarking |\n| Memory Usage (idle) | ~15MB | < 25MB | ✅ |\n| Memory Usage (100 msgs) | ~20MB | < 50MB | ✅ |\n\n---\n\n## 🏗️ Architecture\n\n```\nPresentation Layer\n    ↓\nCLI (Clap) + TUI (Ratatui)\n    ↓\nApplication Layer\n    ↓\nService Layer (Session, Message, Agent)\n    ↓\nData Access Layer (SQLx + SQLite)\n    ↓\nIntegration Layer (LLM, LSP, MCP)\n```\n\n**Key Technologies:**\n- **Tokio** - Async runtime\n- **Axum** - HTTP server (future)\n- **Ratatui** - Terminal UI\n- **SQLx** - Database access\n- **Clap** - CLI parsing\n- **Tower-LSP** - LSP client\n- **Crabrace** - Provider registry\n\n---\n\n## 📁 Project Structure\n\n```\ncrustly/\n├── src/\n│   ├── cli/           # Command-line interface\n│   ├── app/           # Application lifecycle\n│   ├── config/        # Configuration management\n│   │   └── crabrace.rs # Crabrace integration ✅\n│   ├── db/            # Database layer (SQLx)\n│   ├── services/      # Business logic\n│   ├── llm/           # LLM integration\n│   │   ├── agent/     # Agent service\n│   │   ├── provider/  # LLM providers\n│   │   ├── tools/     # Tool system\n│   │   └── prompt/    # Prompt engineering\n│   ├── tui/           # Terminal UI\n│   ├── lsp/           # LSP integration\n│   ├── mcp/           # MCP support\n│   └── utils/         # Utilities\n├── tests/             # Integration tests\n├── benches/           # Benchmarks\n└── docs/              # Documentation\n```\n\n---\n\n## 🔍 Debug and Logging\n\nCrustly is silent by default — no log files are created during normal use.\nPass `-d`/`--debug` to enable verbose logging to `.crustly/logs/` (daily\nrotation, 7-day auto-cleanup), and use `crustly logs status|view|clean|open`\nto manage them. See **[docs/guides/DEBUG_LOGGING.md](docs/guides/DEBUG_LOGGING.md)**\nfor log levels, file format, environment variable overrides, and\ntroubleshooting.\n\n---\n\n## 🛠️ Development\n\n### Build from Source\n\n```bash\n# Development build\ncargo build\n\n# Release build (optimized)\ncargo build --release\n\n# With profiling\ncargo build --release --features profiling\n\n# Run tests\ncargo test\n\n# Run benchmarks\ncargo bench\n\n# Format code\ncargo fmt\n\n# Lint\ncargo clippy -- -D warnings\n```\n\nFor the forward-looking plan (what's shipped, what's next, target\nmilestones), see **[ROADMAP.md](ROADMAP.md)**.\n\n---\n\n## 📖 Documentation\n\n### Guides\n- **[LM Studio Guide](docs/guides/LM_STUDIO_GUIDE.md)** - Local LLM setup, model recommendations, troubleshooting\n- **[Ollama Guide](docs/guides/OLLAMA_GUIDE.md)** - Native Ollama setup, model management, troubleshooting\n- **[Configuration Guide](docs/guides/CONFIGURATION_GUIDE.md)** - `crustly.toml` reference and example configs\n- **[Prompting Best Practices](docs/guides/PROMPT_BEST_PRACTICES.md)** - Effective prompt patterns\n- **[Plan Mode User Guide](docs/PLAN_MODE_USER_GUIDE.md)** - Structured task planning workflow\n- **[Manual Testing Guide](docs/guides/MANUAL_TESTING_GUIDE.md)** - Step-by-step testing instructions\n- **[Debug & Logging](docs/guides/DEBUG_LOGGING.md)** - Log levels, file locations, troubleshooting\n- **[Coding Features](docs/CODING_FEATURES.md)** - Coding-specific feature deep dive\n- **[User Guide](docs/guides/README_USER_GUIDE.md)** - Complete user guide with examples\n\n### Project\n- **[CHANGELOG.md](CHANGELOG.md)** - Full version history\n- **[ROADMAP.md](ROADMAP.md)** - Completed milestones and forward-looking plan\n- **[Architecture](docs/ARCHITECTURE.md)** - Full architecture reference\n- **[Project History](docs/PROJECT_HISTORY.md)** - Archived pre-1.0 sprint log (historical, not current)\n\n### Development Documentation\n- **[Testing Summary](docs/development/TESTING_SUMMARY.md)** - Test coverage and infrastructure\n- **[Technical Specification](docs/CRUSTLY_SPECIFICATION_FINAL.md)** - Complete spec (v3.0)\n- **[Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md)** - Development roadmap\n- **[Crabrace Integration](docs/guides/CRABRACE_INTEGRATION.md)** - Provider registry guide\n- **[Build Notes](docs/guides/BUILD_NOTES.md)** - Build instructions & known issues\n- **[Specification Review](docs/SPECIFICATION_REVIEW.md)** - Feature analysis\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n1. Install Rust 1.75+\n2. Clone the repository\n3. Run `cargo build`\n4. Make changes\n5. Run tests: `cargo test`\n6. Submit PR\n\n---\n\n## 🐛 Known Issues & Platform-Specific Notes\n\n### Windows Build Requirements\n\nBuilding Crustly on Windows requires additional tools due to native dependencies:\n\n**Error you might see:**\n```\nerror: failed to run custom build command for `aws-lc-sys`\nerror: Error calling dlltool 'dlltool.exe': program not found\n```\n\n**Root Cause:**\nThe `aws-lc-sys` crate (used by cryptographic libraries) requires CMake and NASM for Windows builds.\n\n**Solutions (choose one):**\n\n**Option 1: Install Build Tools (Recommended for Windows development)**\n1. Install [CMake](https://cmake.org/download/) (Windows x64 Installer)\n   - During installation, choose \"Add CMake to the system PATH\"\n2. Install [NASM](https://www.nasm.us/)\n   - Download Windows 64-bit installer\n   - Add to PATH: `C:\\Program Files\\NASM`\n3. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)\n   - Select \"Desktop development with C++\"\n4. Restart terminal and run: `cargo build`\n\n**Option 2: Use WSL2 (Recommended for Linux-like environment)**\n```bash\n# In WSL2 Ubuntu\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsudo apt-get update\nsudo apt-get install build-essential pkg-config libssl-dev\ngit clone https://github.com/jyjeanne/crustly.git\ncd crustly\ncargo build --release\n```\n\n**Option 3: Use Pre-built Binaries (Coming Soon)**\n- Download from [Releases](https://github.com/jyjeanne/crustly/releases)\n\n**Platform-specific notes:**\n- **macOS**: No additional dependencies required\n- **Linux**: Requires `build-essential`, `pkg-config`, `libssl-dev`\n- **Windows**: See build requirements above\n\nFor detailed build troubleshooting, see [BUILD_NOTES.md](docs/guides/BUILD_NOTES.md).\n\n---\n\n## 📄 License\n\n**FSL-1.1-MIT License**\n\n- **Functional Source License (FSL) 1.1** - First 2 years\n- **MIT License** - After 2 years from release\n\nSee [LICENSE.md](LICENSE.md) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **Crush (Go)** - Original implementation\n- **Crabrace** - Provider registry (Rust port of Catwalk)\n- **Anthropic** - API\n- **Ratatui Community** - Terminal UI framework\n\n---\n\n## 📞 Support\n\n- **Issues:** [GitHub Issues](https://github.com/jyjeanne/crustly/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/jyjeanne/crustly/discussions)\n- **Documentation:** [docs/](docs/)\n\n---\n\n## 📈 Status\n\nCrustly is under active development — see the **[✨ What's New](#-whats-new)**\nsection above and **[CHANGELOG.md](CHANGELOG.md)** for the current feature\nset, and **[ROADMAP.md](ROADMAP.md)** for what's shipped vs. planned. The\nSprint 0-12 development log from the pre-1.0 bring-up phase is archived at\n**[docs/PROJECT_HISTORY.md](docs/PROJECT_HISTORY.md)** for reference.\n\n---\n\n**Built with** ❤️ **and Rust 🦀**\n\n**\"Why 'Crustly'?\"** 🥐\nLike a croissant's flaky layers, Crustly has a layered architecture.\nCrusty on the outside (fast), soft on the inside (approachable).\n",
  "bytes": 52018,
  "sha": "ed4fc3f9565625a49dfe8d3e58d9814c3c7563d63f8e4eba794f86d760b9c7e5",
  "repo_slug": "jyjeanne/crustly",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jyjeanne_crustly_knowledge_index_md_b943006a/readme"
}