Balcony

A native Apple companion app for Claude Code. Monitor live terminal sessions, approve permissions, respond to questions, and dictate via voice - all from your iPhone, while away from your desk.

Request TestFlight AccessComing Soon Star us on GitHub↗

claude — ~/repos/landing

$ claude "Add settings page with dark mode"

› Planning implementation...

· Reading src/App.tsx

· Reading src/theme.ts

Write src/settings.tsx

· Settings page created with theme toggle.

✓ Done — 3 files changed

ws://192.168.1.42:29170 — encrypted

↑ streaming to Balcony · 12 frames

9:41

‹landing

Active

› Add a settings page with dark mode toggle

· Reading src/App.tsx

· Reading src/theme.ts

Write src/settings.tsx

Settings page created with theme toggle.

✓ Done — 3 files changed

Allow

Deny

Message Claude...

↑

Components

CLI wrapper, Mac menu bar agent, and iPhone app working in concert

Surfaces

Terminal, Mac panel, or iPhone - first response wins, all stay in sync

E2E

Encrypted

X25519 + XChaCha20-Poly1305 authenticated encryption for all traffic

Sessions

Monitor multiple Claude Code instances across different projects

Features

Everything you need to stay connected to your Claude Code sessions from anywhere in your home or office.

Real-Time Streaming

Live terminal output with full ANSI color rendering. Every tool call, every file edit, as it happens. Session output buffered up to 4 MB so reconnecting clients get full history.

Permission Approvals

Claude Code permission prompts show as native iOS cards with tool name, command preview, and risk level badges. Allow, deny, or always-allow from your phone.

End-to-End Encrypted

X25519 key exchange with XChaCha20-Poly1305 authenticated encryption. Your code never touches any server in plaintext. Keys stored in Keychain.

Voice Input

Dictate responses to Claude using speech-to-text with dual-language support. Double-tap Command on Mac to start. Auto-commits once enough text is detected.

Away Detection

Multi-signal presence detection using BLE proximity, keyboard/mouse idle time, and screen lock state. Balcony knows when you've stepped away and queues notifications.

Multi-Session Support

Monitor multiple Claude Code instances across different projects simultaneously. Sessions show attention indicators when a prompt is waiting.

Interactions

Three types of interactive prompts, each rendered as native UI on both Mac and iOS. The first response from any surface wins - terminal, Mac panel, or iPhone.

Tool Permission Prompts

When Claude Code needs to run Bash, edit files, or perform other tool calls, structured hook events deliver risk-classified prompts to both Mac and iOS with native Allow/Deny/Always buttons.

Risk levels · Tool preview · Auto-dismiss

AskUserQuestion & Idle Prompts

When Claude asks a question or finishes and waits for input, Balcony shows an interactive card with the last message, selectable options, and a text input field. Keystrokes stream live to the PTY.

Idle detection · Multi-option · Live typing

Native iOS Command Pickers

Slash commands, model selection, session resume, rewind, and file references are presented as native iOS pickers. The Mac scans your project and sends available options to your phone.

/model · /resume · /rewind · @ files

Response Surfaces

Every prompt can be answered from three places. All responses are injected as PTY keystrokes, so the terminal is always the single source of truth.

Surface

Details

Terminal

Type directly in Claude Code as usual

Mac Panel

Floating NSPanel with buttons - doesn't steal keyboard focus

iPhone

Native iOS cards with tool info, risk badges, and buttons

Device Discovery

BonjourAuto-discovers Macs on the same Wi-Fi network via mDNS

Bluetooth LEClose-range discovery when Wi-Fi is unavailable

QR CodeScan a code from the Mac menu bar to pair instantly

Auto-reconnectRemembers last-connected device, reconnects on launch

Permissions

Risk levelsNormal (Read/Grep), elevated (Edit/Bash), destructive (rm/sudo)

Tool previewFull command or file path shown in the prompt card

Auto-dismiss200+ bytes of new PTY output dismisses the prompt

Questions

Idle detectionStop + Notification hooks trigger idle prompt cards

Multi-optionWizard-style panel with selectable choices and free-text Other

