Documentation

Everything you need to get started with Crest.

Quick Start

Get up and running in 3 simple steps.

1

Download the App

Get the latest version for your platform from our releases page.

Download
2

Open a Project Folder

Click "Open Project" or drag any folder into the app. This sets your working directory.

# Or use the command palette
Cmd+Shift+P → "Open Project"
3

Start Coding

Click "Start Session" or press Cmd+Enter. Claude will connect and you're ready to go!

Claude Code CLI will be auto-installed if needed

Installation

macOS

  1. 1. Download the .dmg file from the releases page
  2. 2. Open the DMG and drag "Crest" to Applications
  3. 3. First launch: Right-click the app and select "Open" (required for unsigned apps)
  4. 4. If blocked, go to System Settings → Privacy & Security → "Open Anyway"

Note: The app is not signed with an Apple Developer certificate. This is common for open-source apps. The "Open Anyway" step is only needed once.

Windows

  1. 1. There is no Windows installer yet. Build from source:
  2. 2. Clone the repo: git clone https://github.com/OneWave-AI/Crest.git
  3. 3. Install and build: npm ci then npm run build:win
  4. 4. Local models (Ollama) are not available on Windows yet

Linux

  1. 1. There is no prebuilt Linux download yet. Build from source:
  2. 2. Clone the repo: git clone https://github.com/OneWave-AI/Crest.git
  3. 3. Install and build: npm ci then npm run build:linux
  4. 4. Run the AppImage from dist/ (make it executable with chmod +x first)

Your First Session

Here's what to expect when you start your first coding session.

1 Claude Code CLI Check

The app checks if Claude Code CLI is installed. If not, it offers to install it automatically.

2 Terminal Opens

A terminal session starts in your project folder. Claude is ready to receive your commands.

3 Start Coding!

Type your request naturally: "Create a React component for a todo list" or "Fix the bug in app.js"

Pro Tips

  • Use the Toolbelt button to quickly insert skills and agents into your prompt
  • Enable Super Agent for tasks that require multiple steps without manual approval
  • Use Agent Hive to run multiple audits (security, performance, tests) in parallel
  • Use Teams to coordinate multiple agents with shared task lists on complex features
  • Click the Grid button to launch a 3x2 grid of 6 terminals for multi-project workflows

Super Agent

Super Agent is an autonomous layer that monitors Claude's terminal and makes decisions on your behalf. It uses a fast outer LLM (Groq or OpenAI) to keep Claude working without manual intervention.

How It Works

Super Agent uses a two-tier decision system:

  • AUTO Fast-path decisions handle known patterns instantly without calling the LLM. This includes y/n prompts, spinner detection, trust prompts, and sending the initial task. These show as teal "Auto" entries in the activity log.
  • LLM LLM decisions are used for creative responses like answering questions, choosing options, or suggesting improvements. These show as indigo "LLM" entries.
  • APPROVED Permission approvals auto-approve y/n prompts and show the question that was approved, so you can see exactly what was allowed.

Safety Levels

Control how much autonomy the agent has:

SAFE Dangerous commands (rm -rf, git push --force, drop database, etc.) are not auto-approved. They fall through to the LLM for evaluation instead of blindly sending "y".
MODERATE Dangerous commands are blocked from being sent, but all y/n prompts are auto-approved.
YOLO No restrictions. Everything is auto-approved and nothing is blocked. Use with caution.

Session Stats

During a session, the status bar tracks real-time metrics:

  • N written - Files created or edited by Claude
  • N passed - Tests that passed during the session
  • N failed - Tests that failed or errors encountered

Setup

Super Agent requires an API key for the outer LLM. Configure it in Settings:

  1. 1. Open Settings (Cmd + ,) and go to the Super Agent tab
  2. 2. Enter your Groq or OpenAI API key
  3. 3. Choose your preferred provider and model
  4. 4. Start a terminal session, then click the Super Agent button in the toolbar to activate

