A living mascot that floats above your windows, reacts to Claude Code and Codex, and lets you handle everything without leaving your flow.
Download Β· Website Β· Custom Mascots
--- ## Features | | Feature | Description | |---|---|---| | π | **Animated overlay** | A mascot that floats above all windows and reacts to Claude Code + Codex state β click or hover to interact | | π | **Permission handling** | Approve, deny, or defer tool use requests from a speech bubble β select with `β1-9`, permissions stack in a queue | | π¬ | **Question answering** | Answer Claude's questions directly from the overlay | | π | **Plan review** | Review and approve plans without opening your terminal | | π | **Session tracking** | Monitor active sessions, subagents, and status at a glance | | π | **Notification dashboard** | Priority levels, resolution tracking, color-coded activity feed | | π₯οΈ | **Find the right terminal** | Jump to the correct terminal tab β supports 13 terminals and IDEs including iTerm2, Ghostty, VS Code, Cursor, and more | | π | **Session switcher** | Double-tap `β` to switch between assistant sessions | | π΄ | **Snooze** | Right-click to hide the mascot for 15 min, 1 hour, or indefinitely | | βοΈ | **Resizable** | Drag to resize or pick a preset (S / M / L / XL) from the context menu | | π | **Auto-updates** | Built-in Sparkle updates β always on the latest version | ## How It Works ``` βββββββββββββββ hook events βββββββββββββββ β Claude/Codex β βββββββββββββββββββΆ β Masko β β (terminal) β β (menu bar) β βββββββββββββββ βββββββββββββββ β β β streams events from hooks/logs, β updates mascot animation, β sessions, notifications β shows permission prompts, β β tracks sessions βΌ βΌ ~/.claude/settings.json local HTTP :49152 ``` 1. **Download the app** β Install the DMG. Lives in your menu bar, no dock clutter. 2. **Grant accessibility** β First launch installs Claude Code hooks automatically into `~/.claude/settings.json`. 3. **Pick a mascot** β Choose the default Masko or bring your own from [masko.ai](https://masko.ai). 4. **Start coding** β Open Claude Code or Codex (CLI/Desktop). Your mascot springs to life. ## Keyboard Shortcuts All shortcuts work globally β no need to focus the app. | Shortcut | Action | |---|---| | `βM` | Toggle dashboard (customizable in Settings) | | `β1-9` | Select Nth pending permission | | `βEnter` | Approve selected permission | | `βEsc` | Deny / dismiss permission | | `βL` | Collapse / defer topmost permission | | `Double-tap β` | Open session switcher (2+ sessions) | | `β / β` | Navigate session switcher | | `Tab / Shift+Tab` | Cycle sessions | | `Enter` | Confirm session selection | | `Esc` | Close session switcher | The focus toggle shortcut can be rebound to any key combination in Settings. Right-click the mascot to open the **context menu** β snooze, resize, or close the overlay. ## Custom Mascots The default Masko fox is included. Want your own character? Create one on [masko.ai](https://masko.ai) with AI-generated animations for every state (idle, working, attention). Export and load it into the desktop app in one click. ## Supported Terminals & IDEs Masko works with terminals that run Claude Code or Codex. Terminal focus (`βM`) support varies by app: | Level | App | How | |---|---|---| | **Exact tab** | VS Code, VS Code Insiders, Cursor, Windsurf, Antigravity | IDE extension (auto-installed) | | **Exact tab** | iTerm2, Terminal.app | AppleScript TTY matching | | **App focus** | Ghostty, Kitty, WezTerm, Alacritty, Warp, Zed | Process activation | Click a session in the dashboard or click the mascot overlay to jump to the right terminal. ## Requirements - macOS 14.0+ (Sonoma) - Apple Silicon or Intel Mac - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or [Codex CLI](https://github.com/openai/codex) installed ## Install Download the latest `.dmg` from [**Releases**](https://github.com/RousselPaul/masko-code/releases/latest). ## Build from Source ```bash git clone https://github.com/RousselPaul/masko-code.git cd masko-code swift build swift run ``` ## Local Codex Smoke Test Boot Masko from source in one terminal: ```bash swift run masko-code ``` Run a live Codex mascot flow in another terminal: ```bash scripts/codex-mascot-smoke.sh --manual ``` Run the automated 3-step integration check instead: ```bash scripts/codex-mascot-smoke.sh --auto ``` The automated mode verifies that Masko ingests: - a Codex question turn as `AskUserQuestion` - an escalated approval turn with a persistent `prefix_rule` suggestion - the final completion marker without blank notifications or question-only completion events The automated mode drives Codex through its own PTY and verifies Masko ingestion. Use `--manual` if you want to inspect the overlay yourself while the prompts are live. ## Project Structure ``` Sources/ βββ App/ # App entry point & lifecycle βββ Models/ # Data models (sessions, events, hooks) βββ Services/ # HTTP server, hook installer, update checker βββ Stores/ # Observable state (sessions, notifications) βββ Views/ # SwiftUI views (overlay, permission prompt, dashboard) βββ Utilities/ # Helpers βββ Resources/ # Assets, images, app icon scripts/ # DMG packaging scripts extensions/ βββ vscode/ # VS Code/Cursor click-to-focus extension βββ jetbrains/ # JetBrains (PyCharm, IntelliJ, etc.) terminal focus plugin ``` ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved. ## License [MIT License](LICENSE) β Copyright (c) 2026 Masko. --- > **Note:** This project has no cryptocurrency or token associated with it. Any coin using the Masko or Clippy name is not affiliated with us.