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

Rich output for your agents

Run your code and test before merging

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

• 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)

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.

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

• Each session will be an isolated git worktree

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

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

• 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

• 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 (Unofficial - Build from source): Windows is currently supported through local builds only. An installer will be provided in future releases.

  • Follow the "Building from Source" instructions below

brew install --cask stravu-crystal

# 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

# Build for macOS
pnpm build:mac

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

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

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.

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.

Crystal is open source software licensed under the MIT License.

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

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.

Made with ❤️ by Stravu