From Terminal Chaos to Crystal Clarity: Migrating Your Claude Code Workflow

You’re already using Claude Code. You’ve got the CLI installed, you know how to start a session, and you’ve built real things with it. But your setup has grown organically, and “organically” is a polite word for what’s happening in your terminal.

Maybe you have seven iTerm2 tabs open, three of which are Claude Code sessions you forgot about. Maybe you accidentally ran a Claude session in the wrong project directory last week and it edited the wrong files. Maybe you lost a two-hour conversation because you closed a tab.

If that’s your setup, you can go from chaos to something structured in about ten minutes.

Step 1: Take stock of what you’re juggling

Before changing anything, take stock of your current setup. If you’re using Claude Code regularly, you’re probably managing:

2-5 active projects they rotate between during a week
Multiple Claude sessions per project (one for features, one for tests, one for debugging)
Different API keys for personal vs. work vs. client projects
Project-specific context like MCP server configs or CLAUDE.md files

If you’re doing all of this in a generic terminal, you’re spending real mental overhead remembering which tab is which, which directory you’re in, and which API key is active. That overhead compounds every time you switch projects.

Step 2: Install Crystl and create your first gem

Once it’s running, create your first gem. A gem is Crystl’s unit of project organization. Point it at your project directory, give it a name, and you’ve got a dedicated workspace for that project.

Each gem lives in the Crystal Rail, the navigation bar on the side of your screen. You’ll see it immediately — one click to switch between projects instead of hunting through tabs. Learn more about gems and the Crystal Rail.

Start with your most active project. You can add the rest later.

Step 3: Set up your shards

Within your gem, create shards — terminal sessions tied to that project. The naming matters here. Instead of “Tab 4” and “Tab 7,” you can name shards by what they do:

“Feature work”
“Tests”
“Bug investigation”
“Refactor”

Each shard starts in your gem’s project directory automatically. No more cd-ing to the right folder and hoping you’re in the right place.

If you want two Claude agents working on the same codebase simultaneously, create isolated shards. These use git worktrees behind the scenes, so each agent gets its own branch and working directory. No conflicts, no overwrites. See isolated sessions for the full explanation.

Step 4: Configure per-project settings

This is where the migration starts paying dividends immediately.

API keys. If you use different API keys for different contexts — personal projects vs. work, or different client accounts — you can assign keys per gem. No more worrying about which key is active. Set it once, and every shard in that gem uses the right key. API key management docs.

MCP servers. If your projects use different MCP server configurations, set those per gem too. A web project might use a browser automation MCP server, while a data project uses a database connector. Each gem carries its own config. MCP server docs.

Approval modes. Some projects you trust Claude to run freely. Others — especially client work — you want to approve every file write. Set the approval mode per gem based on how much autonomy makes sense for that project.

Step 5: Let conversation history do its job

One thing that changes without you doing anything: every conversation is now preserved automatically.

In your old setup, closing a terminal tab meant losing everything. In Crystl, every shard’s conversation history persists. Close a shard, reboot, come back three days later — the full conversation is there, structured and scrollable. Not raw terminal output, but the actual back-and-forth with code blocks and tool calls rendered properly.

This changes how you work in subtle but important ways. You start treating sessions as reference material. “What approach did Claude suggest for the auth refactor?” Open the shard, scroll back, find it.

Step 6: Set up notifications and stop babysitting

In a standard terminal, you find out a Claude session needs attention by staring at it. If you’ve got multiple sessions running, you’re cycling through tabs checking for pending approval prompts.

Crystl sends macOS notifications when a shard needs you — pending approvals, completed tasks, errors. You can focus on other work and respond only when needed. This is especially valuable if you’re running isolated shards in parallel.

What your workflow looks like after migration

The before and after:

Before: Open terminal. cd to project. Start Claude. Work. Open another tab. cd to a different project. Forget which tab is which. Accidentally close one. Lose the conversation. Re-explain context to Claude. Get frustrated.

After: Open Crystl. Click a gem. See all your shards, their status, and their history. Spin up a new shard if you need one. Get notified when any session needs attention. Switch between projects in one click. Never lose a conversation.

The tooling change takes ten minutes. The workflow improvement is permanent.

Do you need the paid license?

No. Crystl is free and fully functional. The optional license unlocks some convenience features, but the core workflow described above — gems, shards, conversation history, notifications, per-project configuration — is available on the free plan.

If you decide later that you want more shards or additional features, you can learn about licensing then. No pressure, no trial expiration.

Get started at crystl.dev/login.