pass

A personal macOS mission-control for Claude Code sessions across many projects.

Agents run on their own; only the sessions that need you surface — in one keyboard-driven panel you summon with a global hotkey. Answer a permission prompt or type a reply, and it goes straight into the session. Sessions live in tmux, so they survive pass restarts and you can tmux attach from any terminal.

Status: MVP (M0–M4) complete and verified end-to-end. Multi-agent adapters for Codex/pi are stubbed (the architecture is in place) but land in M5.

What works today

• Global hotkey (default ⌥Space) summons the panel over any app, any Space, without disruptively stealing your editor's focus. Resizable (drag edges; size is remembered) and toggleable between floating (always-on-top) and a normal window you keep beside your editor (⌘⇧F).
• Chat home — a feed of every session with its last response, and one input pinned at the bottom. Type to reply to the selected session (injected safely; refuses a bare shell), @ to jump to a project/session, y/n to answer a pending permission, ⏎/⌘⏎ to open its terminal.
• Interactive terminal — opening a session embeds a real terminal attached to its tmux session: type straight into Claude (keys, arrows, permission answers), full color and sizing. ⌘[ steps back to the home; ⌘⏎ opens it in Ghostty.
• Agentic embedded browser — the page beside a session is both human-visible and controllable through passcli. An agent can open, take a compact interactive snapshot, then use stable @eN references to click, fill, type, select, press, and scroll; screenshot and read close the visual verification loop. Commands act on the same persistent WKWebView the user sees, without exposing arbitrary JavaScript execution.
• Hooks-driven attention — Claude permission prompts / questions / completions arrive via Claude Code hooks; the selected session surfaces at the top with what it needs and how long it's waited (worktree badge, branch, agent glyph).
• tmux-backed sessions — created by pass or adopted from existing pass-* sessions; each is attachable from any terminal. Worktrees group under their main repo but show a ⧉ badge.
• Projects — register a single repo, a parent folder (scanned for repos), or several at once (menu / Settings); live sessions' projects are remembered automatically.
• Executable feature documents — keep software feature contracts in <project>/.pass/features/*.json, launch their local development server, follow a human test guide, ask a local agent to implement or verify the contract, and send failed human-review feedback back for rework. Agent summaries, changed files, checks, review history, and lifecycle status stay in JSON so they can be committed or synced later.
• Notifications for permission / input / finished, with the menu-bar badge as a reliable always-on fallback.
• Settings (⌘,): rebind the hotkey, launch-at-login, floating toggle, project list, install hooks, notification status, and build/review extensions with an AI agent.
• Extensions (v1) — add your own features as manifest+script extensions in ~/.pass/extensions: >commands in the quick command (⌘P) and event rules (attention/session → script/notify/sendText/openURL), with per-capability permissions and an enable-after-review flow. Ships with an agent-usage example (>usage — Claude Code token usage by day/model/project). Web UI windows (apiVersion 2) render extension-owned HTML/CSS/JS in a separate macOS window with a constrained snapshot/event/action JSON bridge; the bundled event-monitor example opens with >events. AI Extension Builder turns a natural-language goal into a disabled Claude work session, then shows every generated file and permission for feedback or explicit fingerprint approval. Enabled extensions also appear in the Pass panel's top launcher and the macOS menu-bar menu. Design & schema: docs/EXTENSIONS.md.
• Attached device pane — Vysor-style video for Android and iOS devices inside the running session's terminal workspace. Android supports basic pointer control over USB/Wi-Fi and emulators; install its runtime once with brew install scrcpy ffmpeg. iPhone and iPad use macOS's native trusted-USB capture path with no extra runtime: connect and unlock the device, accept Trust This Computer, and allow Pass camera access when macOS asks. iOS mirroring is view-only because iOS doesn't expose a general-purpose remote touch API. The divider is draggable and an open browser tab remains available when the device pane closes. Pass never captures a Mac window, so Screen Recording permission is not required. Use the device button in a session header or menu bar → Attach device pane….
• Mobile remote developer preview — an outbound-only macOS gateway, Cloudflare Worker/Durable Object relay, and Expo client can list/create sessions, send messages, and answer decisions. The current shared-token pairing is explicitly development-only; device-key pairing and voice are still follow-up work.

Build & run

Requires Xcode 26+, xcodegen (brew install xcodegen), tmux, and a free Apple Development signing identity. See BUILD.md for details and the hard-won platform findings.

make run      # build + launch (stdout in terminal)
make open     # build + launch the .app bundle (Finder-style)
make test     # run unit tests
make logs     # stream the app's OSLog

First-time setup (in the app)

The first launch opens a three-step setup assistant:

1. Runtime check — detects tmux (required) and Git (recommended). If Homebrew is available, Pass can install tmux in place and re-detect it without an app restart; otherwise it opens the Homebrew installation guide.
2. Agent check — detects Claude Code, Codex, and pi independently. Only one is needed; missing optional agents link to their official installation guides.
3. Integrations — installs Claude hooks by merging them into ~/.claude/settings.json (backed up first; never touches other hooks) and links the bundled passcli.

The assistant can be reopened any time from the menu bar. If notifications are blocked, enable Pass in System Settings. Summon with the shortcut selected in Settings (⌘⌘ or ⌥Space), @ to jump, or use New session… from the menu bar.

Mobile remote developer preview

The implementation and its security boundary are documented in docs/mobile-remote-architecture.md. Relay setup lives in relay/README.md, and Expo setup lives in mobile/README.md. No relay is deployed automatically.

Steam Deck client

deck/ contains a controller-first SteamOS remote client. Agents run on an internet-connected Pass host while the Deck connects through the existing relay protocol for session discovery/creation, terminal input, messages, and structured permission answers. See deck/README.md for setup and Deck controls.

How it fits together

Claude Code (in tmux)  ──hooks(HTTP)──►  HookServer (127.0.0.1:49817)
                                              │  normalize (ClaudeAdapter)
                                              ▼
   TmuxClient ◄── reconcile ──  SessionStore ──►  EventRouter ──►  Inbox + Notifications
   (create/adopt/attach)         (git identity,        (state machine)      ▲
        ▲                         attention)                                │
        └──────────── ReplyInjector (bracketed paste / y-n) ◄── panel (SwiftUI) ──┘

• The core is agent-agnostic: agent knowledge lives only in adapters (ClaudeAdapter today; /hook/<agent>, @pass_agent, and per-agent glyphs are already wired for Codex/pi in M5).
• tmux + git are the database — pass persists only a small project MRU list; everything else (cwd, branch, worktree, agent, activity) is derived live.
• Feature JSON is the contract — the app and local agents read and update the same repository files. A generated .pass/feature.schema.json supports validation; project-relative paths keep documents portable, and local development commands run only after an explicit click.

Executable feature workflow

1. Open pass › Features, choose a project, and create or edit a feature.
2. Add requirements, observable acceptance criteria, a development command/URL, and a short human test guide. The feature is saved as a reviewable JSON file in the project.
3. Choose Implement or Verify. pass starts (or reuses) a local agent session and gives the JSON file as its contract. The agent writes its summary, changed paths, check evidence, and needsReview/blocked status back into that file.
4. Choose Start server, open the local URL, and follow the guide. If behavior is wrong, enter feedback under Human review and request changes; pass records it and sends it to the agent.
5. Only a person can choose Mark verified.

Design docs & findings

• spikes/FINDINGS.md — empirical validation of Claude hooks, tmux injection, and the GUI/PATH environment (the S0 spikes that de-risked the architecture before any Swift was written).
• BUILD.md — build/signing setup and platform gotchas (notification signing, non-activating panel collectionBehavior, tmux -F control-byte escaping, accessory-app edit shortcuts).
• docs/BROWSER.md — implemented embedded browser design: the terminal │ WKWebView split and the passcli snapshot/ref/action protocol that lets agents open, inspect, and operate the same page the user sees.
• docs/mobile-remote-architecture.md — implemented developer MVP status plus the secure pairing, hardening, and voice-management roadmap for mobile access.