docs
everything you need to know about running parallel claude code sessions in one tiny window.
in 30 seconds
flock is a native macOS app. no electron, no web views, no bundled runtime. download it, open it, and press ⌘T to spawn your first claude session.
System Requirements
- macOS 13 (Ventura) or later
- Apple Silicon or Intel
- Claude Code CLI installed (
npm install -g @anthropic-ai/claude-code)
Homebrew (recommended)
$ brew tap divagation/flock $ brew install --cask flockapp
Direct Download
Grab the latest .pkg from GitHub Releases. Run the installer, then launch Flock from Applications.
Build from Source
$ git clone https://github.com/baahaus/flock.git $ cd flock $ ./build.sh # installs to /Applications/Flock.app
First Launch
Open Flock. It creates a single Claude pane by default. You're in. Press ⌘T to add more sessions, ⌘⇧T for a plain shell. That's it.
Auto-Layout
Flock automatically arranges panes based on how many you have open. No manual dragging, no guessing.
Manual Splits
Want more control? Split the current pane horizontally with ⌘D or vertically with ⌘⇧D. This creates a custom split tree that overrides auto-layout.
Maximize
Press ⌘↵ to maximize the focused pane to fill the entire window. Press again to restore the grid. Great for focusing on one agent's work.
Navigation
Jump between panes with ⌘1 through ⌘9, or use arrow keys: ⌘← ⌘→ ⌘↑ ⌘↓.
Layout Presets
The command palette (⌘K) includes preset layouts: Single Claude, Claude + Shell, 2x2 Grid, and 3-up.
Press ⌘⇧A to toggle agent mode. The terminal grid is replaced with a three-panel view for creating, monitoring, and interacting with agent tasks.
The Three-Panel Layout
Sidebar (Left)
The sidebar is a task list grouped by status: Running, Queued, and Done. Click "+ New Agent" to create a task -- type a description and press Enter. That description becomes the prompt sent to Claude Code.
Click any task to select it and view its details in the other two panels. Right-click for context actions:
- Queued tasks: Start Now, Delete
- Running tasks: Cancel (or Finish if waiting for input)
- Done/Failed tasks: Retry, Delete
Conversation Timeline (Center)
A real-time event log of every action the agent takes. As Claude Code works, each tool use and thinking block appears as a row with a colored badge, title, and timestamp. Only one action is "active" at a time, shown with a blue left bar and bold title.
When a task finishes but has a session, it enters a "waiting for input" state. A message input field appears at the bottom so you can send follow-up prompts -- Flock resumes the conversation using Claude Code's --resume flag.
Detail Panel (Right)
Two tabs:
- Plan -- a checklist of all actions with status indicators (✓ done, • active, ○ pending). Consecutive thinking blocks are grouped as "Analyzing..."
- Changes -- every file the agent touched, with a badge showing the operation (Read, Edit, Write)
Automatic Scheduling
You don't manually assign tasks to agents. Flock's runner automatically picks up the next queued task whenever capacity allows, up to maxParallelAgents (default: 3) running concurrently. When one finishes, the next in the queue starts immediately.
Event Types
Flock parses Claude Code's stream-json output and maps each event to a badge in the timeline:
Stream-JSON Protocol
Under the hood, Flock launches Claude Code with --output-format stream-json. Each line of output is a JSON event (thinking, tool_use, tool_result, result). The StreamJsonParser buffers incoming data, splits on newlines, and emits typed events that become timeline entries.
Cost Tracking
Each task accumulates cost across conversation rounds. The total USD cost appears in the conversation footer and in the sidebar subtitle for completed tasks. Enable the usage tracker in Preferences for aggregate stats.
Persistence
Tasks are saved to ~/Library/Application Support/Flock/tasks.json. They survive app restarts. If Flock quits while a task is running, it's automatically marked as failed on next launch.
The command palette is the fastest way to do anything in Flock. It supports fuzzy search -- type a few characters and it finds what you want.
Available Commands
Panes
- New Claude Pane
- New Shell Pane
- Close Pane
- Rename Tab
- Split Horizontal / Vertical
- Focus Pane 1-9
- Navigate Left / Right / Up / Down
View
- Maximize / Restore
- Find in Terminal
- Find in All Panes
- Toggle Broadcast
- Toggle Agent Mode
- Toggle Memory
- Preferences
Layouts
- Single Claude
- Claude + Shell
- 2x2 Grid
- 3-up
Appearance
- Switch to any of the 7 built-in themes
Memory
- Toggle Memory sidebar
- Add Memory entry
- Clear All Memories
- Toggle Memory Feature on/off
Press ⌘⇧B to toggle broadcast mode. When active, every keystroke goes to all open panes simultaneously. An orange border around the window indicates broadcast is on.
Use Cases
- Give all your Claude agents the same context at once
- Set up environment variables across all shells
- Send a shared prompt to multiple sessions
- Coordinate a team of agents working on related tasks
Toggle it on, type your message, toggle it off. Each pane continues independently from there.
Full Reference
| Shortcut | Action |
|---|---|
| ⌘T | New Claude pane |
| ⌘⇧T | New shell pane |
| ⌘W | Close current pane |
| ⌘1 - ⌘9 | Focus pane 1 through 9 |
| ⌘← ⌘→ | Navigate left / right |
| ⌘↑ ⌘↓ | Navigate up / down |
| ⌘↵ | Maximize / restore pane |
| ⌘D | Split pane horizontally |
| ⌘⇧D | Split pane vertically |
| ⌘K | Open command palette |
| ⌘⇧A | Toggle agent mode |
| ⌘⇧B | Toggle broadcast mode |
| ⌘⇧M | Toggle memory sidebar |
| ⌘F | Find in current pane |
| ⌘G | Find next match |
| ⌘⇧G | Find previous match |
| ⌘⇧F | Find in all panes |
| ⌘C | Copy |
| ⌘V | Paste |
| ⌘A | Select all |
| ⌘, | Preferences |
| ⌘H | Hide Flock |
| ⌘⌥H | Hide others |
| ⌘Q | Quit Flock |
| Ctrl+` | Global hotkey (bring to front) |
Theme transitions use a cross-dissolve animation. You can also override ANSI terminal colors per-theme in the configuration for full control over syntax highlighting.
find in pane
search the current pane's terminal output. ⌘G for next match, ⌘⇧G for previous.
find in all panes
search across every open pane simultaneously. results highlight in each pane's output.
Flock automatically saves your layout and pane arrangement when you quit. On next launch, everything is restored -- pane positions, terminal state, and working directories.
Startup Behavior
In Preferences, choose between:
- New Claude Pane -- fresh start every time (default)
- Restore Last Session -- pick up right where you left off
Session data is stored in ~/Library/Application Support/Flock/session.json.
Crash Recovery
If Flock quits unexpectedly, any in-progress agent tasks are automatically marked as failed so you know exactly what didn't finish.
Press ⌘⇧M to open the memory sidebar. This is a persistent store of context that carries across sessions -- agent instructions, project notes, anything you want your Claudes to remember.
How It Works
- Add memories manually from the sidebar or command palette
- Memories persist in
~/Library/Application Support/Flock/memories.json - Toggle the entire memory feature on/off in Preferences
- Clear all memories from the command palette when you want a fresh start
When an agent finishes a task and Flock isn't in the foreground, you get a native macOS notification. Click it to jump straight to that pane.
Notifications respect your macOS notification preferences (Do Not Disturb, etc.). No special setup required.
Press Ctrl+` (backtick) from any app to bring Flock to the foreground. Works system-wide, even when Flock is minimized or behind other windows.
Customization
In Preferences, you can:
- Enable or disable the global hotkey
- Change the key (default: backtick, key code 50)
- Change the modifier (default: Control). Options include Ctrl, Cmd, Shift, Option, or combinations.
| Setting | Description | Default |
|---|---|---|
| fontSize | Terminal font size in points | 13 |
| defaultPaneType | New pane type: Claude or Shell | claude |
| startupBehavior | New pane or restore last session | new pane |
| showActivityIndicators | Show activity dots on tabs | true |
| themeId | Active color theme | flock |
| soundEffectsEnabled | Audio feedback on events | false |
| globalHotkeyEnabled | System-wide hotkey | true |
| globalHotkeyKeyCode | Hotkey key code | 50 (`) |
| globalHotkeyModifiers | Hotkey modifier flags | control |
| maxParallelAgents | Max concurrent agent tasks | 3 |
| memoryEnabled | Enable memory persistence | true |
| showUsageTracker | Show token/cost tracking | false |
| autoCheckUpdates | Check for updates on launch | true |
All settings are stored in UserDefaults and take effect immediately. Changes broadcast a notification so all components update in sync.
Custom ANSI Colors
Each theme defines a 16-color ANSI palette for terminal syntax highlighting. You can override these per-theme for full control over how code looks in your terminals.
Data Locations
# Task history & kanban state ~/Library/Application Support/Flock/tasks.json # Session layout for restore ~/Library/Application Support/Flock/session.json # Memory entries ~/Library/Application Support/Flock/memory.json # Preferences defaults read com.baa.flock
Requirements
- Xcode 15+ (or the Xcode command line tools)
- Swift 5.9+
- macOS 13+
Build
$ git clone https://github.com/baahaus/flock.git $ cd flock $ ./build.sh
The build script compiles the Swift package, bundles the app with its icon and entitlements, and installs to /Applications/Flock.app.
Dependencies
Flock has one external dependency:
- SwiftTerm (v1.0.0+) -- terminal emulator engine. Pulled automatically by Swift Package Manager.
Release Build
$ ./release.sh # creates a signed .pkg for distribution