# Getting started

## [What is crystl?](/content/docs/faq/what-is-crystl/index.html)

crystl is a macOS terminal built for coding agents. It lets you run many agents at once without getting lost in tabs and windows: every project is a **gem** with its own terminal **shards**, a screen-edge **[crystal rail](/content/docs/crystal-rail/index.html)** keeps projects one click away, and **[floating cards](/content/features/floating-cards/index.html)** float approvals and questions on screen so you answer the right agent without hunting. It also works as a normal terminal for any command-line work.

## [Is crystl free?](/content/docs/faq/is-crystl-free/index.html)

Yes. The free tier includes isolated shards and parallel sessions, floating cards, the [agent activity panel](/content/docs/agent-activity-panel/index.html), split view, the [history navigator](/content/docs/conversation-history/index.html), token tracking, the [workbench](/content/docs/task-backlog/index.html), project optimizer, the agent file editor, screenshot and copy bars, MCP servers, API key storage, remote development over SSH, Metal-accelerated GPU rendering, facet inserts, and [agent scheduling](/content/docs/schedule-agents/index.html) (up to 3 schedules). The **[Guild](/content/pricing/index.html)** plan ($170/year or $18/month) adds the Prompt Library integration, [formations](/content/docs/formations/index.html), CLI orchestration (the control commands), unlimited scheduling, the iPhone app from anywhere, up to 3 devices, and priority support. See [Licensing](/content/docs/licensing/index.html) for the full split.

## [Does crystl work on Linux or Windows?](/content/docs/faq/does-crystl-work-on-linux-or-windows/index.html)

No. crystl is **macOS only** today. It’s a native Swift app and relies on macOS features like the Keychain for secure API key storage.

That said, cross-platform is now on the table. crystl’s terminal core is being rebuilt on a more portable foundation, which clears the biggest technical blocker to a Windows or Linux version. It’s a possibility, not a promise: crystl is built by one developer, and a port only becomes realistic with either more paying subscribers (so I can afford the time) or volunteer contributors. If a Windows or Linux version matters to you, the most direct way to make it happen is to [support crystl](/content/pricing/index.html) or [pitch in](/content/community/index.html).

## [Which agents does crystl work with?](/content/docs/faq/which-agents-does-crystl-work-with/index.html)

Any CLI agent runs in crystl, since every shard is a full terminal session. The deeper integrations depend on what each agent exposes: **Claude Code** has the deepest integration, and **Codex** supports hooks too, so approval cards and notifications work for both. **Antigravity CLI** (Google) also runs with hooks: activity, notifications, history, and resume all work, but its hook adapter can’t yet return an approval decision to the agent, so approval cards can’t gate its tool calls. **Kimi Code** (Moonshot AI) runs with model selection and real approval cards, but no transcript or resume. **opencode**, **goose**, and **GitHub Copilot CLI** get approval cards too, without turn-end reporting. Everything else works. The machine-readable version of this is at [`/agents.json`](/content/agents.json).

## [Can I use crystl for regular terminal work?](/content/docs/faq/can-i-use-crystl-for-regular-terminal-work/index.html)

Yes. Every shard is a full terminal session: git, npm, docker, ssh, whatever you need. The agent-specific features are there when you want them and out of the way when you don’t.

## [Does crystl work fully with Codex?](/content/docs/faq/does-crystl-work-fully-with-codex/index.html)

Yes. Codex supports hooks, so approval cards and notifications work just like they do for Claude Code, and Codex sessions feed the [history navigator](/content/docs/conversation-history/index.html) and token metrics. You can spawn Codex workers from the [CLI](/content/docs/cli/index.html) (`--agent codex`) and mix Codex and Claude agents in the same workspace. Antigravity CLI runs with hooks too, so activity and notifications work for it, but its hook adapter can’t yet return approval decisions, so approval cards can’t gate Antigravity tool calls.

## [Codex says “Hooks need review”. What do I do?](/content/docs/faq/codex-says-hooks-need-review-what-do-i-do/index.html)

Trust it once and you’re done. Codex asks you to approve any hook it hasn’t seen before, and crystl’s hook is how your Codex sessions get approval cards and notifications. If you’re seeing the dialog after updating crystl, it’s because the hook definition changed; it’s now frozen, so future crystl releases won’t ask again. crystl never writes a trust record on your behalf, since approving its own hook for you is exactly the step Codex added the dialog for.

# Source code & open models

## [Is crystl open source?](/content/docs/faq/is-crystl-open-source/index.html)

No. I’m not sure open source makes that much sense for indie developers. Also, I’m not sure why anyone would want crystl’s source code. It’s a pretty unique beast. But if you are interested in crystl or want to contribute, I’d be happy to [chat](/content/contact/index.html).

## [Can crystl run agents on open models?](/content/docs/faq/can-crystl-run-agents-on-open-models/index.html)

Yes. Point an agent at a model on your own hardware, or at a hosted open model, and run it next to agents like Claude Code or Codex. See [open models](/content/features/open-models/index.html).

## [Can I use the crystl library without crystl?](/content/docs/faq/can-i-use-the-crystl-library-without-crystl/index.html)

Yes. Every hero, skill, prompt, rule and workflow in the [library](/content/library/index.html) is plain text. Copy it into your own setup, with or without crystl.

