GitHub - stravu/crystal: Run multiple Codex and Claude Code AI sessions in parallel git worktrees. Test, compare approaches & manage AI-assisted development workflows in one desktop app.

Crystal - Multi-Session AI Code Assistant Manager

Crystal lets you use AI on isolated copies of your code so you can work on multiple tasks instead of waiting for your agents to finish.

Run one or more sessions with Claude Code, Codex, or both

Rich output for your agents

Run your code and test before merging

Crystal_v0.3.0.mp4

The Crystal Workflow

Create sessions from prompts, each in an isolated git worktree
Iterate with your AI assistant (Claude Code or Codex) inside your sessions. Each iteration will make a commit so you can always go back.
Review the diff changes and make manual edits as needed
Squash your commits together with a new message and merge to your main branch.

🚀 Quick Start

Prerequisites

For Claude Code: Claude Code installed and logged in or API key provided
For Codex: Codex installed (via npm: @openai/codex or Homebrew) with ChatGPT account or API key
Git installed
Git repository (Crystal will initialize one if needed)

1. Create a Project

Create a new project if you haven't already. This can be an empty folder or an existing git repository. Crystal will initialize git if needed.

2. Create Sessions from a Prompt

For any feature you're working on, create one or multiple new sessions:

Each session will be an isolated git worktree

3. Monitor and Test Your Changes

As sessions complete:

Configure run scripts in project settings to test your application without leaving Crystal
Use the diff viewer to review all changes and make manual edits as needed
Continue conversations with your AI assistant if you need additional changes

4. Finalize Your Changes

When everything looks good:

Click "Rebase to main" to squash all commits with a new message and rebase them to your main branch
This creates a clean commit history on your main branch

Git Operations

Rebase from main: Pull latest changes from main into your worktree
Squash and rebase to main: Combine all commits and rebase onto main
Always preview commands with tooltips before executing

Installation

Download Pre-built Binaries

macOS: Download Crystal-{version}.dmg from the latest release
- Open the DMG file and drag Crystal to your Applications folder
- On first launch, you may need to right-click and select "Open" due to macOS security settings
Windows: Windows is supported but requires building from source
- Follow the "Building from Source" instructions below
- Requires Visual Studio 2022 with Spectre-mitigated libraries
- Official installer coming in future releases

Homebrew

brew install --cask stravu-crystal

Building from Source

Prerequisites

macOS/Linux: Xcode Command Line Tools or build-essential
Windows: Visual Studio 2022 with Spectre-mitigated libraries (see detailed instructions)

Build Steps

# Clone the repository
git clone https://github.com/stravu/crystal.git
cd crystal

# One-time setup
pnpm run setup

# Run in development
pnpm run electron-dev

Building for Production

# Build for macOS
pnpm build:mac

# Build for Windows
pnpm build:win

# Build for Linux
pnpm build:linux

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Developing Crystal with Crystal

If you're using Crystal to develop Crystal itself, you need to use a separate data directory to avoid conflicts with your main Crystal instance:

# Set the run script in your Crystal project settings to:
pnpm run setup && pnpm run build:main && CRYSTAL_DIR=~/.crystal_test pnpm electron-dev

This ensures:

Your development Crystal instance uses ~/.crystal_test for its data
Your main Crystal instance continues using ~/.crystal
Worktrees won't conflict between the two instances
You can safely test changes without affecting your primary Crystal setup

Using with Third-Party Deployments

To use Crystal with cloud providers or via corporate infrastructure, you should create a settings file with ENV values to correctly connect to the provider.

For example, here is a minimal configuration to use Amazon Bedrock via an AWS Profile:

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-2", // Replace with your AWS region
    "AWS_PROFILE": "my-aws-profile" // Replace with your profile
  },
}

Check the deployment documentation for more information on getting setup with your particular deployment.

Additional Documentation

For a full project overview, see CLAUDE.md. Additional diagrams, database schema details, release instructions, and license notes can be found in the docs directory.

📄 License

Crystal is open source software licensed under the MIT License.

Third-Party Licenses

Crystal includes third-party software components. All third-party licenses are documented in the NOTICES file. This file is automatically generated and kept up-to-date with our dependencies.

To regenerate the NOTICES file after updating dependencies:

pnpm run generate-notices

Disclaimer

Crystal is an independent project created by Stravu. Claude™ is a trademark of Anthropic, PBC. Codex™ is a trademark of OpenAI, Inc. Crystal is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. This tool is designed to work with Claude Code and Codex, which must be installed separately.