Welcome to Buddi
Relevant source files
The following files were used as context for generating this wiki page:
Buddi is a specialized macOS companion application designed to integrate deeply with Claude Code. It functions primarily as a "notch companion," utilizing the MacBook's camera notch area to provide real-time status updates, tool approval interfaces, and session monitoring for AI development workflows.
The system acts as a bridge between the CLI environment of Claude Code and the macOS desktop environment. By registering hooks that communicate via Unix domain sockets, Buddi captures events such as tool execution, thinking states, and permission requests, mapping these to visual animations and interactive UI components.
Sources: README.md:1-5, README.md:46-52
System Architecture and Integration
Buddi operates through a multi-layered communication stack. It intercepts Claude Code events using a Python-based hook system which forwards data to the main Swift application.
Communication Flow
The core logic follows a specific path:
- Claude Code triggers a lifecycle event (e.g.,
PreToolUse,PermissionRequest). - Buddi Hook (Python script) captures the event from
stdin. - Unix Socket (
/tmp/buddi.sock) carries the JSON-encoded state to the Buddi app. - Buddi App updates the Notch UI and Buddy character state.
Key Integration Components
| Component | Technology | Responsibility |
|---|---|---|
| Hook Script | Python 3 | Intercepts JSON events from Claude Code; handles TTY detection. |
| Socket Server | Unix Domain Socket | High-performance local IPC via /tmp/buddi.sock. |
| Session Monitor | Swift | Tracks multiple concurrent AI sessions and their phases. |
| Multiplexer Bridge | Tmux/Cmux | Sends keystrokes back to terminal sessions for interactive control. |
Sources: README.md:10-15, buddi/Buddi/Resources/buddi-hook.py:116-120, buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:42-45
Onboarding and Initialization
When a user first launches Buddi, the application initiates an onboarding sequence to establish necessary permissions and integration hooks.
Onboarding Workflow
The onboarding process is managed by OnboardingView, which guides the user through the following steps:
- Welcome: Introduction to the companion.
- Meet Buddy: Discovery of the user's unique system-generated character.
- Hooks Install: Installation of the Python scripts into the Claude Code environment.
- Permissions: Requesting access to Camera (for mirror), Calendar, Reminders, and Accessibility.
Buddy Identity Generation
Each "Buddy" character is unique to the user's system. The BuddyDetector uses Wyhash and Mulberry32 RNG to generate an identity based on the user's ID found in .claude.json.
- Species: 18 varieties including duck, cat, dragon, and axolotl.
- Rarity: Common, Uncommon, Rare, Epic, Legendary.
- States: Idle, Working, Reading, Sleeping, and Error (mapped to Claude Code phases).
Sources: README.md:20-25, buddi/Buddi/Buddy/BuddyDetector.swift:10-25
AI Session Monitoring
Buddi provides a detailed view of Claude Code activities through its monitoring services.
Event Mapping
The buddi-hook.py script maps Claude Code hook events to specific application statuses that drive the UI.
| Claude Event | Buddi Status | UI Behavior |
|---|---|---|
UserPromptSubmit | processing | Buddy enters "Working" state; visual thinking indicator appears. |
PermissionRequest | waiting_for_approval | Notch expands with Approve/Deny buttons. |
SessionStart | waiting_for_input | Buddy enters "Idle" state. |
PreCompact | compacting | Context compression notification. |
Sources: buddi/Buddi/Resources/buddi-hook.py:126-190
Conversation Parsing
The ConversationParser performs incremental parsing of JSONL files located in ~/.claude/projects/. This allows the application to show a real-time chat history without re-reading the entire file on every update.
Tool Approvals and Multiplexer Support
A critical feature of Buddi is the ability to approve or deny tool executions (like Bash or Write) directly from the macOS UI.
Tmux and Cmux Integration
If Claude Code is running inside a terminal multiplexer, Buddi uses ToolApprovalHandler to send control sequences back to the session.
- Approve Once: Sends
1+Enter. - Approve Always: Sends
2+Enter. - Reject: Sends
n+Enter.
// Example of sending approval keys to tmux
private func sendTmuxKeys(to target: TmuxTarget, keys: String, pressEnter: Bool) async -> Bool {
guard let tmuxPath = await TmuxPathFinder.shared.getTmuxPath() else { return false }
let textArgs = ["send-keys", "-t", target.targetString, "-l", keys]
_ = try await ProcessExecutor.shared.run(tmuxPath, arguments: textArgs)
if pressEnter {
let enterArgs = ["send-keys", "-t", target.targetString, "Enter"]
_ = try await ProcessExecutor.shared.run(tmuxPath, arguments: enterArgs)
}
return true
}
Sources: buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:15-35, buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:60-80
Conclusion
Buddi provides a seamless bridge between local AI CLI tools and the macOS desktop. By combining a character-driven animation system with technical integrations like Unix sockets and terminal multiplexer control, it enhances the developer experience when working with Claude Code. The system ensures that critical interruptions, such as permission requests, are handled with minimal friction while maintaining a high level of technical transparency through its live monitoring features.