Chimlo

The macOS activity island for coding agents.
Watch Codex and Claude Code work, respond when they need you, then get back to your flow.

Install · Features · Changelog · Connect agents · Architecture · Contribute

---

Long-running agents should not make you babysit a terminal. Chimlo turns the top of your display into a small, local control surface: active work stays visible, questions and approvals arrive where you can act on them, and completed work is easy to reopen.

✨ Features

• 🤖 Live agent sessions. Follow concurrent Codex and Claude Code work, including what is active, waiting, done, or failed.
• ❓ Claude questions in place. Read the real multiple-choice prompt and send the selected option back to the blocked session.
• 🛡️ Scoped Claude approvals. Inspect the requested tool action, then deny it, allow it once, or allow it for the current session. Bypass mode is never exposed.
• 📊 Real provider capacity. See Codex and Claude usage windows from provider-owned runtime data, without reading credentials or inventing percentages.
• 🍎 Native macOS. Chimlo is built with AppKit and SwiftUI. There is no Electron shell and no web view.
• 🎵 A useful notch between tasks. Media playback plus volume and brightness feedback share the same compact surface.
• 🖥️ Display-aware behavior. The island adapts to notched displays, external monitors, the menu bar, fullscreen media, Reduce Motion, and increased contrast.
• 👾 Animated pixel companions. Original characters make idle, working, waiting, completed, and failed states recognizable at a glance.
• 🔌 Safe agent setup. Previewed, marker-scoped hook installation preserves unrelated Codex and Claude Code configuration and removes only Chimlo's entries.
• 🔒 Local and private. Prompts, transcripts, permission previews, and session details are not sent to a Chimlo service. There is no telemetry by default.

📦 Install

Chimlo requires macOS 14 or newer. The current release supports Apple silicon Macs.

1. Download the latest Chimlo-*.dmg from GitHub Releases.
2. Open the DMG and drag Chimlo into Applications.
3. Eject the Chimlo disk image, then open Chimlo from Applications.

Updates

Release builds check for signed updates every hour. When a newer published release is available, Chimlo shows Update to latest version in the island. Click it once to download, verify, install, and relaunch the app. Chimlo keeps the same release bundle identifier, so existing app preferences remain in place.

First launch

Chimlo is not yet notarized by Apple. If macOS blocks the first launch, open System Settings > Privacy & Security, scroll to Security, then click Open Anyway for Chimlo. Confirm with your Mac password when prompted. Apple documents this process in Open a Mac app from an unknown developer.

On first launch, complete the short onboarding tour. Chimlo then automatically discovers supported local Codex and Claude Code sessions; no manual connection step is required for session activity.

Allow Accessibility permission

Accessibility permission is required for Chimlo's volume and brightness controls and helps it recognize active fullscreen media.

1. Install Chimlo in Applications and open it from there.
2. Open Chimlo Settings > General.
3. Under Volume and brightness, enable Show in Chimlo and click Allow.
4. In System Settings > Privacy & Security > Accessibility, enable Chimlo.
5. Return to Chimlo and click Retry if the status has not updated.

Without this permission, agent activity remains available and macOS keeps its native volume and brightness controls.

Build from source

You need Xcode or the Xcode Command Line Tools with a Swift 6 toolchain.

git clone https://github.com/kraten/chimlo.git
cd chimlo

# One-time local signing setup
make signing-identity

# Package and open the separately identified local build
make app
open "dist/Chimlo Dev.app"

The source build is named Chimlo Dev and uses its own bundle identifier, so macOS lists it separately from a release copy of Chimlo in Accessibility settings. Each app can therefore keep its own permission toggle.

Why the local signing step matters

make signing-identity creates a dedicated local keychain, imports a non-exportable private key, and restricts the certificate to code signing. This keeps Chimlo's designated code requirement stable between local builds, so macOS does not repeatedly forget its Accessibility permission.

You can skip the step for an ad-hoc build, but permission may need to be granted again when the executable changes. Run make signing-check to verify that two separate builds keep the same designated requirement.

Develop locally

make build
make test
make check
./Scripts/swift.sh run ChimloApp

make test runs the Swift test suites. make check runs Chimlo's deterministic layout, protocol, and behavior checks.

Public releases are built and signed locally, then the exact DMG and signed appcast.xml are uploaded to a draft GitHub release. GitHub Actions does not rebuild or re-sign the artifact, and the private Sparkle key stays in the release Mac's Keychain. Maintainers should follow the complete release procedure.

🔌 Connect Codex and Claude Code

Chimlo combines app-server events, process liveness, incremental local metadata, and command hooks. No cloud connection is required.

Client	What Chimlo installs
Codex	Marker-scoped observers in ~/.codex/hooks.json for task lifecycle updates.
Claude Code	Marker-scoped observers plus the blocking AskUserQuestion and PermissionRequest bridges in ~/.claude/settings.json.

Every install starts with a complete preview and explicit confirmation. Chimlo preserves unrelated configuration, creates a one-time backup, validates the result, and removes only its own marked entries during uninstall.

Read Agent hook setup for the full install, recovery, and uninstall behavior.

🔒 Privacy and safety

Chimlo is designed so that the terminal remains authoritative.

• Question text, answers, permission paths, and action previews exist only in memory while the interaction is active.
• The local registry deliberately omits prompt and response content.
• Hook traffic uses an authenticated loopback protocol with per-launch tokens and bounded message framing.
• A missing app, timeout, authentication failure, or transport error never implies approval. Claude Code falls back to its native terminal UI.
• Capacity comes from the existing Codex app-server connection and Claude Code's documented status-line or /usage surfaces. Chimlo does not read provider credentials.

See the protocol specification for the wire format and fail-closed behavior.

🏗️ Architecture

Chimlo keeps its platform code, transport, and domain model in narrow modules:

flowchart LR
    CLI["ChimloCLI<br/>Hooks and dev events"] --> Protocol["ChimloProtocol<br/>Authenticated loopback"]
    App["ChimloApp<br/>AppKit and SwiftUI"] --> Protocol
    CLI --> Core["ChimloCore<br/>Domain values and reducer"]
    App --> Core
    Protocol --> Core

Loading

• ChimloCore owns deterministic session, interaction, retention, capacity, and layout rules.
• ChimloProtocol owns authenticated local transport and its wire schema.
• ChimloApp owns the macOS lifecycle, panel placement, discovery adapters, settings, and SwiftUI views.
• ChimloCLI receives agent hooks and provides development event injection.

Read the architecture guide for the dependency boundaries and runtime data flow.

🤝 Contributing

Contributions are welcome. Start with the contributing guide and code of conduct, then open an issue or pull request.

• Report a bug
• Request a feature
• Join a discussion

📜 License

Chimlo is free and open-source software licensed under GPL-3.0. Product and integration names remain the property of their respective owners.