## [Can I see what crystl changes on my Mac?](/content/docs/faq/can-i-see-what-crystl-changes-on-my-mac/index.html)

Yes. The hooks crystl adds to your agent’s settings and the section it keeps in `AGENTS.md` are plain text files you can open and read. The [CLI reference](/content/docs/cli/index.html) documents every command and flag. For the full list of files, see [which files crystl can create inside an existing project](/content/docs/faq/which-files-can-crystl-create-inside-an-existing-project/index.html).

## [What open source software does crystl use?](/content/docs/faq/what-open-source-software-does-crystl-use/index.html)

The terminal engine started from [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm), and updates ship through Sparkle. The full list is on the [acknowledgments](/content/acknowledgments/index.html) page.

## [Can I contribute to crystl?](/content/docs/faq/can-i-contribute-to-crystl/index.html)

The source isn’t public, so there are no pull requests to send. If you want to help make crystl better, [get in touch](/content/contact/index.html). Bug reports and ideas help too: send them from the app, or post them in the [community](/content/community/index.html).

# Gems, shards & multitasking

## [What are gems and shards?](/content/docs/faq/what-are-gems-and-shards/index.html)

A **gem** is a project workspace tied to a directory; a **shard** is a terminal session inside it. Think of gems as projects and shards as the tabs within each one. See [gems & shards](/content/docs/gems-and-shards/index.html).

## [How do gems, shards, and tabs fit together?](/content/docs/faq/how-do-gems-shards-and-tabs-fit-together/index.html)

It’s two levels. **Gems** are the top level, one per project, and you switch between them from the [crystal rail](/content/docs/crystal-rail/index.html) (the screen-edge dock) or the **gem tab bar** across the top of the window. **Shards** are the sessions inside a gem, shown in the **shard bar** that appears once a gem has two or more; each shard is its own terminal and can hold its own agent session. The gem tab bar can sit across the top by default, or down the left side with **Sidebar Mode** on (settings, **general**). Every gem always keeps at least one shard.

## [How do I add another session versus another project?](/content/docs/faq/how-do-i-add-another-session-versus-another-project/index.html)

Use the **+** on the **shard bar** to add another shard (session) to the _same_ project. Use the **+** on the **gem tab bar** (or **New Gem** in the crystal rail) to open a _different_ project. Mixing these up is the usual point of confusion: the shard-bar + stays inside the current gem, the tab-bar + opens a new one.

## [How do I run multiple agents at once?](/content/docs/faq/how-do-i-run-multiple-agents-at-once/index.html)

Open as many shards as you want inside a gem and run them side by side, and open multiple gems for different projects. [Isolated shards](/content/docs/isolated-sessions/index.html) each get their own git worktree and branch, so several agents can work the same repo simultaneously without stepping on each other.

## [How do I keep track of all my agents?](/content/docs/faq/how-do-i-keep-track-of-all-my-agents/index.html)

The [agent activity panel](/content/docs/agent-activity-panel/index.html) shows every agent across your gems in one view: who’s working, who’s idle, and where tokens are going. [Floating cards](/content/features/floating-cards/index.html) float approvals and questions as glass cards color-coded by project, so you respond to the right agent without switching windows.

# Running multiple agents

## [How do I get my AI agents to talk to each other?](/content/docs/faq/how-do-i-get-my-ai-agents-to-talk-to-each-other/index.html)

Agents talk through a shared surface, never directly. Inside one session, subagents report their result back to the agent that spawned them, and Claude Code’s `SendMessage` tool lets the parent resume a named subagent with follow-up instructions. Across separate sessions, the shared surface is a file both agents read and write, or an orchestration layer that relays messages between terminals.

The file approach is the portable one: a task list, a scratch directory, or a status document at a path both agents know. It survives restarts and works with any agent. crystl adds the relay layer: `crystl screen` reads another shard’s terminal and `crystl send` types into it, so a lead agent can dispatch work and read the reply. [side quest](/content/docs/side-quest/index.html) opens a 1:1 channel between two shards, and [crystl quest](/content/docs/crystl-quest/index.html) puts a whole party in one shared chat. See [subagents](/content/guides/claude-code-subagents/index.html) and the [CLI reference](/content/docs/cli/index.html).

### [Why do my agents keep overwriting each other’s files?](/content/docs/faq/why-do-my-agents-keep-overwriting-each-others-files/index.html)

Because they share one working directory. Two agents in the same checkout read and write the same files, and neither git nor the agents themselves arbitrate: the later write silently replaces the earlier one, and the first agent keeps reasoning about a file that no longer says what it thinks. Prompting them to stay in their lane does not hold, because agents refactor across file boundaries.

The symptom to look for is an agent citing a version of a file that no longer exists, or a change you watched land reappearing undone a few minutes later. Check `git status` and `git diff` while both agents are running: if the working tree is moving under one agent’s feet, that is the collision. Full breakdown of the failure modes: [why your AI agents keep overwriting each other’s files](/content/blog/agents-overwriting-files/index.html). For the setup that prevents it, see [how do I stop agents stepping on each other in one repo](/content/docs/faq/#how-do-i-stop-agents-stepping-on-each-other-in-one-repo/index.html).