# Blueberry Documentation (Complete) > This file contains the complete Blueberry documentation in a single markdown file. > For the summary/index version, see /llms.txt > Generated: 2026-04-20 --- # Blueberry Documentation Welcome to the Blueberry documentation. Blueberry is a focus-first desktop IDE for AI-native builders. ## What is Blueberry? Blueberry brings your code, terminal, browser, and apps into one window, giving you and your AI full context without the chaos of scattered tabs and windows. ## Workspace - [Terminal](/docs/workspace/terminal) - Multi-tab terminal with session persistence - [Code Editor](/docs/workspace/code-editor) - Full-featured editor with LSP, git gutter, and syntax highlighting - [Canvas](/docs/workspace/canvas) - Whiteboard with AI agent integration - [Source Control](/docs/workspace/source-control) - Git integration with staging and diff viewer - [Preview Browser](/docs/workspace/preview-browser) - Built-in browser with DevTools and device modes ## Context - [Blueberry MCP](/docs/context/blueberry-mcp) - Give your AI full context over your workspace - [Pinned Apps](/docs/context/pinned-apps) - Keep essential apps ready per project - [Screenshot & Element Select](/docs/context/screenshot-element-select) - Visual context for your AI ## Models - [Claude Code](/docs/models/claude-code) - Anthropic's AI coding agent - [Codex](/docs/models/codex) - OpenAI's coding agent - [Gemini CLI](/docs/models/gemini-cli) - Google's AI coding tool ## App Mode - [Startup Config](/docs/app-mode/startup-config) - Define how your project launches with `.blueberry/startup.json` - [Add to Desktop](/docs/app-mode/add-to-desktop) - Turn any project into a standalone desktop app ## Workflow - [Command Bar](/docs/workflow/command-bar) - Quick access to actions via Cmd+P - [Worktrees](/docs/workflow/worktrees) - Work on multiple branches simultaneously - [Saved Setups](/docs/workflow/saved-setups) - Per-project workspace configurations - [Remote Access](/docs/workflow/remote-access) - Use Blueberry from any device ## Focus - [Flow Mode](/docs/focus/flow-mode) - Distraction-free deep work - [Layouts](/docs/focus/layouts) - Hyprland-inspired tiling layouts - [Music](/docs/focus/music) - Built-in ambient music - [Themes](/docs/focus/themes) - 8 wallpaper themes ## Getting Help Join our [Slack community](https://join.slack.com/t/blueberry-ens6414/shared_invite/zt-3odsq3aet-ItPj32AlGAkFx9_9YgYUnw) for support and feedback. --- ============================================================ # Getting Started ============================================================ # Agent Setup Set up your preferred AI coding agent to work inside Blueberry. ## Supported Agents Blueberry works with any terminal-based coding agent. Here are some popular options: ### Claude Code ```bash npm install -g @anthropic-ai/claude-code ``` Once installed, run `claude` in a Blueberry terminal to start. ### Codex ```bash npm install -g @openai/codex ``` Once installed, run `codex` in a Blueberry terminal to start. ### Gemini CLI ```bash npm install -g @google/gemini-cli ``` Once installed, run `gemini` in a Blueberry terminal to start. ### Other Agents Any coding agent that runs in a terminal works with Blueberry. Just install it and run it in a Blueberry terminal tab. ## Using Your Agent 1. Open a terminal tab in Blueberry 2. Run your agent's CLI command 3. Start describing what you want to build or change Your agent can edit files, run commands, and see your project. The editor and preview panels update as changes are made. ## MCP Integration MCP (Model Context Protocol) gives your agent deeper access to the Blueberry workspace. With MCP, your agent can: - View open files, terminal output, and browser content - Open files and navigate to specific lines - Capture screenshots and page content from the preview - Run terminal commands in Blueberry To configure the Blueberry MCP server, add it to your agent's MCP configuration: ```json { "mcpServers": { "blueberry": { "command": "blueberry-mcp" } } } ``` See the [Blueberry MCP](/docs/context/blueberry-mcp) reference for the full list of available tools. --- # Installation Download and install Blueberry on your Mac. ## System Requirements - **Operating System:** macOS (Apple Silicon) - **Disk Space:** ~500MB ## Download 1. Visit the [Blueberry download page](https://meetblueberry.com/download) 2. Download the DMG file for Apple Silicon 3. Open the DMG and drag Blueberry to your Applications folder 4. Launch Blueberry from Applications ## First Launch On first launch, macOS may ask you to confirm opening an app from an unidentified developer: 1. Right-click the Blueberry app 2. Select "Open" 3. Click "Open" in the dialog Blueberry will now launch and you can start using it. ## Next Steps - [Quick Tour](/docs/getting-started/quick-tour) - Learn the basics - [Agent Setup](/docs/getting-started/agent-setup) - Set up your AI coding agent --- # Quick Tour Your first 5 minutes with Blueberry. ## Opening a Project 1. Launch Blueberry 2. Click "Open Folder" or drag a folder onto the window 3. Blueberry will open your project with the file explorer on the left ## The Interface Blueberry's interface has three main panels, which can be rearranged to fit your workflow: - **Terminal** - Run commands and interact with your project - **Editor** - Edit code with syntax highlighting - **Preview** - View your running app ## Basic Workflow ### 1. Open a File Click any file in the explorer to open it in the editor. The editor supports 30+ languages with syntax highlighting. ### 2. Run Commands Click the terminal panel or press `Cmd+2` to focus it. Run your dev server: ```bash npm run dev ``` ### 3. Preview Your App When Blueberry detects a running dev server, it automatically opens the preview panel. You can also manually enter a URL. ### 4. Make Changes Edit your code directly in the editor, or talk to your AI agent of choice in the terminal. Blueberry supports Claude, Codex, Gemini, and more. The terminal is the heart of the workflow: describe what you want, and your agent builds it for you. Changes are saved automatically. ## Next Steps - [Agent Setup](/docs/getting-started/agent-setup) - Set up Claude, Codex, Gemini, or your preferred agent - [Code Editor](/docs/workspace/code-editor) - Learn editor features --- ============================================================ # Reference ============================================================ # Best Practices Tips for working effectively with Claude in Blueberry. ## Context Awareness ### Let Claude See First Before asking Claude to make changes, let it understand the context: ``` Look at the current file and tell me what it does. ``` Claude will call `blueberry_get_context` and see your open file. ### Be Specific About Scope Instead of "fix the bug", try: ``` There's a bug in the login function on line 42. The user state isn't being updated after successful login. ``` ## Terminal Commands ### Check Before Running Ask Claude to explain commands before running them: ``` What command should I run to start the dev server? Don't run it yet, just tell me. ``` ### Use Appropriate Terminals If you have multiple terminals, specify which one: ``` Run the tests in the "Tests" terminal tab. ``` ### Handle Long-Running Processes For dev servers and watchers: ``` Start the dev server, then let me know when it's ready. ``` Claude can check the terminal output to confirm the server started. ## Preview Browser ### Describe What You See After Claude opens a preview, describe any issues: ``` Open localhost:3000/dashboard. The chart should show user data but it's empty. ``` ### Use Screenshots Wisely Screenshots are useful for visual issues: ``` Take a screenshot of the current page. The button alignment looks off. ``` ### Read Content for Data Issues For content problems, use content capture: ``` Read the content of the current page. Are all the user names showing correctly? ``` ## File Operations ### One Thing at a Time Ask Claude to make one change, verify it works, then continue: ``` First, add the import statement. Let me check it compiles. ``` ### Review Before Saving Ask Claude to show the changes before applying: ``` Show me what the updated function would look like before you make the change. ``` ## Working with Errors ### Share Error Context When you hit an error, give Claude the full picture: ``` I'm getting a TypeScript error. Check the terminal for the error message and look at the file it mentions. ``` ### Let Claude Debug Claude can investigate issues: ``` The page isn't loading. Check the console logs in the preview for any errors. ``` ## Project Understanding ### Start New Sessions Right At the start of a session, orient Claude: ``` I'm working on a Next.js app. The main page is src/app/page.tsx. Take a look at the project structure. ``` ### Reference Documentation If you have docs in your project: ``` Check the README for how the API authentication works. ``` ## Common Patterns ### Code Review ``` Look at my recent changes in the Source Control panel and review them for any issues. ``` ### Testing ``` Run the test suite and summarize any failures. ``` ### Debugging ``` The form isn't submitting. Open the page, fill in the form, and check the network tab for what happens. ``` ### Documentation ``` Based on this function, write a JSDoc comment explaining what it does. ``` --- # FAQ Frequently asked questions about Blueberry. ## General ### What is Blueberry? Blueberry is a focus-first workspace for builders. It brings your code, terminal, browser, and apps into one window, giving you and your AI coding agent full context without the chaos of scattered tabs and windows. ### How much does Blueberry cost? Blueberry is completely free while in beta. We'll introduce pricing down the road, but for now you can enjoy full access at no cost. ### What platforms does Blueberry support? Blueberry is currently available for Mac only (Apple Silicon). We're focused on making the Mac experience exceptional before expanding to other platforms. ## AI Agent Integration ### Which AI coding agents does Blueberry support? Blueberry works with any terminal-based AI coding agent, including [Claude Code](/docs/models/claude-code), [Codex](/docs/models/codex), and [Gemini CLI](/docs/models/gemini-cli). If it runs in a terminal, it works in Blueberry. ### How does AI integration work? Your AI agent can see everything in your workspace through the [Blueberry MCP](/docs/context/blueberry-mcp): your code, terminal, browser, and pinned apps. This gives it full context to help you build. No more copying and pasting screenshots or explaining what you're looking at. ### Do I need a subscription to an AI agent? You need access to at least one AI coding agent (e.g., Claude Code, Codex, or Gemini CLI), which may require a separate subscription. Blueberry itself is free. ### What can AI agents do with Blueberry? Through the Blueberry MCP, your AI agent can: - See your open files and code - Read terminal output - View your preview browser content - Open files and navigate to specific lines - Run terminal commands - Take screenshots of your preview - Create and manage App Mode startup configs ## Features ### What are pinned apps? Pinned apps let you keep your essential tools like PostHog, Vercel, Supabase, Gmail, etc. right in your workspace. Switch between them with `Ctrl+number`. No more hunting through browser tabs. ### What's Flow Mode? Flow Mode removes all distractions with a single keystroke. Just you, your work, and ambient music to keep you in flow. Your attention, protected. ### Does Blueberry support music? Yes. Blueberry has Spotify and Apple Music plugins, so you can control your music without leaving your workspace. One less app to manage. ## Technical ### Is Blueberry an IDE or a text editor? Blueberry is a workspace that includes a code editor, but it's designed as a complete environment rather than just an editor. It combines editing, terminal, browser preview, and app access in one window. ### What editor does Blueberry use? Blueberry has a powerful built-in code editor with syntax highlighting for 30+ languages, LSP integration, and all the editing features you'd expect. ### Can I use my VS Code extensions? Not directly. Blueberry has its own built-in features rather than using VS Code's extension system. Many common extension features (Git integration, language support, etc.) are built in. ### Does Blueberry work offline? Core features (editing, terminal, file browsing) work offline. Features that require network access (preview of web apps, pinned apps, Claude integration) need a connection. ## Troubleshooting ### Why can't I open Blueberry? macOS may block apps from unidentified developers. Right-click the app and select "Open" to bypass this. ### Why is my terminal slow? Check if you have heavy processes running. Close unused terminal tabs and try clearing the terminal buffer with `Cmd+K`. ### Why isn't my AI agent seeing my workspace? Make sure you're running your AI agent from a terminal tab inside Blueberry, not from a separate Terminal app. The Blueberry MCP server connects automatically when agents are started from a Blueberry terminal. ## Getting Help ### How do I get help or give feedback? Join our [Slack community](https://join.slack.com/t/blueberry-ens6414/shared_invite/zt-3odsq3aet-ItPj32AlGAkFx9_9YgYUnw) to chat with other builders and the Blueberry team. We'd love to hear what you're building and how we can make Blueberry better for you. ### How do I report a bug? Post in our Slack community or reach out directly. Include: - What you were trying to do - What happened instead - Your macOS version - Blueberry version (from the menu bar) --- # Keyboard Shortcuts Complete reference of Blueberry keyboard shortcuts. ## General | Action | Shortcut | |--------|----------| | Open Settings | `Cmd+,` | | Quick Open File | `Cmd+P` | | Global Search | `Cmd+Shift+F` | | Toggle Sidebar | `Cmd+B` | | Toggle Full Screen | `Ctrl+Cmd+F` | | Quit | `Cmd+Q` | ## Editor | Action | Shortcut | |--------|----------| | Save | `Cmd+S` | | Save All | `Cmd+Option+S` | | Close Tab | `Cmd+W` | | Close All Tabs | `Cmd+Shift+W` | | New File | `Cmd+N` | | Find | `Cmd+F` | | Find and Replace | `Cmd+Option+F` | | Go to Line | `Ctrl+G` | | Go to Definition | `Cmd+Click` or `F12` | | Peek Definition | `Option+F12` | | Undo | `Cmd+Z` | | Redo | `Cmd+Shift+Z` | | Cut Line | `Cmd+X` (no selection) | | Copy Line | `Cmd+C` (no selection) | | Delete Line | `Cmd+Shift+K` | | Move Line Up | `Option+Up` | | Move Line Down | `Option+Down` | | Duplicate Line | `Cmd+Shift+D` | | Toggle Comment | `Cmd+/` | | Indent | `Tab` | | Outdent | `Shift+Tab` | | Select All | `Cmd+A` | | Select Word | `Cmd+D` | | Select Line | `Cmd+L` | | Multi-Cursor | `Cmd+Option+Up/Down` | | Autocomplete | `Cmd+Space` | ## Terminal | Action | Shortcut | |--------|----------| | New Terminal | `Cmd+T` (when terminal focused) | | Close Terminal Tab | `Cmd+W` (when terminal focused) | | Toggle Terminal | `Cmd+\`` | | Line Continuation | `Option+Enter` | | Clear Terminal | `Cmd+K` | | Interrupt (Ctrl+C) | `Ctrl+C` | | EOF (Ctrl+D) | `Ctrl+D` | | Jump to Start | `Cmd+Left` | | Jump to End | `Cmd+Right` | | Delete Word | `Option+Backspace` | | Delete to Start | `Cmd+Backspace` | | Open URL in System Browser | `Cmd+Shift+click` | ## Preview Browser | Action | Shortcut | |--------|----------| | New Tab | `Cmd+T` (when preview focused) | | Close Tab | `Cmd+W` (when preview focused) | | Reload | `Cmd+R` | | Go Back | `Cmd+[` | | Go Forward | `Cmd+]` | | Focus URL Bar | `Cmd+L` | | Find in Page | `Cmd+F` (when preview focused) | | Toggle DevTools | `Cmd+Option+I` | | Switch Tabs | `Cmd+1` through `Cmd+9` | ## Panels | Action | Shortcut | |--------|----------| | Focus Editor | `Cmd+1` | | Focus Terminal | `Cmd+2` | | Focus Preview | `Cmd+3` | | Focus Canvas | `Ctrl+4` | | Toggle Flow Mode | `Cmd+.` | ## Worktrees | Action | Shortcut | |--------|----------| | New Worktree | `Ctrl+Shift+N` | | Switch to Worktree 1-9 | `Ctrl+Shift+1` through `Ctrl+Shift+9` | ## Source Control | Action | Shortcut | |--------|----------| | Open Source Control | `Cmd+Shift+G` | | Stage File | `Cmd+Enter` (in diff view) | | Commit | `Cmd+Enter` (in message field) | ## Pinned Apps | Action | Shortcut | |--------|----------| | Open Pinned App 1 | `Ctrl+1` | | Open Pinned App 2 | `Ctrl+2` | | Open Pinned App 3 | `Ctrl+3` | | Open Pinned App 4 | `Ctrl+4` | | Open Pinned App 5 | `Ctrl+5` | | Open Pinned App 6 | `Ctrl+6` | ## Music | Action | Shortcut | |--------|----------| | Play/Pause | `Cmd+Shift+P` | | Next Track | `Cmd+Shift+]` | | Previous Track | `Cmd+Shift+[` | ## Customizing Shortcuts Custom keyboard shortcut configuration is planned for a future release. --- # MCP & CLI Reference Complete reference for Blueberry's MCP server and CLI commands. ## Architecture Blueberry provides two interfaces for AI agent integration: 1. **MCP Tool** (`blueberry_get_context`): a single MCP tool that returns the full workspace state 2. **CLI** (`blueberry`): a command-line tool with 16+ commands for taking actions When an AI agent starts in a Blueberry terminal, the MCP server connects automatically and the `blueberry` CLI is available on PATH. The typical workflow is: call `blueberry_get_context` to understand the workspace, then use CLI commands via bash to take actions. ## MCP Tool ### blueberry_get_context Get the current IDE context organized by panel with visibility status. Returns a structured object: - project: Current project path - editor: \{ isVisible, activeFile, openTabs, cursor, selection, diffView \} - terminal: \{ isVisible, tabs (with id/name for terminal commands) \} - preview: \{ isVisible, activeUrl, tabs (with id/url/title for screenshots) \} - pinnedApps: [\{ id, url, title, isVisible \}] - pinned web apps - sidebar: \{ isVisible, activePanel \} - worktrees: \{ current, list (path/head/branch/isMain), defaultBranch \} - only present when git worktrees exist Each section has 'isVisible' at the top so you know immediately what's showing. **Parameters:** None ## CLI Commands The `blueberry` CLI is available on PATH in all Blueberry terminal sessions. Run `blueberry help` for the full list. ### Editor | Command | Description | |---------|-------------| | `blueberry open [--line N]` | Open a file in the editor, optionally jumping to a line | ### Preview Browser | Command | Description | |---------|-------------| | `blueberry preview ` | Open a URL in the preview panel | | `blueberry capture:webview [--output FILE]` | Screenshot the preview (saves to file) | | `blueberry capture:content [--tab ID] [--app ID]` | Get page text as accessibility tree | | `blueberry console-logs [--tab ID] [--level LEVEL]` | Get console logs from a preview tab | ### Terminal | Command | Description | |---------|-------------| | `blueberry terminal [--session ID]` | Send a command to a terminal tab | | `blueberry terminal:create [--name NAME]` | Create a new terminal tab | | `blueberry terminal-logs [--session ID] [--limit N]` | Get terminal output | ### Canvas | Command | Description | |---------|-------------| | `blueberry canvas:data` | Get all canvas elements as JSON | | `blueberry canvas:draw ` | Draw elements from a JSON file | | `blueberry canvas:draw-guide` | Get the style guide for canvas:draw (run before first use) | | `blueberry canvas:mermaid ` | Render a Mermaid diagram onto the canvas | | `blueberry canvas:remove [id2 ...]` | Remove elements by ID | | `blueberry canvas:update ` | Update properties of an element | | `blueberry capture:canvas [--output FILE]` | Screenshot the canvas | ### Pinned Apps | Command | Description | |---------|-------------| | `blueberry pinned-app ` | Open a pinned web app panel | ### App Mode | Command | Description | |---------|-------------| | `blueberry startup-config:guide` | Get the format guide for startup configs | ## Canvas CLI Usage ### Mermaid Diagrams Write a temp file with Mermaid syntax, then render it: ```bash blueberry canvas:mermaid /tmp/canvas-mermaid-abc.md ``` Supports flowcharts, sequence diagrams, class diagrams, and ER diagrams. New diagrams auto-position next to existing canvas content. ### Custom Drawing Run the style guide first, then write a JSON file with element definitions: ```bash blueberry canvas:draw-guide blueberry canvas:draw /tmp/canvas-layout-xyz.json ``` Elements within a batch are positioned relative to each other. The API auto-offsets the entire batch away from existing content. ### Important Notes - Never remove or clear existing canvas elements unless the user explicitly asks - Always use unique temp file paths (e.g., `/tmp/canvas-mermaid-a1b2.md`) to avoid conflicts - For Mermaid: keep labels short (1-3 words), avoid `
` tags - For canvas:draw: run `canvas:draw-guide` before your first drawing ## Getting Started 1. Open a terminal tab in Blueberry 2. Start your AI agent (e.g., `claude`, `codex`, `gemini`) 3. The agent automatically has MCP access and the `blueberry` CLI on PATH 4. Run `blueberry help` to see all available commands ## Best Practices - Always call `blueberry_get_context` first to understand the current workspace state - Check `isVisible` flags before interacting with panels - Use `blueberry capture:content` instead of screenshots when you need to read page text - Prefer named terminal tabs for organization (e.g., "Dev Server", "Tests") ## Error Handling Commands may return errors in these situations: - **"Blueberry is not running"**: Start Blueberry and open your project - **"Not running in a Blueberry terminal"**: Run your AI agent from a Blueberry terminal - **"No context available"**: Open a project folder in Blueberry --- # Settings Configure Blueberry to match your preferences. ## Opening Settings - Press `Cmd+,` - Or click the gear icon in the sidebar ## General Settings ### Editor | Setting | Options | Default | |---------|---------|---------| | Font Size | 8px - 24px | 14px | | Font Family | System fonts | Geist Mono | | Word Wrap | On/Off | Off | | Minimap | On/Off | On | | Tab Size | 2/4/8 spaces | 2 | ### Terminal | Setting | Options | Default | |---------|---------|---------| | Font Size | 8px - 24px | 14px | | Scrollback | Lines to keep | 5000 | | Cursor Style | Block/Line/Underline | Block | ### Preview | Setting | Options | Default | |---------|---------|---------| | Default Device | Desktop/Tablet/Phone | Desktop | | DevTools Position | Bottom/Right | Bottom | ## Appearance ### Theme Select from 8 built-in wallpaper themes: - Midnight, Dawn, Mountain, Snow - Ocean, Forest, Shadow, Alpine ### UI Density - Comfortable (default) - Compact ## Network ### Remote Access - **Allow Remote Access** - Enable browser access from other devices - **Connection URL** - Shows your local IP and port See [Remote Access](/docs/workflow/remote-access) for details. ## Integrations ### Spotify - Connect your Spotify account for music integration - Sign out to disconnect ### Apple Music - Enable Apple Music plugin - Sign in with Apple ID ## Notifications | Notification | Default | |-------------|---------| | Server detected | On | | Build errors | On | | Update available | On | ## Keyboard Shortcuts View and customize keyboard shortcuts. | Action | Default Shortcut | |--------|-----------------| | Open Settings | `Cmd+,` | | Toggle Terminal | `Cmd+\`` | | New File | `Cmd+N` | | Save | `Cmd+S` | | Find | `Cmd+F` | | Global Search | `Cmd+Shift+F` | | Quick Open | `Cmd+P` | ## Project Settings Some settings are saved per-project: - Theme - Layout mode - Panel sizes - Pinned apps - Terminal tabs These sync automatically when you switch projects. ## Syncing Settings Settings are stored locally. Sync across machines is planned for a future release. ## Reset to Defaults To reset all settings: 1. Quit Blueberry 2. Delete `~/.blueberry/settings.json` 3. Restart Blueberry --- # Troubleshooting Solutions for common issues with Blueberry. ## Installation Issues ### "App is damaged" on macOS macOS may block apps from unidentified developers. **Solution:** 1. Right-click the Blueberry app 2. Select "Open" 3. Click "Open" in the dialog Or in Terminal: ```bash xattr -cr /Applications/Blueberry.app ``` ### App won't launch **Check:** - macOS version is supported (requires macOS 12+) - Apple Silicon Mac (Intel not currently supported) ## Terminal Issues ### Terminal not responding **Try:** 1. Click the terminal panel to focus it 2. Press `Ctrl+C` to interrupt any running process 3. If still frozen, close the tab and open a new one ### Commands not found Your shell may not be loading profile files. **Solution:** Add to your terminal startup command in Settings: ```bash source ~/.zshrc ``` ### Session lost after sleep Terminal sessions should persist for 30 minutes. If you're losing them: 1. Check your network connection 2. Ensure Blueberry is still running (not suspended) 3. Try increasing the system sleep timeout ## Editor Issues ### Syntax highlighting not working **Check:** - File has correct extension (`.ts`, `.tsx`, `.js`, etc.) - File isn't too large (>2MB files may have limited highlighting) ### LSP not providing completions **Check:** 1. Language server is installed for that language 2. Project has a `tsconfig.json` (for TypeScript) 3. Try restarting Blueberry ### Slow performance with large files Files over 2MB may be slow. Consider: - Splitting large files - Disabling minimap in Settings ## Preview Issues ### Preview shows blank page **Check:** 1. Dev server is running 2. URL is correct 3. No JavaScript errors (open DevTools with `Cmd+Option+I`) ### localhost not loading **Try:** 1. Verify your dev server is running 2. Check the port matches your server 3. Try `127.0.0.1` instead of `localhost` ### CSS not updating **Try:** 1. Hard refresh: `Cmd+Shift+R` 2. Clear browser cache in DevTools 3. Check for CSS compilation errors ## Git Issues ### Changes not showing **Check:** 1. You're in a git repository 2. Files are not in `.gitignore` 3. Try refreshing the Source Control panel ### Commit failing **Check:** - Git is configured with name and email: ```bash git config user.name "Your Name" git config user.email "you@example.com" ``` ## Claude Integration Issues ### "Not running in Blueberry terminal" Claude must run in a Blueberry terminal to use MCP tools. **Solution:** 1. Open a terminal tab in Blueberry 2. Run `claude` from that terminal ### "Blueberry not running" **Check:** 1. Blueberry is running 2. The project is open in Blueberry 3. You're running Claude from within the project directory ### Tools returning errors **Check:** 1. Session token is set (happens automatically in Blueberry terminals) 2. Project is open and matches your working directory ## Remote Access Issues ### Can't connect from other device **Check:** 1. Both devices on same network 2. Remote access enabled in Blueberry settings 3. Firewall isn't blocking the connection 4. Try IP address instead of hostname ### Preview not working in remote mode localhost URLs won't work from other devices. **Solution:** Start your dev server with `--host`: ```bash npm run dev -- --host 0.0.0.0 ``` ## Performance Issues ### High CPU usage **Try:** 1. Close unused terminal tabs 2. Close unused preview tabs 3. Disable minimap if not needed 4. Restart Blueberry ### High memory usage **Check:** 1. Number of open files (close unused tabs) 2. Preview tabs (close unused pages) 3. Terminal scrollback (clear with `Cmd+K`) ## Getting Help If you're still stuck: 1. Check our [FAQ](/docs/reference/faq) 2. Join our [Slack community](https://join.slack.com/t/blueberry-ens6414/shared_invite/zt-3odsq3aet-ItPj32AlGAkFx9_9YgYUnw) 3. Report issues on GitHub --- # Changelog All notable changes to Blueberry. --- # Add to Desktop Turn any project into a standalone desktop app. ## Overview Projects with a `.blueberry/startup.json` can be launched as standalone desktop apps, with no IDE chrome. The app opens directly to your preview URL after running setup and starting all processes in the background. This is useful for running your project like a native app: click the icon, wait a moment, and your app appears. ## Creating a Desktop App Open the Command Bar (`Cmd+P`) or use the dropdown next to the Run button in the header and choose **Add to Desktop**. In the dialog: 1. **App name**: the name that appears under the desktop icon. Defaults to the project folder name or the `name` field from your `startup.json`. 2. **Icon**: choose your project's favicon (if one is detected in common locations like `public/favicon.ico`, `public/favicon.png`, etc.) or pick an emoji from the grid. Click **Add to Desktop** and a launcher is created on your Desktop. ## How It Works When you open the desktop app: 1. A startup screen appears with your project name and icon. 2. Setup commands from `startup.json` run (installing dependencies, migrations, etc.). 3. All processes start in parallel. 4. Once the preview process is ready, the app window navigates to your preview URL. The app window is standalone, with just your web content and a draggable title bar. No editor, no terminal, no sidebar. ## Sharing with Your Team Since `.blueberry/startup.json` is a regular file in your repository, anyone who clones the project gets the same Run button and Add to Desktop option. This makes it easy to onboard new team members: clone the repo, click Run, and the project sets itself up. --- # Startup Config Define how your project starts with a single JSON file, then run it with one click. ## Overview The `.blueberry/startup.json` file lives at the root of your project and tells Blueberry how to set up and run it. Think of it as a recipe: install dependencies, start your servers, and open the preview, all automated. When Blueberry detects a valid `startup.json`, a **Run** button appears in the header bar. Clicking it launches your project in app mode: setup commands run first, then all processes start in parallel, and the preview opens automatically once the server is ready. Since the file lives in your repository, your whole team gets the same one-click setup. ## The Config File Create a `.blueberry/startup.json` file at the root of your project. It has three fields: ### name (optional) Display name shown in the startup screen and desktop launcher. Defaults to the folder name if omitted. ```json "name": "My App" ``` ### setup (optional) Array of shell commands to run sequentially before starting processes. If any command fails, startup stops and shows the error. Use this for installing dependencies, running migrations, or building assets. ```json "setup": [ "npm install", "npm run db:migrate" ] ``` ### run (required) Object of named processes to start in parallel. Each entry needs a `command`, and exactly one must have `preview: true`. | Field | Type | Required | Description | | --------- | ------- | ------------ | --------------------------------------------------------------------------------------------------- | | `command` | string | Yes | Shell command to execute | | `port` | number | No | Port the process listens on (1 to 65535). If omitted, Blueberry auto-detects from the process tree. | | `preview` | boolean | One required | Set to `true` on exactly one process to mark it as the preview URL | ## Examples ### Single Service A typical setup for a Next.js or Vite project: ```json { "name": "My App", "setup": ["npm install"], "run": { "web": { "command": "npm run dev", "port": 3000, "preview": true } } } ``` ### Multiple Processes A full-stack project with a frontend, API server, and background worker: ```json { "name": "Full Stack App", "setup": ["npm install", "npm run db:migrate"], "run": { "frontend": { "command": "npm run dev", "port": 3000, "preview": true }, "api": { "command": "npm run api:dev", "port": 4000 }, "worker": { "command": "npm run worker" } } } ``` ### Minimal If you just need a dev server with no setup step: ```json { "run": { "dev": { "command": "npm run dev", "preview": true } } } ``` ## How It Works When you click **Run** (or open the project as a desktop app): 1. **Startup screen** appears, showing the project name and favicon. 2. **Setup commands** run one at a time. Each must succeed before the next starts. 3. **Run processes** all start in parallel, each in its own terminal session. 4. **Port monitoring** watches for the preview process to start listening. Once the port responds, the preview opens automatically. ## AI Integration Claude can create `startup.json` for you using the `blueberry_create_startup_config` MCP tool. Ask Claude to set up your project for app mode and it will generate the config based on your project structure. ## Worktree Integration When you create a new [worktree](/docs/workflow/worktrees) in a project that has a `startup.json`, Blueberry offers to run the setup commands automatically. A toast notification appears after the worktree is created, letting you kick off `npm install`, migrations, or whatever else is defined in your `setup` array. This gets every worktree ready to work in without manual steps. ## Tips - **Keep setup commands idempotent.** Commands like `npm install` are safe to re-run, which makes the experience smooth even if dependencies are already installed. - **Use port hints.** Specifying `port` avoids the auto-detection delay and makes startup faster. - **Multiple processes are fine.** Background workers, API servers, and database tools can all run alongside your preview process. - **Validation is immediate.** Blueberry validates the config when the file is saved. If something is wrong (missing `preview: true`, invalid port, etc.), the Run button won't appear. --- # Blueberry MCP Blueberry includes a built-in MCP server and CLI that give any AI coding agent full context and control over your entire workspace: your editor, terminal, preview browser, canvas, and pinned apps. ## What is Blueberry MCP? Blueberry MCP is a local [Model Context Protocol](https://modelcontextprotocol.io) server that runs inside Blueberry. It provides workspace context through an MCP tool and a full CLI for taking actions. When you run an AI agent from a Blueberry terminal, the MCP server connects automatically and the `blueberry` CLI is available on PATH. The agent can then read your code, check terminal output, capture screenshots, draw on the canvas, and more, all without you copying, pasting, or switching windows. This works with any MCP-compatible coding agent, including [Claude Code](/docs/models/claude-code), [Codex](/docs/models/codex), and [Gemini CLI](/docs/models/gemini-cli). ## What Your AI Can See When an AI agent runs from a Blueberry terminal, it has visibility into every part of your workspace: ### Editor - The currently open file and its contents - All open tabs - Cursor position and selection - Active diff views ### Terminal - All terminal tabs and their output - Running processes and server status - Build errors and test results ### Preview Browser - The active URL and page content - All preview tabs with their URLs and titles - Console logs from the page - Visual screenshots of your running app ### Canvas - All drawing elements and their properties - Mermaid diagrams rendered as native elements ### Pinned Apps - Your pinned web apps (GitHub, Vercel, PostHog, etc.) - Their current content and state ## How It Works Blueberry uses a two-part architecture for AI integration: 1. **MCP Context Tool** (`blueberry_get_context`): returns the full workspace state as structured data, including available CLI commands 2. **CLI Commands** (`blueberry`): 16+ commands for taking actions like opening files, running terminal commands, drawing on the canvas, and capturing screenshots The typical agent workflow is: 1. Call `blueberry_get_context` to understand the workspace 2. Use `blueberry` CLI commands (via bash) for all further actions ### Key CLI Commands | Command | What it does | |---------|-------------| | `blueberry open ` | Open a file in the editor | | `blueberry preview ` | Open a URL in the preview browser | | `blueberry terminal ` | Send a command to a terminal tab | | `blueberry capture:webview` | Screenshot the preview or a pinned app | | `blueberry capture:content` | Get page text as an accessibility tree | | `blueberry canvas:mermaid ` | Render a Mermaid diagram on the canvas | | `blueberry canvas:draw ` | Draw elements on the canvas from JSON | | `blueberry canvas:data` | Get canvas elements as JSON | | `blueberry help` | List all available commands | See the [MCP & CLI Reference](/docs/reference/mcp-tools) for full command documentation. ## Why This Matters ### No More Copy-Paste Stop copying code snippets, error logs, and screenshots into chat. Your AI can see your workspace directly and pull the context it needs. ### Better Responses With full visibility into your editor, terminal, preview, and canvas, your AI understands the complete picture. It sees the error in your terminal, the code causing it, and the result in your browser, all at once. ### Direct Actions Your AI doesn't just tell you what to do: it can do it. Open files, run commands, navigate your preview, draw diagrams, and check your deployments without you lifting a finger. ## Getting Started 1. Open a terminal tab in Blueberry 2. Start your AI agent (e.g. `claude`, `codex`, `gemini`) 3. The agent automatically has MCP access and the `blueberry` CLI on PATH See [Agent Setup](/docs/getting-started/agent-setup) for detailed setup instructions. ## Learn More - [MCP & CLI Reference](/docs/reference/mcp-tools): full command documentation - [Best Practices](/docs/reference/best-practices): tips for getting the most out of AI agents in Blueberry --- # Pinned Apps Keep your essential tools like GitHub, PostHog, Vercel, Supabase, and more pinned right in your workspace. ## What are Pinned Apps? Pinned apps let you keep web applications accessible in a dedicated sidebar panel. Instead of switching to your browser and hunting through tabs, your tools are always one click away. ## Pinning an App 1. Open the web app in the Preview Browser (e.g., `https://github.com`) 2. Drag it from the browser into your sidebar 3. The app appears as a pinned icon in your sidebar ## Using Pinned Apps ### Quick Access - Click a pinned app icon to open it - Use `Ctrl+1` through `Ctrl+6` for keyboard shortcuts ### Per-Project Sync Pinned apps are saved per project. Your marketing site project might have: - Vercel (deployment) - PostHog (analytics) While your API project might have: - Supabase (database) - GitHub (code) ### Chromeless Interface Pinned apps show just the web content without browser chrome, maximizing your screen space. ## Common Use Cases ### Development - **GitHub** - View PRs and issues - **Vercel** - Check deployments - **Netlify** - Monitor builds ### Analytics - **PostHog** - Track events - **Mixpanel** - View funnels - **Google Analytics** - Check traffic ### Backend - **Supabase** - Database and auth - **Firebase** - Realtime data - **PlanetScale** - MySQL database ### Communication - **Gmail** - Check email - **Slack** - Team chat - **Linear** - Issue tracking ## Managing Pinned Apps ### Reorder Drag and drop pinned app icons to reorder them. ### Remove Right-click a pinned app and select "Unpin" to remove it. ### Refresh Click the refresh button or press `Cmd+R` when focused on a pinned app. ## Claude Integration Claude can see the content of your pinned apps through MCP: - `blueberry_open_pinned_app` - Open a specific pinned app - `blueberry_capture_webview_content` - Read the text content - `blueberry_capture_webview_screenshot` - Take a screenshot This means you can ask Claude things like "What's the status of my latest deployment?" and it can check your Vercel dashboard. --- # Screenshot & Element Select Give your AI visual context by capturing screenshots, selecting specific elements, and sharing console output from your preview browser. ## Overview Sometimes code alone isn't enough. When you're debugging a layout issue, reviewing a UI change, or tracking down a visual bug, Claude needs to see what you see. Blueberry lets you share visual context from the preview browser directly with Claude. ## Screenshot Capture Take a screenshot of your preview browser and share it with Claude for visual analysis. ### How It Works 1. Make sure your preview browser is open with the page you want to capture 2. Ask Claude to take a screenshot, or use the screenshot button in the preview toolbar 3. Claude receives the image and can analyze layout, styling, content, and visual bugs ### What Claude Can Do With Screenshots - **Visual debugging** - Identify layout issues, misaligned elements, or broken styles - **UI review** - Compare the current state against your design intent - **Responsive testing** - Check how your app looks across device modes (desktop, tablet, phone) - **Error states** - See what error pages or empty states actually look like ### Tips - Switch device modes before capturing to test responsive layouts - Navigate to the specific page or state you want reviewed before asking for a screenshot - Use screenshots when the visual result matters more than the underlying HTML ## Element Picker Select a specific element from the preview browser to give Claude targeted context about a particular part of your UI. ### How to Use 1. Click the element picker button (crosshairs icon) in the preview toolbar 2. Hover over elements in the preview - they highlight as you move 3. Click to select an element 4. The element details are captured and available for Claude ### What Gets Captured - **Tag name** - The HTML element type - **ID and classes** - CSS identifiers for the element - **CSS selector** - A unique selector path to the element - **Text content** - A preview of the element's text - **Dimensions** - Width and height of the element ### When to Use - Point Claude to a specific button, form, or section that needs work - Identify which component corresponds to a visual element - Debug styling on a particular element without describing it manually ## Console Log Capture Share browser console output with Claude for runtime debugging. ### What's Captured Console logs are collected per preview tab and include all log levels: - **log** - General output - **warn** - Warnings - **error** - Errors and exceptions - **info** - Informational messages - **debug** - Debug output ### How It Works - Logs are captured automatically from your preview browser - Up to 100 entries are stored per tab - Logs clear automatically when the page reloads - Claude can filter by log level and read only errors, for example ### Use Cases - **Runtime errors** - Ask Claude to check the console for JavaScript errors - **API debugging** - See failed network requests or unexpected responses logged to console - **State inspection** - Review `console.log` output from your app's logic ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Toggle DevTools | `Cmd+Option+I` | | Element picker | Click crosshairs icon in toolbar | | Focus URL bar | `Cmd+L` | ## Tips for Effective Use - **Use content capture for text, screenshots for visuals.** If you need Claude to read what's on the page, `blueberry_capture_webview_content` is faster and more accurate. Use screenshots when layout and appearance matter. - **Combine context types.** Ask Claude to check both the screenshot and console logs together for a complete debugging picture. - **Test across devices.** Switch to phone or tablet mode in the preview before capturing to verify responsive behavior. - **Clear logs for focused debugging.** Have Claude clear the console log buffer, reproduce the issue, then read only the new logs. --- # Flow Mode Remove distractions with a single keystroke so you can stay in deep work. ## What is Flow Mode? Flow Mode blurs everything except your current focus area, helping you concentrate on the task at hand. It's inspired by the concept of "flow state" - that feeling of complete immersion in your work. ## Activating Flow Mode ### Keyboard Shortcut Press `Cmd+.` to toggle Flow Mode on and off. ### From the Menu Click the Focus icon in the header bar. ## What Happens in Flow Mode When you activate Flow Mode: 1. **Background Blur** - The wallpaper and non-essential UI elements blur 2. **Reduced Chrome** - Toolbars and sidebars fade back 3. **Focus Highlight** - Your active panel is emphasized 4. **Ambient Sound** - Optional ambient music continues ## Customizing Flow Mode ### Focus Area Flow Mode highlights your currently focused panel: - Editor when editing code - Terminal when running commands - Preview when testing Click a different panel to shift focus. ### Duration There's no timer - stay in Flow Mode as long as you need. Toggle off when you're ready to return to normal view. ## Tips for Deep Work ### Pair with Music Enable the music player before entering Flow Mode. Ambient or lo-fi music can help maintain focus. ### Minimize Notifications Consider enabling Do Not Disturb on your Mac while in Flow Mode. ### Full Screen Combine Flow Mode with macOS full screen (`Ctrl+Cmd+F`) for maximum immersion. ### Take Breaks Even in flow state, take regular breaks. The Pomodoro technique (25 min work, 5 min break) works well. ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Toggle Flow Mode | `Cmd+.` | | Exit Flow Mode | `Escape` or `Cmd+.` | | Switch focus panel | Click or `Cmd+1/2/3` | --- # Layouts Arrange your panels with Hyprland-inspired tiling layouts. ## Layout Modes Blueberry offers four tiling layout modes: ### Fibonacci The default layout. Panels arrange in a spiral pattern, with each new panel taking half the remaining space. ``` ┌──────────┬─────┐ │ │ 2 │ │ 1 ├──┬──┤ │ │3 │4 │ └──────────┴──┴──┘ ``` Best for: General development with multiple panels. ### Grid Panels arrange in a uniform grid, each taking equal space. ``` ┌─────┬─────┐ │ 1 │ 2 │ ├─────┼─────┤ │ 3 │ 4 │ └─────┴─────┘ ``` Best for: Comparing multiple files or views side by side. ### Columns Panels stack horizontally in columns. ``` ┌────┬────┬────┬────┐ │ │ │ │ │ │ 1 │ 2 │ 3 │ 4 │ │ │ │ │ │ └────┴────┴────┴────┘ ``` Best for: Wide monitors, comparing code files. ### Rows Panels stack vertically in rows. ``` ┌───────────────┐ │ 1 │ ├───────────────┤ │ 2 │ ├───────────────┤ │ 3 │ └───────────────┘ ``` Best for: Tall monitors, terminal-heavy workflows. ## Changing Layouts ### Layout Selector Click the layout selector in the top-right corner of the workspace to choose your preferred mode. ### From the Menu Click View → Layout and select your preferred mode. ## Resizing Panels ### Drag Borders Click and drag the border between panels to resize. ### Reset Size Double-click a border to reset panels to equal size. ### Minimum Size Each panel has a minimum size to ensure usability. ## Panel Order ### Default Order 1. File Explorer (sidebar) 2. Editor 3. Preview 4. Terminal ### Changing Order Drag panel tabs to reorder within the layout. ## Maximizing a Panel ### Temporary Maximize Double-click a panel's title bar to maximize it. Double-click again to restore. ### Focus Mode Use [Flow Mode](/docs/focus/flow-mode) to blur non-active panels. ## Saving Layouts Layout preferences are saved per project. Blueberry remembers: - Which layout mode you're using - Panel sizes - Which panels are visible ## Tips ### For Different Tasks | Task | Recommended Layout | |------|-------------------| | Coding | Fibonacci with editor maximized | | Debugging | Grid with terminal and preview visible | | Reviewing | Columns for side-by-side comparison | | Terminal work | Rows for multiple terminal views | ### Quick Access Use the layout selector in the top-right corner to quickly switch between layouts. --- # Music Control your music directly in Blueberry with Spotify and Apple Music integration. ## Overview Blueberry includes a built-in music player that integrates with your streaming services. Control playback without leaving your workspace. ## Supported Services - **Spotify** - Full integration with playback controls - **Apple Music** - Plugin support for playback ## Setting Up Music ### Spotify 1. Click the music icon in the header bar 2. Click "Connect Spotify" 3. Sign in to your Spotify account 4. Authorize Blueberry to control playback ### Apple Music 1. Open Blueberry Settings 2. Go to "Integrations" 3. Enable "Apple Music" 4. Sign in with your Apple ID ## Music Player Controls The music player appears in the header bar with a compact "Dynamic Island" style interface. ### Playback Controls - **Play/Pause** - Click the play button or press `Space` when focused - **Skip** - Next/previous track buttons - **Shuffle** - Randomize your queue - **Repeat** - Loop current track or playlist ### Now Playing - Album artwork thumbnail - Song title and artist - Progress bar ### Expanding the Player Hover over the music indicator to expand and see full controls. ## Sound Bars Animation When music is playing, animated sound bars appear in the header. This gives you visual feedback that music is playing even at a glance. ## Using with Flow Mode Music continues playing when you enter Flow Mode. The ambient audio helps maintain focus while the visual distractions fade away. ### Recommended for Focus - Lo-fi hip hop - Ambient electronic - Classical/instrumental - Nature sounds ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Play/Pause | `Cmd+Shift+P` | | Next track | `Cmd+Shift+]` | | Previous track | `Cmd+Shift+[` | | Toggle music player | Click music icon | ## Troubleshooting ### Spotify Not Connecting 1. Make sure you have a Spotify Premium account 2. Try signing out and back in 3. Check that Blueberry has permission in Spotify settings ### No Sound 1. Check your system volume 2. Verify audio output device in System Preferences 3. Make sure the track isn't paused ### Playback on Wrong Device Spotify plays on the last active device. Open Spotify's "Connect" menu and select your Mac. --- # Themes Customize your workspace with built-in wallpaper themes. ## Available Themes Blueberry includes 8 beautiful wallpaper themes: | Theme | Description | |-------|-------------| | **Midnight** | Dark, starry night sky | | **Dawn** | Golden sunrise with warm tones | | **Mountain** | Scenic mountain landscape | | **Snow** | White snowy terrain | | **Ocean** | Blue water seascape | | **Forest** | Green woodland scene (default) | | **Shadow** | Dark, moody silhouette | | **Alpine** | Mountain peaks at high altitude | ## Changing Themes ### From Settings 1. Open Settings (`Cmd+,`) 2. Go to "Appearance" 3. Select a theme from the gallery ### Keyboard Shortcut Press `Cmd+K T` to open the theme picker. ## Per-Project Themes Themes are saved per project. This lets you: - Use different themes for different projects - Quickly identify which project you're working on - Match the theme to the project's vibe ### Example Setup - Marketing site → Dawn (bright, energetic) - Backend API → Midnight (focused, technical) - Personal project → Forest (calm, natural) ## Theme Components Each theme includes: ### Wallpaper A high-quality background image that fills the window behind your panels. ### Color Adjustments Subtle tinting of UI elements to complement the wallpaper. ### Overlay A semi-transparent layer that ensures text readability while showing the wallpaper. ## Dark Mode All themes are designed for dark mode. The dark interface provides: - Reduced eye strain during long coding sessions - Better contrast for syntax highlighting - Focus on your content, not the UI ## Custom Themes Custom theme support is planned for a future release. You'll be able to: - Add your own wallpapers - Customize accent colors - Share themes with others ## Related - [Settings](/docs/reference/settings) - More customization options - [Flow Mode](/docs/focus/flow-mode) - Blur the theme for focus --- # Claude Code Use Anthropic's AI coding agent directly in Blueberry's terminal. ## What is Claude Code? Claude Code is Anthropic's agentic coding tool that lives in your terminal. It can understand your codebase, edit files, run commands, and help you build software faster. When you run Claude Code inside Blueberry, it gains full visibility into your workspace through MCP. ## Installation Install Claude Code globally via npm: ```bash npm install -g @anthropic-ai/claude-code ``` ## Setup ### 1. Configure Your API Key Claude Code requires an Anthropic API key. Set it as an environment variable: ```bash export ANTHROPIC_API_KEY=your-api-key ``` You can add this to your shell profile (`~/.zshrc` or `~/.bashrc`) so it persists across sessions. ### 2. Start Claude Code in Blueberry 1. Open a terminal tab in Blueberry 2. Navigate to your project directory 3. Run `claude` to start an interactive session ```bash claude ``` Claude Code will automatically detect your project structure and begin an interactive session. ## Blueberry MCP Integration When Claude Code is connected to Blueberry's MCP server, it gains additional capabilities beyond a standard terminal session: - **Workspace awareness** - Claude can see your open files, terminal output, and preview browser - **File navigation** - Claude can open files and jump to specific lines in the editor - **Terminal control** - Claude can run commands in Blueberry's terminal tabs - **Screenshots** - Claude can capture screenshots of your preview browser - **Live preview** - Claude can open URLs in the preview panel To set up the MCP connection, see the [Agent Setup guide](/docs/getting-started/agent-setup). ## Key Capabilities - Read and understand entire codebases - Create, edit, and refactor files - Run shell commands and interpret output - Search across files with semantic understanding - Debug errors by reading logs and stack traces - Work across multiple files in a single session ## Learn More - [Agent Setup](/docs/getting-started/agent-setup) - Configure MCP integration - [Blueberry MCP](/docs/context/blueberry-mcp) - How Blueberry provides context to AI agents - [Anthropic Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) - Official Claude Code docs --- # Codex Use OpenAI's coding agent directly in Blueberry's terminal. ## What is Codex? Codex is OpenAI's agentic coding tool that runs in your terminal. It can read your codebase, suggest changes, write code, and run commands. Running Codex inside Blueberry gives it richer context about your workspace. ## Installation Install Codex globally via npm: ```bash npm install -g @openai/codex ``` > Check the [official Codex documentation](https://github.com/openai/codex) for the latest installation instructions. ## Setup ### 1. Configure Your API Key Codex requires an OpenAI API key. Set it as an environment variable: ```bash export OPENAI_API_KEY=your-api-key ``` You can add this to your shell profile (`~/.zshrc` or `~/.bashrc`) so it persists across sessions. ### 2. Run Codex in Blueberry 1. Open a terminal tab in Blueberry 2. Navigate to your project directory 3. Start Codex: ```bash codex ``` Codex will start an interactive session with access to your project files. ## How Blueberry Provides Context Running Codex inside Blueberry's terminal means it can: - Access your full project directory from the terminal - See command output alongside your code in the editor - Work while you monitor changes in the live preview panel Blueberry's integrated environment lets you watch Codex's changes take effect in real time through the preview panel and editor. ## Key Capabilities - Understand and navigate large codebases - Generate and edit code across multiple files - Run shell commands and react to output - Explain existing code and suggest improvements - Help with debugging and error resolution ## Learn More - [OpenAI Codex Documentation](https://github.com/openai/codex) - Official docs and setup guide --- # Gemini CLI Use Google's AI coding tool directly in Blueberry's terminal. ## What is Gemini CLI? Gemini CLI is Google's command-line AI tool powered by the Gemini model. It can help you understand code, generate new code, debug issues, and automate tasks. Running Gemini CLI inside Blueberry gives it access to your full development environment. ## Installation Install Gemini CLI globally via npm: ```bash npm install -g @anthropic-ai/gemini-cli ``` > The install command above may change. Check the [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for the latest installation instructions. ## Setup ### 1. Authenticate Gemini CLI uses Google authentication. Run the auth command and follow the prompts: ```bash gemini auth ``` Alternatively, you can set an API key: ```bash export GEMINI_API_KEY=your-api-key ``` > Refer to the official documentation for the most up-to-date authentication method. ### 2. Run Gemini CLI in Blueberry 1. Open a terminal tab in Blueberry 2. Navigate to your project directory 3. Start Gemini CLI: ```bash gemini ``` Gemini CLI will start an interactive session with access to your project files. ## How Blueberry Provides Context Running Gemini CLI inside Blueberry's terminal means it can: - Access your full project directory from the terminal - See command output alongside your code in the editor - Work while you monitor changes in the live preview panel Blueberry's integrated environment lets you watch Gemini's changes take effect in real time through the preview panel and editor. ## Key Capabilities - Read and understand codebases - Generate and edit code - Run shell commands and interpret output - Help with debugging and error resolution - Explain code and suggest improvements ## Learn More - [Gemini CLI Documentation](https://github.com/google-gemini/gemini-cli) - Official docs and setup guide --- # Command Bar Quickly access files, actions, and settings from anywhere in Blueberry with `Cmd+P`. ## Overview The Command Bar is a universal launcher that puts every action at your fingertips. Instead of hunting through menus or remembering where settings live, press `Cmd+P` and start typing. ## Opening the Command Bar Press `Cmd+P` from anywhere in Blueberry to open the Command Bar. Press `Escape` to dismiss it. ## What You Can Do ### File Search Start typing a file name to quickly find and open files in your project. Results update as you type with fuzzy matching, so you don't need to remember exact file names. ### Commands Access workspace commands like toggling panels, switching themes, or managing terminals. Type "claude" to quickly access Claude Code sessions, conversations, headless prompts, resume, and config commands. ### Settings Jump directly to specific settings without navigating through menus. ### Navigation Switch between open tabs, preview pages, and pinned apps. ## Tips for Power Users - **Type fast, be vague.** Fuzzy matching means you can type partial file names or abbreviations and still find what you need. - **Use it for everything.** The Command Bar is often faster than clicking through the UI, even for actions you know the location of. - **Muscle memory.** The more you use `Cmd+P`, the faster it becomes. It's designed to be the single entry point for navigating your workspace. ## Keyboard Shortcuts | Action | Shortcut | | ---------------- | ---------------- | | Open Command Bar | `Cmd+P` | | Dismiss | `Escape` | | Select item | `Enter` | | Navigate results | `Up/Down` arrows | --- # Remote Access Access Blueberry from other devices on your local network, like an iPad or phone. ## Overview Remote Access lets you use Blueberry from any device on your local network. This is useful for: - Using your iPad as a second screen - Quick edits from your phone - Pairing with a colleague on the same network ## Enabling Remote Access 1. Open Blueberry Settings (`Cmd+,`) 2. Go to the "Network" section 3. Toggle "Allow Remote Access" on 4. Note the connection URL shown (e.g., `http://192.168.1.100:4200`) ## Connecting from Another Device 1. Open a web browser on your other device 2. Enter the connection URL from Blueberry settings 3. Blueberry loads as a web app ### iPad/iPhone For the best experience on iOS: 1. Open the URL in Safari 2. Tap the Share button 3. Select "Add to Home Screen" 4. Open from your home screen for a full-screen app experience ## What Works in Remote Mode | Feature | Desktop | Remote | |---------|---------|--------| | Code Editor | ✅ | ✅ | | Terminal | ✅ | ✅ | | File Explorer | ✅ | ✅ | | Preview Browser | ✅ | ⚠️ Limited | | DevTools | ✅ | ❌ | | Element Picker | ✅ | ❌ | ### Preview Limitations The preview browser in remote mode uses an iframe instead of a webview. Localhost URLs are automatically converted to your Mac's IP address. ## Security Considerations ### Local Network Only Remote access is restricted to your local network. Devices must be on the same WiFi/LAN to connect. ### Session Token Each remote session uses a token for authentication. The token is generated when you enable remote access. ### Recommendations - Only enable remote access when you need it - Disable it when finished - Don't use on public networks ## Troubleshooting ### Can't Connect 1. Verify both devices are on the same network 2. Check that remote access is enabled in Blueberry 3. Try the IP address directly (not hostname) 4. Check your firewall allows connections on the Blueberry port ### Preview Not Working If previewing localhost sites from remote: 1. Start your dev server with `--host 0.0.0.0` flag 2. Or use `npm run dev -- --host` 3. This allows your dev server to accept connections from other devices ### Slow Performance Remote access adds network latency. For best performance: - Use a wired connection if possible - Stay close to your WiFi router - Reduce preview refresh rate ## Future Improvements We're working on: - Password/PIN protection - QR code for easy connection - mDNS discovery (automatic finding of Blueberry) - Notification when devices connect --- # Saved Setups Blueberry remembers your workspace setup for each project, so you can pick up right where you left off. ## Overview Every developer sets up their workspace differently depending on the project. Your marketing site might need the preview browser front and center, while your API project needs multiple terminal tabs. Saved Setups automatically persist your workspace layout per project so you never have to reconfigure things when switching between projects. ## What Gets Saved Blueberry saves the following for each project: - **Layout mode** - Your panel arrangement and sizing - **Pinned apps** - Which web apps are pinned in the sidebar - **Terminal tabs** - Your named terminal tabs and their configuration - **Theme** - Light, dark, or custom theme preference - **Panel sizes** - The exact dimensions of each panel - **Device preview mode** - Desktop, tablet, or phone mode in the preview browser ## How It Works Saved Setups are fully automatic. There's nothing to configure or manage. 1. **Open a project** - Blueberry loads your saved setup for that project, or starts with the default layout for new projects 2. **Customize your workspace** - Resize panels, pin apps, create terminal tabs, switch themes 3. **Close or switch projects** - Your setup is saved automatically 4. **Come back later** - Everything is restored exactly as you left it ## Switching Between Projects Each project maintains its own independent setup. When you switch projects: - Your current project's setup is saved - The new project's setup is loaded - Pinned apps, terminal tabs, panel sizes, and theme all update to match the new project This means you can have completely different workflows per project without any manual switching. ## Tips for Multi-Project Workflows - **Pin project-specific tools.** Keep Vercel pinned for your frontend project and Supabase pinned for your backend project. Each project remembers its own pinned apps. - **Name your terminal tabs.** Use descriptive names like "Dev Server", "Tests", or "Build" so you can quickly orient yourself when returning to a project. - **Set the right device mode.** If you're working on a mobile-first project, set the preview to phone mode. It'll stay that way for that project. - **Let it work for you.** Don't overthink your setup. Just arrange things how you like them and Blueberry handles the rest. --- # Worktrees Work on multiple branches at the same time without stashing or switching. ## Overview Worktrees are a built-in Git feature (`git worktree`). They let you check out multiple branches simultaneously, each in its own directory, no stashing, no context-switching. Blueberry enhances the experience by wrapping the underlying commands in a visual UI so you can create, switch, and remove worktrees without touching the terminal. Everything maps directly to standard Git operations, so your worktrees work the same way whether you manage them from Blueberry or the command line. Each worktree appears as a numbered pill (1, 2, 3…) in the header bar. Click a pill to switch to that worktree instantly. Your editor, terminal, and preview all update to reflect the new branch. You can have up to 9 worktrees open at once. ## Creating a Worktree Press `Ctrl+Shift+N` or open the Command Bar (`Cmd+P`) and search for **"New Worktree"**. In the dialog: 1. **Start point**: choose which branch to base it on (defaults to your repository's default branch). 2. **Branch name**: enter a name for the new branch. 3. **Copy environment files**: if `.env` files are found in your project root (`.env`, `.env.local`, `.env.development`, etc.), a checkbox lets you copy them to the new worktree automatically. This is checked by default. Blueberry creates a sibling directory named `-` and opens it as a new worktree. A new numbered pill appears in the header bar. If your project has a [`.blueberry/startup.json`](/docs/app-mode/startup-config), Blueberry offers to run the setup commands (like `npm install`) automatically after the worktree is created. This gets the new worktree ready to go without manual steps. ## Switching Worktrees You have several ways to switch between worktrees: - **Header pills**: click any numbered pill in the header bar. Hover over a pill to see its branch name. - **Keyboard shortcuts**: press `Ctrl+Shift+1` through `Ctrl+Shift+9` to jump directly to a worktree by number. - **Command Bar**: press `Cmd+P`, search for **"Change Worktree"**, then pick from the list. ## Removing a Worktree Hover over a worktree pill in the header bar and long-hover to reveal the **X** button, or use the Command Bar to search **"Change Worktree"** and select the remove action. When removing a worktree, Blueberry walks you through a few checks: 1. **Uncommitted changes**: if the worktree has uncommitted changes, you'll be prompted to either commit them (with a customizable message) or discard them before proceeding. 2. **New environment variables**: if the worktree's `.env` files contain keys that don't exist in the main project, Blueberry shows them and offers to copy them back. You can copy the new variables to the main project or skip this step. 3. **Confirm removal**: choose between: - **Remove**: deletes the worktree directory but keeps the branch. - **Remove & Delete Branch**: deletes both the worktree directory and the branch. ## Finishing Up with a Worktree When you're done with a worktree, you'll want to get your changes back into the main branch: 1. **Commit your work**: make sure all changes in the worktree branch are committed. 2. **Push the branch**: push to remote so you can open a pull request, or merge locally. 3. **Merge into main**: use your normal merge workflow (PR, `git merge`, or `git rebase`) from the main worktree. 4. **Remove the worktree**: once merged, remove the worktree using the header pill (long-hover for the X) or the Command Bar. Choose **Remove & Delete Branch** if the branch is fully merged and no longer needed. Since each worktree is just a branch checked out in its own directory, your standard Git workflow applies. There's nothing special to do beyond treating it like any other branch. ## Environment Files Blueberry handles `.env` files specially in worktrees since they're typically gitignored and wouldn't transfer between branches: - **On create**: detected `.env` files (`.env`, `.env.local`, `.env.development`, etc.) are optionally copied from the main project to the new worktree. - **On remove**: Blueberry checks if the worktree added new environment variables that the main project doesn't have. If found, it offers to copy them back before the worktree is deleted. This prevents losing API keys or configuration that were added during development in a worktree. ## Command Center Integration The Command Bar (`Cmd+P`) has full worktree support. Search for **"Change Worktree"** to see a list of all your worktrees with options to switch to or remove each one. ## Working with AI Blueberry's MCP context (`blueberry_get_context`) automatically exposes your worktree information to Claude. This means Claude knows which worktrees exist, which one is active, and can factor that into its suggestions. ## Tips - **Keep worktrees focused.** Use one worktree per task: a feature branch, a bug fix, a review. This keeps your mental context clean. - **Install dependencies in new worktrees.** Each worktree is a separate directory, so dependencies aren't shared. Run your project's install command before starting work (e.g. `npm install`, `pip install -r requirements.txt`, `bundle install`, `cargo build`). If you switch to a worktree and things look broken, a missing install is usually the reason. - **Use keyboard shortcuts.** `Ctrl+Shift+1` through `Ctrl+Shift+9` make switching nearly instant once you build muscle memory. - **External changes are detected.** If you create or remove worktrees from the terminal with `git worktree add` or `git worktree remove`, Blueberry picks up the changes automatically. - **Only the main project shows in the project picker.** Worktree directories are hidden to keep your project list tidy. ## Keyboard Shortcuts | Action | Shortcut | | ---------------------- | ------------------------------- | | Create new worktree | `Ctrl+Shift+N` | | Switch to worktree 1-9 | `Ctrl+Shift+1` - `Ctrl+Shift+9` | | Open Command Bar | `Cmd+P` | --- # Canvas A built-in whiteboard for wireframes, diagrams, sketches, and visual thinking, right inside your workspace. ## Overview The canvas is a built-in drawing panel that lives alongside your editor, terminal, and preview. Open it with `Ctrl+4` or from the Command Bar. Everything you draw is saved per project and persists across restarts. Use it to sketch UI layouts, map out architecture, draw flowcharts, or let your AI agent generate diagrams for you. ## Drawing Tools The canvas toolbar includes: - **Shapes** - Rectangle, ellipse, diamond, arrow, line - **Text** - Click anywhere to add text labels - **Freehand** - Draw with a pencil tool - **Eraser** - Remove elements - **Selection** - Move, resize, and group elements ### Properties Bar When you select an element or activate a drawing tool, a properties bar appears with context-aware options: - **Fill color** - Solid, hatch, cross-hatch, or transparent fills - **Stroke color** - Border and line colors including black - **Stroke width** - Thin, regular, bold - **Stroke style** - Solid, dashed, dotted - **Font size** - Small, medium, large, extra-large (for text) - **Arrow style** - Arrowhead types and curve style - **Opacity** - Element transparency ## Mermaid Diagrams Render Mermaid syntax (flowcharts, sequence diagrams, class diagrams, ER diagrams) directly onto the canvas. Diagrams are converted to native canvas elements that you can rearrange and style. From the terminal: ```bash blueberry canvas:mermaid /path/to/diagram.md ``` AI agents can create Mermaid diagrams by writing a temp file and running the command. New diagrams are automatically positioned to avoid overlapping existing content. ## PNG Export Export your canvas as a PNG image: 1. Select the elements you want to export (or export everything) 2. Use the download button in the toolbar 3. Choose dark or light mode for the export background Exported images include 20px padding and use a subtle background color. ## AI Agent Integration AI agents can interact with the canvas through CLI commands available in any Blueberry terminal: | Command | Description | |---------|-------------| | `blueberry canvas:data` | Get all canvas elements as JSON | | `blueberry canvas:draw ` | Draw elements on the canvas from a JSON file | | `blueberry canvas:mermaid ` | Render a Mermaid diagram onto the canvas | | `blueberry canvas:remove [id2 ...]` | Remove elements by ID | | `blueberry canvas:update ` | Update properties of an existing element | | `blueberry capture:canvas` | Screenshot the canvas | Agents should run `blueberry canvas:draw-guide` before their first `canvas:draw` to get the style guide for element positioning and formatting. New content added via `canvas:draw` and `canvas:mermaid` is automatically positioned next to existing elements to avoid overlap. ## Per-Project & Per-Worktree Canvas state is isolated per project. When using [worktrees](/docs/workflow/worktrees), each worktree has its own independent canvas. You can optionally copy the canvas to a new worktree using the "Copy workspace setup" checkbox in the Create Worktree dialog. ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Focus Canvas | `Ctrl+4` | --- # Code Editor Blueberry includes a powerful code editor with built-in language support, smart git awareness, and specialized viewers. ## Multi-Language Syntax Highlighting Blueberry supports **30+ programming languages** out of the box: **Web Technologies:** JavaScript, TypeScript, JSX/TSX, HTML, CSS, SCSS, Less, JSON, YAML, XML **Server Languages:** Python, Go, Rust, Java, C#, C++, Ruby, PHP, Swift, Kotlin **Data & Config:** SQL, GraphQL, Markdown, Shell, Dockerfile, TOML Each language includes: - Automatic language detection from file extension - Syntax coloring with semantic token support - Bracket matching and auto-closing - Code folding for large files ## Language Server Protocol (LSP) Blueberry integrates with Language Server Protocol for intelligent code understanding: ### Hover Information - Type information for variables and functions - Inline documentation from source - Parameter hints ### Go to Definition (Cmd+Click) - Navigate to function/class definitions - Automatically opens file in new tab - Preserves editor scroll position **Supported Languages:** JavaScript, TypeScript, Python, Go, Rust (with language server installed) ## Real-Time Git Gutter The editor's left margin shows live git status: | Indicator | Meaning | |-----------|---------| | 🟢 Green | New lines added | | 🔵 Blue | Modified lines | | 🔴 Red dot | Deleted lines | Features: - Hover over changed line for original content - Uses LCS diff algorithm for precision - Updates instantly as you edit ## Side-by-Side Diff Viewer View original vs. current file content in the Source Control panel: - Line numbers with diff indicators - Syntax coloring in both panes - Scroll sync between panes - Full-screen diff view for detailed review ## Markdown Preview & Block Editor
Hello World\n}", language: "tsx", }, }} initialOpenTabs={["README.md", "src/app/page.tsx"]} initialActiveTab="README.md" />
When you open a `.md` or `.mdx` file, Blueberry offers a Notion-like block editor alongside the standard source view. ### Preview Mode Toggle between **Preview** and **Markdown** tabs in the toolbar: - **Preview** renders the markdown as a rich document with styled headings, tables, code blocks, and links - **Markdown** shows the raw source in the standard code editor - Both editors stay mounted, so undo history is preserved when switching between views ### Block Editing In preview mode, the editor supports: - **Slash commands** - Type `/` to insert headings, lists, code blocks, tables, and more - **Drag-and-drop blocks** - Rearrange paragraphs, headings, and other blocks by dragging - **Inline formatting** - Bold, italic, code, links with a floating toolbar - **Tables** - Full-width tables with header backgrounds - **Code blocks** - Syntax-highlighted with dark theme styling - **Links** - Click links to open them in Blueberry's preview panel Changes in preview mode are merged back into the source markdown, preserving formatting that the block editor doesn't handle. ## Image Viewer Open images directly in the editor: **Zoom Levels:** 10%, 25%, 50%, 75%, 100%, 150%, 200%, 300%, 400% **Shortcuts:** - `+` Zoom in - `-` Zoom out - `F` Toggle fit mode Supported formats: PNG, JPG, GIF, WebP, SVG ## Editor Settings Customize from Settings → General: - Font size (8px - 20px, default: 14px) - Font family - Theme - Word wrap toggle - Minimap toggle ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Save | `Cmd+S` | | Find | `Cmd+F` | | Global search | `Cmd+Shift+F` | | Quick file search | `Cmd+P` | | New file | `Cmd+N` | | Close tab | `Cmd+W` | | Undo/Redo | `Cmd+Z` / `Cmd+Shift+Z` | --- # Preview Browser The preview browser gives you a built-in web browser panel for testing your apps, complete with device emulation, Chrome DevTools, and element inspection. ## Tab Management Manage multiple preview tabs like a regular browser: - **Create tabs** - `Cmd+T` opens a new blank tab - **Close tabs** - `Cmd+W` closes the active tab - **Switch tabs** - `Cmd+1-9` jumps to numbered tabs - **Reorder tabs** - Drag tabs to rearrange ### Tab Types - **Manual tabs** - Created by user - **Server tabs** - Auto-created when dev server detected (linked to terminal) ### Tab Indicators - Favicon from page - Page title (updates on navigation) - Loading spinner during page load - Green pulsing dot on tabs connected to running dev servers ## Smart URL Bar The URL bar understands what you want to navigate to: | Input | Result | | -------------------- | --------------------------- | | `localhost:3000` | `http://localhost:3000` | | `127.0.0.1:5000/api` | `http://127.0.0.1:5000/api` | | `example.com` | `https://example.com` | | `search query` | Google search | **Shortcuts:** - `Cmd+L` - Focus URL bar and select all text - `Enter` - Navigate to entered URL - `Escape` - Cancel editing ## Device Preview Modes Test responsive designs with built-in device presets. The device toolbar at the bottom of the preview panel lets you switch between three modes: - **Desktop** (monitor icon): constrains the viewport to a fixed desktop resolution - **Tablet** (tablet icon): shows a tablet-sized viewport - **Phone** (phone icon): shows a phone-sized viewport Click a mode icon to activate it. Click the same icon again to return to responsive (full-width) mode. ### Device Presets Each mode includes a dropdown with common device presets: **Phone presets:** | Device | Viewport | | ----------------- | --------- | | iPhone 17 Pro Max | 440 x 956 | | iPhone 17 Air | 420 x 912 | | Galaxy S24 Ultra | 412 x 915 | | Pixel 9 Pro | 412 x 915 | | Pixel 9 | 412 x 824 | | iPhone 17 Pro | 402 x 874 | | iPhone 17 | 402 x 874 | | Galaxy S24 | 360 x 780 | **Tablet presets:** | Device | Viewport | | ------------- | ----------- | | iPad Pro 13" | 1032 x 1376 | | iPad Pro 11" | 834 x 1194 | | iPad Air | 820 x 1180 | | Galaxy Tab S9 | 800 x 1280 | | iPad Mini | 768 x 1024 | **Desktop presets:** | Device | Viewport | | ----------- | ----------- | | 4K | 3840 x 2160 | | QHD | 2560 x 1440 | | Full HD | 1920 x 1080 | | MacBook Air | 1440 x 900 | | Laptop | 1366 x 768 | | HD | 1280 x 720 | ### Custom Dimensions Select **Custom** from the preset dropdown to enter your own width and height. Dimensions are clamped between 350px minimum and 3840 x 2160 maximum. ### Rotate The rotate button swaps width and height, useful for testing landscape vs portrait orientations. ### Scaling When the viewport dimensions exceed the available panel space, the preview automatically scales down to fit. The current scale percentage is shown in the toolbar. Device mode is saved per project. ## Embedded DevTools Full Chrome DevTools available inline: ### Opening DevTools - `Cmd+Option+I` - Toggle DevTools panel - Click the DevTools button in toolbar ### Position Options - **Bottom** - DevTools below preview (good for wide screens) - **Right** - DevTools beside preview (good for tall screens) ### Features - Full Elements, Console, Network, Sources panels - Element inspection - Live CSS editing - JavaScript console - Network request monitoring ## Element Picker Inspect page elements without opening DevTools: 1. Click the element picker button (crosshairs icon) 2. Hover over elements - they highlight as you move 3. Click to select an element 4. View element details in popover ### Element Info Captured - Tag name - ID and CSS classes - Unique CSS selector - Text content preview - Element dimensions ## Find in Page Press `Cmd+F` while the preview panel is focused to open a Chrome-style find bar. Search for text on the current page with: - Match counter showing current position and total matches - Previous/next navigation buttons - Responsive layout that adapts to panel width This also works in [pinned app](/docs/context/pinned-apps) panels. ## Open Links in Browser Right-click any link in the preview to access **"Open Link in Browser"**, which opens the URL in your default system browser. This is useful for links that need full browser capabilities or when you want to view something outside Blueberry. ## Console Capture Browser console logs are captured for debugging: **Log Levels:** log, warn, error, info, debug - Logs captured per tab (max 100 entries) - Automatically cleared when page reloads - Available via MCP for Claude integration ## Certificate & Authentication ### Certificate Errors When navigating to a site with an untrusted HTTPS certificate, the preview shows a warning interstitial with details about the certificate issue. You can choose to proceed anyway. The URL bar also displays a "Not Secure" badge for these pages. ### HTTP Basic Auth Password-protected pages trigger a sign-in dialog directly in the preview. This also works for pinned apps, so tools behind HTTP authentication are accessible without leaving Blueberry. ## Server Detection Integration Preview automatically connects with detected dev servers: 1. Terminal detects server on port 2. Preview creates a new tab linked to that terminal 3. Tab shows green indicator while server is running 4. Tab auto-navigates to server URL --- # Source Control Blueberry includes built-in Git integration with staging, commits, and a visual diff viewer. ## Source Control Panel Access the Source Control panel from the sidebar to see all your changes. ### File States | Icon | State | |------|-------| | M | Modified | | A | Added (new file) | | D | Deleted | | U | Untracked | ### Actions - **Stage** - Click the `+` button to stage a file - **Unstage** - Click the `-` button to unstage - **Discard** - Revert changes to last commit - **View Diff** - Click a file to see the diff ## Staging Changes ### Stage Individual Files Click the `+` button next to any changed file to stage it. ### Stage All Click "Stage All" to stage all changes at once. ### Partial Staging The diff viewer shows individual hunks that can be staged separately. ## Committing 1. Stage your changes 2. Enter a commit message in the text field 3. Click "Commit" or press `Cmd+Enter` ### Commit Message Tips - Keep the first line under 50 characters - Use present tense ("Add feature" not "Added feature") - Reference issue numbers if applicable ## Diff Viewer The side-by-side diff viewer shows original vs. current content: ### Features - Line numbers with diff indicators - Syntax coloring in both panes - Scroll sync between panes - Full-screen view for detailed review ### Reading Diffs - **Red background** - Removed lines - **Green background** - Added lines - **Yellow background** - Modified lines ## Git Gutter The editor shows live git status in the left margin: - 🟢 Green - New lines - 🔵 Blue - Modified lines - 🔴 Red - Deleted lines Hover over the gutter to see the original content. ## Branch Management View your current branch in the status bar. Branch switching is available through the terminal. ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | Open Source Control | `Cmd+Shift+G` | | Stage selected | `Cmd+Enter` (in diff view) | | Commit | `Cmd+Enter` (in message field) | --- # Terminal The terminal brings full shell access directly into Blueberry with multi-tab support, session persistence that survives network interruptions, and smart integrations. ## Multi-Tab Terminal Run multiple terminal sessions with drag-and-drop tab management: ### Tab Features - **Create tabs** - `Cmd+T` opens a new terminal session - **Rename tabs** - Double-click tab name - **Reorder tabs** - Drag tabs to rearrange - **Tab indicators** - Green pulsing dot shows running server - **Startup commands** - Configure commands to auto-run when tab opens ### Auto-Naming - Tabs automatically rename to "Server" when a dev server is detected - Tabs rename to the agent name when an AI agent is detected (see below) - Manual renames are preserved ## Split Panes Split terminal tabs into multiple groups with tmux-style horizontal and vertical splits. ### Creating Splits - **Horizontal split** - Divide the terminal side by side - **Vertical split** - Stack terminals top and bottom - **Nested splits** - Splits can be nested recursively for complex layouts ### Working with Split Groups Each split group has its own tab bar and active session: - **Drag tabs between groups** - Move terminal sessions across split panes - **Focused group** - Keyboard shortcuts (`Cmd+T`, `Cmd+number`) target the currently focused group - **Auto-close** - Empty groups close automatically when other groups exist - **Resize** - Drag the handle between groups, or double-click to reset to 50/50 Split layouts persist per workspace, surviving project switches and restarts. ## AI Agent Detection Blueberry automatically detects AI coding agents running in terminal tabs: ### Supported Agents - **Claude Code** - Anthropic's coding agent - **Codex** - OpenAI's coding agent - **Gemini CLI** - Google's coding agent - **OpenCode** - Open-source coding agent ### How It Works Blueberry scans child processes of each terminal session to detect known agent binaries. When an agent is detected: - The tab automatically renames to the agent name (e.g., "Claude") - An agent icon appears on the tab - Both clear when the agent process exits ## Session Persistence Terminal sessions survive network interruptions, laptop sleep, and browser refreshes: ### How It Works - **30-minute grace period** - PTY processes stay alive after disconnect - **50KB output buffer** - Recent output replayed on reconnection - **Heartbeat monitoring** - Server detects stale connections via ping/pong ### Reconnection - Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (max 10 attempts) - Yellow spinner during reconnection - Attempt counter: "Reconnecting (attempt 3/10)" - Reload button after max attempts ## Clickable Links `Cmd+click` on file paths and URLs in terminal output: ### File Links - Absolute paths: `/Users/foo/project/src/file.ts:42:10` - Relative paths: `./src/file.ts`, `src/file.ts` - With line numbers: `file.ts:42` or `file.ts:42:10` - Opens file in editor at specified line ### URL Links - Full URLs: `https://example.com` - Localhost: `localhost:3000`, `127.0.0.1:8080` - Opens in preview browser panel ## Server Auto-Detection Blueberry automatically detects when you start a dev server: ### Detection Process (macOS) 1. Monitors child processes every 2 seconds 2. Scans for listening ports via `lsof` 3. Verifies HTTP server with HEAD request 4. Notifies via WebSocket message ### When Server Detected - Tab auto-renames to "Server" - Green pulsing indicator appears on tab - Preview browser can auto-navigate to server URL ## Terminal Settings ### Per-Tab Settings - Tab name (with manual override protection) - Startup command (auto-runs on tab open) ### Global Settings - Font size (adjustable) - Scrollback buffer: 5000 lines ## Keyboard Shortcuts | Action | Shortcut | |--------|----------| | New terminal tab | `Cmd+T` | | Close current tab | `Cmd+W` | | Line continuation | `Option+Enter` | | Delete to line start | `Cmd+Backspace` | | Delete word | `Opt+Backspace` | | Jump to line start/end | `Cmd+Left/Right` | | Jump word | `Opt+Left/Right` | | Open link in system browser | `Cmd+Shift+click` | --- ## Additional Resources - Website: https://meetblueberry.com - Download: https://meetblueberry.com/download - Slack Community: https://join.slack.com/t/blueberry-ens6414/shared_invite/zt-3odsq3aet-ItPj32AlGAkFx9_9YgYUnw --- End of documentation.