A coding agent for your terminal, built on .NET and Crystal.
Crystal Code works in a local repository through a streaming terminal UI. Ask it to inspect code, plan a change, or edit files. Plan, Work, and custom modes, tool approvals, and workspace boundaries keep you in control of what it can do.
Official site · Get started · Features · Command line · Configuration · User guide
- 🖥️ Stay in the terminal. Follow streamed responses and tool calls, edit a multiline prompt, and queue follow-up requests while a turn runs.
- 🎛️ Choose how work happens. Plan mode offers built-in reading and planning tools; Work mode also enables file edits and shell commands. Tool calls follow a risk-aware approval policy.
- 🧵 Keep a conversation going. Resume or fork saved sessions, switch models with
/model, and compact older context automatically or with/compact. - 🔌 Use the model endpoints you prefer. Built-in DeepSeek, OpenAI, Gemini, and Ollama providers are available, and you can configure OpenAI-compatible Chat Completions, OpenAI Responses, and Anthropic Messages (Claude) endpoints.
- 🧩 Extend the workflow. Load skills and operator tool sets from your home directory or workspace. Image-capable models can receive workspace or clipboard images.
- 👥 Delegate inside the session. When child Agents are enabled, the model can hand a bounded task to
general, read-onlyexplore, or Work-onlywork. They are off by default./agentsconfigures them;/childor F7 inspects one.
Crystal Code is the coding product built on the sibling Crystal library. The terminal is its operator surface.
The self-contained release supports Linux (glibc and musl, such as Alpine) on x64 and ARM64, macOS on x64 and ARM64, and Windows on x64 and ARM64.
Linux and macOS are the recommended platforms. On Windows, install Git for Windows; its Git Bash provides the bash shell the built-in bash tool uses.
Linux or macOS
curl --fail --location --show-error \
https://raw.githubusercontent.com/YELANDAOKONG/CrystalCode/master/scripts/install.sh | shWindows PowerShell
Invoke-RestMethod `
-Uri https://raw.githubusercontent.com/YELANDAOKONG/CrystalCode/master/scripts/install.ps1 | Invoke-ExpressionThe installer places the application under ~/.crystal/binaries/code/ and adds that directory to your path. On Linux and macOS it also aliases crystal to CrystalCode; on Windows the command stays CrystalCode. Open a new terminal after installation. To inspect a script before running it, download it first and run the local copy.
Write the key in ~/.crystal/credentials.json under the provider name. For the default DeepSeek provider the file looks like:
{
"deepseek": { "apiKey": "" }
}The value is plain text. Where the operating system allows it, the file is limited to the owner.
DEEPSEEK_API_KEY, OPENAI_API_KEY, or <PROVIDER>_API_KEY overrides that file for the process that receives it. Use an environment variable for a single launch or a CI runner. See Credentials for the full lookup order.
cd /path/to/your/repository
crystalOn Windows, run CrystalCode instead of crystal. The current directory becomes the workspace. The first run creates ~/.crystal/config.json; the default selection is DeepSeek's deepseek-flash model.
Inside the app, type /help for commands and shortcuts. Use Tab to cycle modes, /plan to toggle Plan and Work, or /mode <name> to pick one (including custom modes under modes/). The interactive session guide covers the composer, image attachments, and follow-up queue.
Type these inside a running session; /help lists them all.
| Command | What it does |
|---|---|
/plan |
Switch between Plan and Work |
/mode |
List modes, or switch with /mode <name> |
/model |
List or select a configured provider and model |
/approval |
View or change the approval mode |
/attach <path> |
Attach a supported image from the workspace |
/resume |
Choose a saved session for this workspace, another directory, or every workspace |
/fork |
Branch the current conversation into a new session |
/compact |
Summarize older context now |
/agents |
List child Agents, or turn them on, set concurrency, or choose a model |
/child |
Inspect one child session, or return to the parent |
/help |
Show all commands and shortcuts |
See the complete command reference.
Run these from your shell. The interactive terminal, crystal server, and crystal bridge host a session; the others start, do their work, and exit without one:
| Command | What it does |
|---|---|
crystal server |
Serve one session over HTTP so another front end, such as a web page or a desktop program, can drive it. Prints one JSON listening line and writes ~/.crystal/server/<pid>.json. A bearer token is required by default (CRYSTAL_SERVER_TOKEN, --token-file, --token-stdin, or generated); --auth none turns it off. Accepts the same session options as crystal, plus --listen, --socket, --tls-cert/--tls-key, --allow-host, --allow-origin, --expose-header, and --allow-private-network. See docs/server.md |
crystal bridge |
Serve one session to an Agent Client Protocol (ACP) editor such as Zed, which starts it as a subprocess and speaks ACP on stdin and stdout: saved sessions with load, resume, and fork, streaming, tool calls with diffs, permission, config options, the editor's MCP servers and extra directories, forms, child Agents, compaction updates, and _crystal/* extensions for the rest of the session. Configure the editor with {"command": "crystal", "args": ["bridge"]}. Accepts the same session options as crystal, plus --workspace and --space for a session request without cwd. See docs/bridge.md |
crystal run <task> |
Run one task without a terminal and exit. Anything that would ask the operator is denied. Accepts process-only overrides such as --provider, --model, --workspace, --approval, and repeatable --prompt-attachment; they are not written to config.json |
crystal space |
Open the terminal in the operator space at ~/.crystal/space |
crystal version |
Print the build identity and exit |
crystal plugins |
List, show, enable, or disable one operator plugin outside a session |
crystal tools |
List, show, enable, or disable one operator tool set outside a session |
crystal promptsets |
List, show, enable, or disable one Home prompt set. Enabling one turns the others off |
crystal prompt-attachments |
List, show, enable, or disable one prompt attachment in Home or the workspace |
See the headless run and operator space sections of the user guide for the full option list.
Preferences and provider definitions are separate:
| File | Purpose |
|---|---|
~/.crystal/config.json |
Active provider and model, approval mode, and session preferences |
~/.crystal/providers.json |
Additional provider endpoints and model definitions |
~/.crystal/providers/ |
More provider files, optionally grouped in first-level subdirectories |
~/.crystal/credentials.json |
Plain-text API keys, one entry per provider |
~/.crystal/access.json |
Default extra directories for new sessions, per workspace |
The built-in catalog includes DeepSeek, OpenAI, Gemini, and Ollama; Anthropic Messages (Claude) is also a built-in protocol reachable by adding a provider entry. You can select any model listed in the effective catalog with /model, or use --provider and --model when starting the app. Provider configuration explains protocols, model fields, and examples.
File edits and shell commands stay within the workspace. Reads outside it require approval, and credential paths are forbidden. Approval modes explain which calls ask you, use a reviewing model, or pass automatically.
You need the .NET 10 or .NET 11 SDK and a sibling checkout of Crystal at ../Crystal.
dotnet build CrystalCode.sln
dotnet test CrystalCode.sln
dotnet run --project CrystalCode -- --provider deepseek --model deepseek-flashTo install this checkout as crystal:
sh scripts/install-local.shOn Windows:
powershell -ExecutionPolicy Bypass -File scripts/install-local.ps1The script checks for the .NET 10 or .NET 11 SDK, the sibling Crystal checkout, and the current platform, then publishes Release into build/ with the release workflow arguments (--self-contained true, -p:PublishSingleFile=true, and the matching runtime). It replaces ~/.crystal/binaries/code/ and leaves configuration, credentials, and prompts in place. The script locates the repository from its own path.
Run dotnet build, dotnet test, and dotnet run from the Crystal Code repository root. To work on a different repository, add --workspace <path> after the final -- in the dotnet run command. A TTY is required for the interactive UI, and bash must be on the path (Git Bash is used on Windows when available).
Maintainers can write a commit message and commit the current change with commit.sh. It runs crystal run in this repository. Extra arguments are appended to the task. The run skips external tools and the directory trust check, and it does not record the directory as trusted.
Branch roles: master is the main development branch. release is the release branch; a push to it runs the release workflow, which builds and publishes the release artifacts. test is used to trigger the test workflow; a push to it runs the test matrix on all supported platforms.
- 📘 User guide: installation, configuration, commands, tools, sessions, and prompts
- 🧰 External tools: tool-set format and runners
- 🧩 Plugins: plugin contract, tools, and hooks
- 🔌 MCP servers: connect MCP servers and use their tools
- 🌐 crystal server: HTTP and event-stream protocol for other front ends
- 🌉 crystal bridge: Agent Client Protocol front end for editors
- 📄 Product definition: scope and terminology
- 📋 Deferred work: deferred, priority, and undecided buckets
- 🏗️ Architecture: components and runtime behavior
- 📏 Engineering standards: source and verification rules
- 🤖 Agent instructions: repository guidance for coding agents
The full list is in TODO.md. Items still under evaluation are separate and are not scheduled. High priority, and not in this build: a NuGet package; .NET CLI tool support; other packaging support; MCP resources, prompts, elicitation, and roots (MCP tools are in this build); and a refactor of crystal run. Medium priority, and not in this build: automatically fetching model-list information from a provider, a full code review, child Agent configuration, provider-specific custom-format tools such as OpenAI's apply_patch, and built-in tool optimization. An operating-system sandbox, audio and video input, non-text model output, editing provider definitions in the TUI, and switchable thinking-chain compression remain deferred. crystal bridge is the editor-facing front end on stdio, not an engine protocol; see docs/bridge.md. crystal server serves one session over HTTP to other front ends; see docs/server.md. Thinking-chain compression would, after each thinking pass, ask a model to compress and summarize that thinking according to a requirement. It is not context compaction. Image input is available for supported models and providers. A disk plugin may add fields to the custom status line; the default status bar stays adaptive. /model selects a configured provider and model; it does not edit the catalog. Plan and Work are built in; operators can add custom modes under modes/.