Live typingCharacters appear in the terminal as you type on your phone

Pickers

/modelNative picker for switching Claude models

/resumeSession picker for resuming previous conversations

/rewindTurn picker to navigate back in conversation history

@ filesProject file picker for inline file references

Architecture

Three native Swift components working in concert. A CLI that wraps the terminal, a Mac agent that bridges everything, and an iPhone app that puts it all in your pocket.

BalconyCLI

PTY Wrapper

Wraps Claude Code in a POSIX pseudoterminal. Raw terminal output flows through a Unix domain socket to BalconyMac. User input from iOS flows back the reverse path.

posix_openpt + posix_spawn, SIGWINCH forwarding, graceful cleanup

BalconyMac

Menu Bar Agent

A macOS menu bar agent that runs WebSocket + Bonjour + BLE servers, manages PTY sessions, listens for Claude Code hook events, and shows floating notification panels.

SwiftNIO WebSocket, NSPanel floating UI, Speech framework, Away detection

BalconyiOS

iPhone App

Discovers Macs, connects over encrypted WebSocket, renders terminal output as a native conversation view, detects prompts, and provides native UI for all interactions.

SwiftUI, HeadlessTerminalParser (SwiftTerm), CoreBluetooth, native pickers

Communication Layer

Unix domain sockets for local IPC, WebSocket for network transport, and end-to-end encryption for all data in transit.

Channel

Purpose

pty.sock

CLI to Mac: raw PTY output and input injection

hooks.sock

Hook handler to Mac: structured Claude Code events

WebSocket

Mac to iOS: encrypted session data and commands

Bonjour

Service advertisement for automatic device discovery

BLE

Proximity detection and close-range discovery fallback

Claude Code Hooks

Balcony integrates with Claude Code's hook system for structured event delivery. The setup wizard patches your settings automatically.

PermissionRequestTool approvals with risk classification and bidirectional response

StopSession completion detection for idle prompt triggering

NotificationIdle prompt correlation and attention indicators

PreToolUseAsync tool use tracking for real-time status updates

Language

Swift 5.9

Native on both platforms

Platforms

macOS 14+ / iOS 16+

Sonoma and newer

Networking

SwiftNIO

WebSocket server on Mac

Encryption

libsodium

via swift-sodium package

How It Works

A PTY wrapper captures terminal output, a Mac agent bridges it over encrypted WebSocket, and an iPhone app renders it natively.

Wrap

PTY pseudoterminal

BalconyCLI wraps Claude Code in a POSIX pseudoterminal. Raw terminal bytes flow through a Unix domain socket to the Mac agent.

Bridge

Mac menu bar agent

BalconyMac runs a WebSocket server, manages PTY sessions, listens for hook events, and shows floating notification panels on your Mac.

Hook

Claude Code events

Permission requests, stop events, and notifications flow through the hook handler script to the Mac agent via a second Unix socket.

Encrypt

X25519 + XChaCha20

All WebSocket traffic is end-to-end encrypted. Keys are exchanged during handshake and stored in Keychain. Your code never travels in plaintext.

Stream

WebSocket to iPhone

Terminal output, hook events, and session state are streamed to iOS in real time. Sessions buffer up to 4 MB so reconnecting clients get full history.

Interact

Native iOS UI

Terminal output is parsed into styled lines. Prompts are rendered as native cards. Responses flow back through WebSocket to PTY as keystrokes.

Get Started

Balcony is currently in private beta. Request TestFlight access to be among the first to try it. The Mac agent includes a guided setup wizard that handles everything.

Request TestFlight AccessComing Soon

Native Swift on both platforms. No Electron, no web views. Minimal resource usage with a menu bar agent that has no Dock icon.

View on GitHub↗

Requirements

macOS 14.0 (Sonoma) or later

iOS 16.0 or later

Claude Code installed and authenticated

Same Wi-Fi network (or Bluetooth for pairing)

Setup Wizard

The Mac agent includes a first-launch wizard that handles all configuration automatically.

1. Install CLIPlaces balcony wrapper in /usr/local/bin

2. Hook handlerInstalls hook-handler script to ~/.balcony/