Tip: Groq's free tier is fast and works great for Super Agent. The agent uses very few tokens per decision since most common patterns are handled by the instant fast-path.

Teams

Teams is Claude Code's native multi-agent coordination system. A lead agent spawns teammates that share a task list and communicate via messages to work on complex projects in parallel.

How Teams Work

When Claude creates a team, it establishes a lead agent that coordinates specialized teammates. Each team has:

  • Team members with roles like researcher, frontend-developer, test-engineer, each with their own model and capabilities
  • Shared task list where tasks can be assigned, tracked, and have dependencies (blocks/blockedBy)
  • Direct messaging between agents for coordination and status updates

Teams Panel

Open the Teams panel from the toolbar (teal Users icon) or from the home screen to manage your teams:

  • VIEW See all active teams with member count, task progress bar, and creation date
  • DETAIL Click a team to see its members (role, model, working directory) and all tasks with status, owner, and dependencies
  • LIVE Auto-refreshes every 5 seconds so you can watch tasks complete in real time without manual refreshing

Starting a Team

There are two ways to start a team:

  1. 1. From the terminal: Ask Claude directly to create a team for your task. Claude will spawn teammates and coordinate them automatically.
  2. 2. Start Team button: Click the "Start Team" button in the Teams panel header. This sends a prompt to your active terminal session asking Claude to analyze your current conversation and suggest a team.

Tip: Teams work best for complex, multi-step tasks where different parts can be worked on in parallel - like building a full-stack feature with frontend, backend, and tests.

Data Location

Teams are stored on disk and persist across sessions:

# Team configurations
~/.claude/teams/{team-name}/config.json

# Team task lists
~/.claude/tasks/{team-name}/{task-id}.json

You can delete teams from the Teams panel when they're no longer needed.

Keyboard Shortcuts

Master these shortcuts to navigate like a pro.

Action Shortcut
Command Palette Cmd + P
Quick Open File Cmd + O
Search Files Cmd + F
Switch Project Cmd + Shift + P
Start Session (from home) Cmd + Enter
Toggle Split View Cmd + \
Grid Layout (3x2) Click Grid button or use + menu
New Terminal Tab Cmd + Shift + T
Git Commit Cmd + Shift + C
Refresh Files Cmd + R
Go to Parent Directory Cmd + Up
Expand All Directories Alt + Cmd + Right
Collapse All Directories Alt + Cmd + Left

On Windows/Linux, replace Cmd with Ctrl

Configuration

Customize Crest to fit your workflow.

Settings Panel

Access settings via the gear icon in the header or Cmd + ,

  • Terminal Theme: Choose from 14 themes, including Default, Pro, Homebrew, Ocean, Dracula, Solarized, Tokyo Night and Synthwave
  • Font Size: Adjust terminal and editor font size
  • Auto-detect Localhost: Toggle automatic dev server detection

Skills & Agents Location

Crest auto-discovers skills and agents from:

# Skills
~/.claude/skills/

# Custom Agents
~/.claude/agents/

MCP Servers

MCP servers are configured in your Claude config file:

~/.claude.json

Use the MCP Manager in Crest to add/remove servers without editing JSON manually.

Troubleshooting

App won't open on macOS

Since the app isn't signed with an Apple certificate:

  1. Right-click the app and select "Open"
  2. Click "Open" in the dialog
  3. If still blocked: System Settings → Privacy & Security → "Open Anyway"
Claude Code CLI not found

Crest will auto-install Claude Code CLI if missing. If manual install is needed:

npm install -g @anthropic/claude-code
Terminal not responding

Try these steps:

  1. Close and reopen the terminal tab
  2. Restart the app
  3. Check if Claude Code CLI is running properly in a regular terminal
Skills not showing up

Skills are loaded from ~/.claude/skills/. Make sure:

  • The folder exists
  • Skill files have .md extension
  • Click "Refresh" in the Skills panel

Still stuck?

Open an issue on GitHub with details about your problem.

Open GitHub Issue