# neur0map/pikochan architecture

> Architecture diagram of the GitHub repository neur0map/pikochan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neur0map/pikochan
- Repository: https://github.com/neur0map/pikochan

## Overview

PikoChan is a native macOS AI companion presented through the MacBook notch. The main interaction runs from the notch UI through its manager to the brain, which generates a response; the manager then presents it and coordinates suggested or approved actions. Separate capabilities cover voice, music, awareness and scheduled jobs, setup/configuration, and MCP integrations. The graph uses README claims and the supplied source index/excerpts; unsampled implementation details are represented cautiously, and unverified links are omitted.

Main entry points: [`PikoChan/Core/NotchManager.swift`](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/NotchManager.swift) (Interaction manager), [`PikoChan/Core/Brain/PikoBrain.swift`](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoBrain.swift) (LLM brain), [`PikoChan/Core/Skills/PikoActionHandler.swift`](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoActionHandler.swift) (Action approvals), [`PikoChan/Views/NotchContentView.swift`](https://github.com/neur0map/pikochan/blob/main/PikoChan/Views/NotchContentView.swift) (Notch interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Notch interaction"]
  node_notchview["Notch interface"]
  node_manager["Interaction manager<br/>[NotchManager.swift]"]
  node_feed["Activity feed"]
end

subgraph group_intelligence["Brain and memory"]
  node_brain["LLM brain<br/>[PikoBrain.swift]"]
  node_mood["Mood parser<br/>[MoodParser.swift]"]
  node_memory["Semantic memory<br/>[PikoMemory.swift]"]
  node_brainstore[("Conversation store<br/>[PikoStore.swift]")]
  node_gateway["Event gateway<br/>[PikoGateway.swift]"]
end

subgraph group_capabilities["Companion capabilities"]
  node_actionhandler["Action approvals"]
  node_terminal["Terminal control<br/>[PikoTerminal.swift]"]
  node_browser["Browser control<br/>[PikoBrowser.swift]"]
  node_skills["Markdown skills"]
  node_voice["Voice I/O<br/>[PikoSTT.swift]"]
  node_tts["Speech synthesis<br/>[PikoTTS.swift]"]
  node_music["Now playing"]
  node_heartbeat["Awareness monitor"]
  node_cron["Scheduled jobs"]
end

subgraph group_configuration["Setup and settings"]
  node_setup["First-run setup<br/>[SetupManager.swift]"]
  node_config["Configuration store"]
  node_keychain[("Credential storage<br/>[PikoKeychain.swift]")]
end

subgraph group_integrations["External integrations"]
  node_mcp["MCP manager"]
  node_provider{{"Model providers"}}
  node_os{{"macOS services"}}
end

node_user(("Mac user"))

node_user -->|"interacts with"| node_notchview
node_notchview -->|"drives"| node_manager
node_manager -->|"requests response"| node_brain
node_brain -->|"queries models"| node_provider
node_brain -->|"parses mood"| node_mood
node_brain -->|"extracts facts"| node_memory
node_brain -->|"uses history"| node_brainstore
node_brain -->|"logs events"| node_gateway
node_manager -->|"updates feed"| node_feed
node_manager -->|"parses actions"| node_actionhandler
node_actionhandler -->|"executes approved"| node_terminal
node_actionhandler -.->|"opens URLs"| node_browser
node_brain -->|"loads abilities"| node_skills
node_manager -->|"transcribes audio"| node_voice
node_manager -->|"speaks responses"| node_tts
node_manager -->|"observes playback"| node_music
node_manager -->|"starts monitoring"| node_heartbeat
node_heartbeat -->|"requests nudges"| node_brain
node_manager -->|"coordinates jobs"| node_cron
node_cron -->|"runs commands"| node_terminal
node_setup -->|"saves setup"| node_config
node_config -->|"stores credentials"| node_keychain
node_manager -->|"starts manager"| node_mcp
node_mcp -->|"generates skill"| node_brain
node_music -->|"detects playback"| node_os
node_voice -.->|"captures audio"| node_os

click node_notchview "https://github.com/neur0map/pikochan/blob/main/PikoChan/Views/NotchContentView.swift"
click node_manager "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/NotchManager.swift"
click node_feed "https://github.com/neur0map/pikochan/blob/main/PikoChan/Views/Feed/ActivityFeedView.swift"
click node_brain "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoBrain.swift"
click node_mood "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/MoodParser.swift"
click node_memory "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoMemory.swift"
click node_brainstore "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoStore.swift"
click node_gateway "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoGateway.swift"
click node_actionhandler "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoActionHandler.swift"
click node_terminal "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoTerminal.swift"
click node_browser "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoBrowser.swift"
click node_skills "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoSkillLoader.swift"
click node_voice "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Voice/PikoSTT.swift"
click node_tts "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Voice/PikoTTS.swift"
click node_music "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Music/PikoNowPlaying.swift"
click node_heartbeat "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/PikoHeartbeat.swift"
click node_cron "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Cron/PikoCronService.swift"
click node_setup "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/SetupManager.swift"
click node_config "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoConfigStore.swift"
click node_keychain "https://github.com/neur0map/pikochan/blob/main/PikoChan/Utilities/PikoKeychain.swift"
click node_mcp "https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/MCP/PikoMCPManager.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notchview,node_manager,node_feed,node_user toneBlue
class node_brain,node_mood,node_memory,node_brainstore,node_gateway toneAmber
class node_actionhandler,node_terminal,node_browser,node_skills,node_voice,node_tts,node_music,node_heartbeat,node_cron toneMint
class node_setup,node_config,node_keychain toneRose
class node_mcp,node_provider,node_os toneIndigo
```

## Components

### Notch interaction

- [Notch interface](https://github.com/neur0map/pikochan/blob/main/PikoChan/Views/NotchContentView.swift): `PikoChan/Views/NotchContentView.swift`
- [Interaction manager](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/NotchManager.swift): `PikoChan/Core/NotchManager.swift`
- [Activity feed](https://github.com/neur0map/pikochan/blob/main/PikoChan/Views/Feed/ActivityFeedView.swift): `PikoChan/Views/Feed/ActivityFeedView.swift`

### Brain and memory

- [LLM brain](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoBrain.swift): `PikoChan/Core/Brain/PikoBrain.swift`
- [Mood parser](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/MoodParser.swift): `PikoChan/Core/Brain/MoodParser.swift`
- [Semantic memory](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoMemory.swift): `PikoChan/Core/Brain/PikoMemory.swift`
- [Conversation store](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoStore.swift): `PikoChan/Core/Brain/PikoStore.swift`
- [Event gateway](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoGateway.swift): `PikoChan/Core/Brain/PikoGateway.swift`

### Companion capabilities

- [Action approvals](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoActionHandler.swift): `PikoChan/Core/Skills/PikoActionHandler.swift`
- [Terminal control](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoTerminal.swift): `PikoChan/Core/Skills/PikoTerminal.swift`
- [Browser control](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoBrowser.swift): `PikoChan/Core/Skills/PikoBrowser.swift`
- [Markdown skills](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Skills/PikoSkillLoader.swift): `PikoChan/Core/Skills/PikoSkillLoader.swift`
- [Voice I/O](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Voice/PikoSTT.swift): `PikoChan/Core/Voice/PikoSTT.swift`
- [Speech synthesis](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Voice/PikoTTS.swift): `PikoChan/Core/Voice/PikoTTS.swift`
- [Now playing](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Music/PikoNowPlaying.swift): `PikoChan/Core/Music/PikoNowPlaying.swift`
- [Awareness monitor](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/PikoHeartbeat.swift): `PikoChan/Core/PikoHeartbeat.swift`
- [Scheduled jobs](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Cron/PikoCronService.swift): `PikoChan/Core/Cron/PikoCronService.swift`

### Setup and settings

- [First-run setup](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/SetupManager.swift): `PikoChan/Core/SetupManager.swift`
- [Configuration store](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/Brain/PikoConfigStore.swift): `PikoChan/Core/Brain/PikoConfigStore.swift`
- [Credential storage](https://github.com/neur0map/pikochan/blob/main/PikoChan/Utilities/PikoKeychain.swift): `PikoChan/Utilities/PikoKeychain.swift`

### External integrations

- [MCP manager](https://github.com/neur0map/pikochan/blob/main/PikoChan/Core/MCP/PikoMCPManager.swift): `PikoChan/Core/MCP/PikoMCPManager.swift`
- **Model providers**
- **macOS services**

### Other components

- **Mac user**

## Connections

- Mac user → Notch interface: interacts with (evidence: `README.md`)
- Notch interface → Interaction manager: drives (evidence: `PikoChan/Views/NotchContentView.swift`)
- Interaction manager → LLM brain: requests response (evidence: `PikoChan/Core/NotchManager.swift`)
- LLM brain → Model providers: queries models (evidence: `README.md`)
- LLM brain → Mood parser: parses mood (evidence: `PikoChan/Core/Brain/PikoBrain.swift`)
- LLM brain → Semantic memory: extracts facts (evidence: `PikoChan/Core/Brain/PikoBrain.swift`)
- LLM brain → Conversation store: uses history (evidence: `PikoChan/Core/Brain/PikoBrain.swift`)
- LLM brain → Event gateway: logs events (evidence: `PikoChan/Core/Brain/PikoBrain.swift`)
- Interaction manager → Activity feed: updates feed (evidence: `PikoChan/Core/NotchManager.swift`)
- Interaction manager → Action approvals: parses actions (evidence: `PikoChan/Core/NotchManager.swift`)
- Action approvals → Terminal control: executes approved (evidence: `PikoChan/Core/Skills/PikoActionHandler.swift`)
- Action approvals → Browser control: opens URLs (evidence: `PikoChan/Core/Skills/PikoActionHandler.swift`)
- LLM brain → Markdown skills: loads abilities (evidence: `README.md`)
- Interaction manager → Voice I/O: transcribes audio (evidence: `PikoChan/Core/NotchManager.swift`)
- Interaction manager → Speech synthesis: speaks responses (evidence: `PikoChan/Core/NotchManager.swift`)
- Interaction manager → Now playing: observes playback (evidence: `PikoChan/Core/NotchManager.swift`)
- Interaction manager → Awareness monitor: starts monitoring (evidence: `PikoChan/Core/NotchManager.swift`)
- Awareness monitor → LLM brain: requests nudges (evidence: `PikoChan/Core/PikoHeartbeat.swift`)
- Interaction manager → Scheduled jobs: coordinates jobs (evidence: `PikoChan/Core/NotchManager.swift`)
- Scheduled jobs → Terminal control: runs commands (evidence: `PikoChan/Core/Cron/PikoCronService.swift`)
- First-run setup → Configuration store: saves setup (evidence: `PikoChan/Core/SetupManager.swift`)
- Configuration store → Credential storage: stores credentials (evidence: `PikoChan/Core/Brain/PikoConfigStore.swift`)
- Interaction manager → MCP manager: starts manager (evidence: `PikoChan/Core/NotchManager.swift`)
- MCP manager → LLM brain: generates skill (evidence: `PikoChan/Core/MCP/PikoMCPManager.swift`)
- Now playing → macOS services: detects playback (evidence: `README.md`)
- Voice I/O → macOS services: captures audio (evidence: `README.md`)