PHPackages sugarcraft/sugar-crush - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. sugarcraft/sugar-crush ActiveProject[Utility & Helpers](/categories/utility) sugarcraft/sugar-crush ====================== Chat-shell TUI for AI coding assistants — port of charmbracelet/crush. Pluggable Backend interface (ship your own Anthropic / OpenAI / Ollama / shell-out adapter). Markdown rendering of replies via CandyShine, scrollback viewport via SugarBits, input area via SugarBits TextArea. 10PHP Since Jun 29Pushed 1mo agoCompare [ Source](https://github.com/sugarcraft/sugar-crush)[ Packagist](https://packagist.org/packages/sugarcraft/sugar-crush)[ RSS](/packages/sugarcraft-sugar-crush/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependenciesVersions (1)Used By (0) [![sugar-crush](.assets/icon.png)](.assets/icon.png) SugarCrush ========== [](#sugarcrush) [![CI](https://github.com/detain/sugarcraft/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/db5b1b61b6910e745faa30f11744269eb9f352666150d7b523fd0f4835f9b5ea/68747470733a2f2f636f6465636f762e696f2f67682f64657461696e2f737567617263726166742f6272616e63682f6d61737465722f67726170682f62616467652e7376673f666c61673d73756761722d6372757368)](https://app.codecov.io/gh/detain/sugarcraft?flags%5B0%5D=sugar-crush)[![Packagist Version](https://camo.githubusercontent.com/c6e4c63d3d204313d76c64deed51dc1a40feb277ddb157e98df9e3efa4c1e4d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737567617263726166742f73756761722d63727573683f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/sugarcraft/sugar-crush)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/fd3accad83cd317a9843432403191b4e555c55d57d63e10897f3f1dff5ed169e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135382e332d3838393262662e737667)](https://www.php.net/) [![demo](.vhs/chat.gif)](.vhs/chat.gif) A terminal AI coding agent — PHP port of [`charmbracelet/crush`](https://github.com/charmbracelet/crush). It is a candy-core TEA program (a real `Model`/`Program` render loop with buffer-diffed output and Markdown-rendered replies) wrapped around a full agent engine: **multiple LLM providers**, model-driven **tool calling** gated by **hooks**, prompt-injecting **skills**, **sub-agents**, an **MCP** client/server, and **SQLite** session history. ``` ┌─ SugarCrush ───────────────────────────────────────┐ │ user> add a test for the Width helper │ │ │ │ assistant │ │ I'll read the helper first, then write the test. │ │ ⚙ Read src/Util/Width.php │ │ ⚙ Edit tests/Util/WidthTest.php │ │ Done — added 4 cases covering the clamp edges. │ └────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────┐ │ > run them█ │ └────────────────────────────────────────────────────┘ Enter to send · Esc / ^C to quit ``` > **History:** SugarCrush absorbed the former experimental `candy-crush` port. There is now a single `SugarCraft\Crush` library. Run it ------ [](#run-it) ``` composer install ./bin/sugarcrush ``` With no configuration the binary runs the **offline `EchoProvider`** through the full engine, so it launches with zero network and zero keys. Point it at a real model with environment variables: ``` # OpenAI export SUGARCRUSH_PROVIDER=openai export OPENAI_API_KEY=sk-... export SUGARCRUSH_MODEL=gpt-4o # optional; provider default otherwise ./bin/sugarcrush ``` `SUGARCRUSH_PROVIDER` accepts `openai`, `anthropic`, `claude-code`, `sglang`, `bedrock`, `vertex`, or `custom`. Each reads its own credentials from the environment (e.g. `ANTHROPIC_API_KEY`, AWS ambient creds for Bedrock, `GOOGLE_APPLICATION_CREDENTIALS` for Vertex). When a real provider is active, the binary wires the built-in coding tools (Bash/Read/Edit/Glob/Grep/WebFetch) and the safety hooks automatically. ### Dependency-free shell-out [](#dependency-free-shell-out) To avoid PHP SDKs entirely, set `SUGARCRUSH_BACKEND_CMD` to a command that reads JSON history on stdin and writes the reply to stdout: ``` export SUGARCRUSH_BACKEND_CMD=~/bin/anthropic.sh ./bin/sugarcrush ``` ``` #!/usr/bin/env bash # ~/bin/anthropic.sh — keeps PHP network-dep-free, swap models by editing this file payload=$(jq -nc --argjson h "$(cat)" '{model:"claude-opus-4-8", max_tokens:4096, messages:$h}') curl -sN https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" -d "$payload" | jq -r '.content[0].text' ``` Providers --------- [](#providers) `SugarCraft\Crush\Providers\ProviderInterface` is the single LLM abstraction (capability introspection, batch + `\Generator` streaming, function calling, embeddings, per-model cost). Build one directly or from config via `ProviderFactory` (which resolves `${VAR}` / `${VAR:-default}` from the environment): ``` use SugarCraft\Crush\Providers\ProviderFactory; $factory = new ProviderFactory(); $provider = $factory->create(['type' => 'openai', 'apiKey' => '${OPENAI_API_KEY}', 'model' => 'gpt-4o']); ``` ProviderType keyNotesOpenAI`openai``openai-php/client`; function calling, embeddings, cost tableAnthropic`anthropic`real Messages API (`/v1/messages`, `x-api-key`)Claude Code CLI`claude-code`drives the `claude` binary headless; native cost; JSON schemaSGLang`sglang`OpenAI-compatible self-hosted endpoints (Guzzle)AWS Bedrock`bedrock`Converse API via `aws/aws-sdk-php`; per-model pricingGCP Vertex`vertex`Anthropic-on-Vertex via an injectable predictor seamCustom`custom`any OpenAI-compatible HTTP endpointEcho—`EchoProvider`: offline, echoes the last turn; default + testsThe agent loop -------------- [](#the-agent-loop) `EngineBackend` bridges the chat-shell `Backend` seam to the engine. Each user turn runs a **bounded agentic loop**: call the provider through the `Runtime`, execute any tool calls through the hook gate, feed the results back, and repeat until the model answers without calling tools — or a `maxSteps` ceiling is hit. ``` use SugarCraft\Crush\Backend\EngineBackend; use SugarCraft\Crush\Hooks\{HookManager, HookRegistry}; use SugarCraft\Crush\Tools\BuiltIn\{Bash, Read, Edit, Glob, Grep, WebFetch}; $hooks = new HookManager(new HookRegistry()); $hooks->registerBuiltIns(); // audit + confirm-rm + protect-files $backend = (EngineBackend::new($provider, 'gpt-4o')) ->withTools([new Bash(), new Read(), new Edit(), new Glob(), new Grep(), new WebFetch()]) ->withHooks($hooks); (new Program(new Chat(backend: $backend)))->run(); ``` Capabilities ------------ [](#capabilities) - **Tools** — `Tools\BuiltIn\*`: `Bash`, `Read`, `Edit`, `Glob`, `Grep`, `WebFetch`. Implement `Tools\Tool` for your own. - **Hooks** — `Hooks\*`: pre/post-tool-use guards (allow / deny / **modify** the input). Built-ins: `AuditHook`, `ConfirmRemoveHook`, `ProtectFilesHook`. YAML config and external `ScriptHook` supported. - **Skills** — `Skills\*`: frontmatter `SKILL.md` files inject prompt context, matched by keyword/path. Discovered from built-ins, `~/.sugar-crush/skills`, and `/.sugar-crush/skills` (project wins). Ships php-best-practices, security-audit, phpunit-master, composer-wizard. - **Agents** — `Agents\*`: 6 sub-agent presets (coder/reviewer/debugger/architect/tester/devops) with their own model, tools, skills, and a streaming lifecycle. - **MCP** — `MCP\*`: multi-server client (stdio + HTTP, `.mcp.json`, `${VAR}` interpolation) and stdio/HTTP servers to host your own tools. - **Sessions** — `Session\SessionStore`: SQLite (WAL) persistence of sessions/messages/tool-calls with FK-enforced cascade and age-based pruning. - **Tokens & export** — `Util\TokenTracker` (token + cost accumulation) and `Util\Exporter` (Markdown / JSON / text transcripts). - **Messages** — typed `Messages\{System,User,Assistant,ToolResult}Message`; `UserMessage` carries file/image attachments; `AssistantMessage` carries tool calls + reasoning. Architecture ------------ [](#architecture) SugarCrush keeps the proven sugar-crush **chassis** (the `Chat` candy-core `Model`, buffer-diff `Renderer`, `bin/sugarcrush`) and runs the ported **engine** behind it: ``` bin/sugarcrush └─ Program → Chat (Model: input, scrollback, inFlight gate, buffer-diff view) └─ Backend ── EchoBackend / CommandBackend (simple) └─ EngineBackend (agent loop) └─ Runtime → ProviderInterface (+ Tools · Hooks · Skills via App) ``` The chassis speaks the root `Message` value object; the engine speaks the typed `Messages\*` hierarchy; `EngineBackend` converts at the seam. Custom provider --------------- [](#custom-provider) ``` use SugarCraft\Crush\Providers\{ProviderInterface, CompleteRequest, CompleteResponse, EmbeddingsRequest, EmbeddingsResponse}; final class MyProvider implements ProviderInterface { public function name(): string { return 'mine'; } public function supportsStreaming(): bool { return false; } public function supportsFunctionCalling(): bool { return true; } public function supportsVision(): bool { return false; } public function supportsJsonSchema(): bool { return false; } public function contextWindow(): int { return 128_000; } public function costPer1kTokens(string $model, string $direction): float { return 0.0; } public function complete(CompleteRequest $r): CompleteResponse { /* ... */ } public function completeStream(CompleteRequest $r): \Generator { /* yield CompleteResponse chunks */ } public function embeddings(EmbeddingsRequest $r): EmbeddingsResponse { /* ... */ } } ``` Tests ----- [](#tests) ``` cd sugar-crush && composer install && vendor/bin/phpunit ``` 1,239 tests / 2,924 assertions. Coverage spans every subsystem: typed messages + attachments, the 6 built-in tools, all 7 providers (unit-tested with mocked transports — no live calls), the hook framework, skills discovery, sub-agents, the MCP client/servers, the SQLite store, token tracking, export, the TUI components, the `Runtime` orchestration (streaming accumulation, tool-result correlation, MODIFY hooks), and the `EngineBackend` agentic loop (incl. the `maxSteps` guard). ### Health Score 20 — LowBetter than 12% of packages Maintenance59 Moderate activity, may be stable Popularity2 Limited adoption so far Community8 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 98.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain) --- Top Contributors [![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (90 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags agenticai-assistantanthropiccandycorechat-uichatbotcli-chatcrushcrush-portlanguage-modelllmmarkdown-chatollamaopenairead-eval-printshellstreamingtuiturnkeywrapper-script ### Embed Badge ![Health badge](/badges/sugarcraft-sugar-crush/health.svg) ``` [![Health](https://phpackages.com/badges/sugarcraft-sugar-crush/health.svg)](https://phpackages.com/packages/sugarcraft-sugar-crush) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)