WAIT — Mixed signals — read the receipts

• Last commit today
• 4 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

cmux is a native macOS terminal built on Ghostty that adds vertical tabs, AI agent notifications, and an embedded browser for coding workflows. It solves the problem of managing multiple terminal panes and tracking long-running AI agent tasks by providing visual notification rings on panes/tabs when agents need attention, plus a unified notification panel to jump to unread updates. Hybrid monorepo: core terminal UI lives in Swift (main application layer), with Python backends for agent communication and scripting (1.9M LOC), TypeScript for browser integration (627K LOC), and Go utilities (213K LOC). The .claude/commands/ directory houses Claude agent automation commands, suggesting the project itself uses AI for development. Asset organization via Assets.xcassets/ (Xcode standard) and structured workflows in .github/workflows/.

AI engineers and developers running coding agents (Claude, o1, etc.) who need to monitor multiple terminal sessions simultaneously without constant manual checking. Teams building or using AI agents that emit status updates need better visibility than stock terminal multiplexers provide.

Actively developed and production-ready. The repo shows mature CI/CD with GitHub Actions workflows (ci.yml, release.yml, nightly.yml), CircleCI integration, and structured release processes (release-local.md, release.md, release-nightly.md commands in .claude/). With 12.6M lines of Swift and 1.9M Python, it's a substantial codebase with comprehensive review rules (.github/review-bot-rules/) enforcing code quality standards around concurrency, logging, and architecture.

Low-to-moderate risk for a specialized tool. It's tightly coupled to macOS (Ghostty-based, native Swift), limiting portability. The large Swift codebase (12.6M LOC) concentrates maintenance burden, though the .github/swift-file-length-budget.tsv and warning budgets suggest active effort to prevent technical debt accumulation. No indication of security vulnerabilities in visible files, but the embedded browser component is a potential attack surface.

Active development cycle with nightly builds (nightly.yml workflow), Homebrew integration updates (update-homebrew.yml), performance activation testing (perf-activation.yml), and E2E test expansion (test-e2e.yml). The presence of cloud-vm-migrate.yml and cloud-vm-smoke.yml suggests recent infrastructure evolution. Multiple release channels (local, nightly, production) indicate rapid iteration.

Clone and build with Xcode:

git clone https://github.com/manaflow-ai/cmux.git
cd cmux
# Install Swift dependencies via Xcode
open cmux.xcodeproj
# Or build via command line
xcodebuild -scheme cmux -configuration Release

For Python backend dependencies, check requirements files in the Python subdirectory (inferred from 1.9M LOC).

Daily commands: Xcode build:

xcodebuild -scheme cmux -configuration Debug -derivedDataPath build
./build/Build/Products/Debug/cmux.app/Contents/MacOS/cmux

Or run from Xcode: Cmd+R. For testing: xcodebuild test -scheme cmux. Check .github/workflows/ci.yml for the authoritative CI build commands.

• .github/workflows/ci.yml: Defines the complete CI pipeline including build, test, and lint stages — essential for understanding the development workflow and required checks.
• .github/review-bot-rules/swift-actor-isolation.md: Core architectural constraint: enforces Swift actor-based concurrency throughout the codebase, critical for understanding thread-safety patterns in this multi-process terminal app.
• .github/swift-file-length-budget.tsv: Specifies file size limits per Swift component, revealing the logical module boundaries and code organization strategy.
• .claude/commands/release.md: Documents the release automation process including versioning, signing, and distribution — important for understanding deployment flow.
• .github/workflows/test-e2e.yml: Defines end-to-end test strategy for the terminal UI and agent notification system, showing how integration testing is structured.
• AGENTS.md: Likely documents the agent protocol and integration points — essential reference for understanding how AI agents communicate with cmux.
• .gitmodules: Reveals git submodule dependencies (including Ghostty), critical for understanding external dependencies and build prerequisites.

For UI changes: edit Swift files in the main Xcode project (notification ring rendering likely in a PaneView or NotificationView component). For agent integration: modify Python backend (structure inferred from 1.9M LOC — likely under a python/ or backend/ directory). For browser features: edit TypeScript in the browser integration layer. For system notifications: check review rule swift-concurrent-annotation.md and swift-actor-isolation.md as this repo enforces strict concurrency. Start by exploring the Xcode project structure and following the architectural patterns in .github/review-bot-rules/.

1. macOS-only: No Windows/Linux support (native Swift + Ghostty dependency). 2) Submodule dependencies: .gitmodules indicates git submodules (likely Ghostty); must use git clone --recursive or run git submodule update --init --recursive after cloning. 3) Code signing: macOS DMG distribution requires valid codesigning certificates and provisioning profiles (check .github/workflows/release.yml for signing step). 4) Swift version: Review-bot rules suggest Swift 5.9+ with strict concurrency enabled (-warn-concurrency flag); older Xcode versions will fail. 5) Python environment: 1.9M LOC of Python suggests backend daemon; verify Python 3.8+ is available and dependencies installed via pip. 6) Homebrew integration: update-homebrew.yml workflow suggests tap maintenance; if modifying formulas, requires credentials.

• Swift Actor Isolation & Concurrency — cmux enforces strict actor-based concurrency (reviewed in .github/review-bot-rules/swift-actor-isolation.md) to prevent data races in a multi-pane, multi-session terminal; fundamental to understanding thread safety in this codebase.
• Terminal Control Sequences (ANSI/VT100) — cmux wraps Ghostty which interprets terminal escape sequences; understanding ANSI codes is essential for debugging pane rendering, color output, and notification ring state synchronization.
• Process Communication (IPC) — The hybrid Swift/Python architecture requires inter-process communication between the macOS UI and Python agent daemon; critical for notification flow and command execution.
• SwiftUI State Management & View Composition — The notification rings, sidebar git info, and port listeners are stateful SwiftUI views; understanding @State, @Binding, and custom view hierarchy patterns is required for UI modifications.
• macOS App Lifecycle & Entitlements — cmux is a native macOS app requiring specific entitlements for clipboard access, file system monitoring, and notification permissions; seen in code signing workflow (.github/workflows/release.yml).
• Notification Pattern Observer (Pub/Sub) — The notification ring system likely uses Swift Combine publishers or NotificationCenter to broadcast agent status changes; understanding this pattern helps implement new alert types or integrations.
• Ghostty Terminal Emulator Protocol — As a Ghostty wrapper, cmux communicates with the terminal engine via specific APIs for session management, pane creation, and output capture; understanding this interface is critical for lower-level troubleshooting.

• vercel-labs/agent-browser — Direct upstream: the embedded browser component in cmux is explicitly ported from this Vercel labs project (mentioned in README). Reference for browser API design.
• ghostty-org/ghostty — Core terminal engine underlying cmux; understanding Ghostty's architecture helps with terminal event handling and escape sequence processing in the parent project.
• tmux/tmux — Spiritual predecessor in terminal multiplexing space; cmux improves on tmux's UX with vertical tabs and AI-aware notifications for the modern agent-driven workflow.
• zellij-org/zellij — Alternative Rust-based terminal multiplexer with similar goals (pane management, visual feedback); competitor for understanding the terminal multiplexing design space.
• manaflow-ai/cmux-docs — Likely companion repo for user documentation and guides (inferred from README references to 'The Zen of cmux' blog); separate from main codebase for deployment flexibility.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E tests for vertical tabs and agent notification workflows

The repo has .github/workflows/test-e2e.yml configured but no visible E2E test suite in the file structure. Given that cmux's core value propositions are vertical tabs and AI agent notifications (per README), these workflows lack automated test coverage. This would catch regressions in the Ghostty integration and agent notification delivery.

• [ ] Create Tests/E2E/VerticalTabsTests.swift to validate tab creation, switching, and persistence
• [ ] Create Tests/E2E/AgentNotificationTests.swift to test notification triggers for different agents (Claude, Codex, OpenCode, HermesAgent)
• [ ] Update .github/workflows/test-e2e.yml to run these Swift XCTest suites in CI
• [ ] Add test fixtures in Tests/Fixtures/ for mock agent responses and notification payloads

Implement review-bot rules enforcement for Swift concurrency in Agent-related code

The repo has extensive review-bot rules (.github/review-bot-rules/swift-concurrency-modernization.md, swift-actor-isolation.md, etc.) but no automated enforcement visible in CI. Given that cmux handles concurrent agent communication, adding linter rules would prevent data races and improve code quality. This bridges the gap between documented rules and actual PR validation.

• [ ] Create a GitHub Action workflow (.github/workflows/review-bot-enforcement.yml) that parses review-bot rules and validates PRs against them
• [ ] Specifically target files in agent-related modules that deal with concurrent notifications (likely in Sources/ related to AGENTS.md capabilities)
• [ ] Add automation to comment on PRs that violate swift-actor-isolation or swift-concurrent-annotation rules
• [ ] Document the enforcement process in .github/review-bot-rules/README.md with examples

Add comprehensive agent integration documentation and API specs

The repo references AGENTS.md and has asset folders for agent icons (Claude, Codex, OpenCode, HermesAgent) but lacks specific integration documentation. New contributors cannot easily understand how to add a new agent or what the agent notification protocol expects. This is a blocker for community contributions.

• [ ] Expand AGENTS.md with sections: Agent Registration, Notification Protocol, Required Fields, and Example Implementation
• [ ] Create docs/AGENT_INTEGRATION_GUIDE.md with step-by-step instructions to add a new agent (referencing Assets.xcassets/AgentIcons structure)
• [ ] Document the notification payload schema (JSON or Swift Codable struct) that agents must conform to
• [ ] Add code examples showing how agents like Claude integrate with cmux's notification system

• Add missing unit tests for the notification ring rendering system. The codebase has strict SwiftUI state layout rules (.github/review-bot-rules/swiftui-state-layout.md) but notification UI logic likely lacks comprehensive test coverage for edge cases like simultaneous multi-pane notifications.: High-visibility feature with clear test criteria; improves code stability and demonstrates testing patterns to new contributors.
• Document the Python agent protocol in AGENTS.md. The 1.9M Python LOC suggests a structured agent communication system, but new developers can't integrate custom agents without clear API documentation (port numbers, message format, authentication).: Documentation-only, unblocks future contributors and reduces onboarding friction; requires no deep codebase knowledge.
• Add performance regression tests for the notification panel with 100+ pending notifications. The perf-activation.yml workflow hints at performance concerns; benchmark the notification deduplication and sorting logic to catch slowdowns in future commits.: Addresses existing infrastructure (perf-activation.yml) and prevents real user pain; good opportunity to learn the notification system architecture.

The cmux codebase demonstrates moderate security posture. Primary concerns are the incomplete visibility of dependencies for vulnerability assessment, potential credential exposure in CI/CD workflows and command scripts, and the need for proper secret management in GitHub Actions. The macOS/Swift application itself lacks visible injection vulnerabilities in the provided file structure, but comprehensive analysis requires access to source code files. Recommendations focus on hardening CI/CD pipelines, implementing proper secret management, and ensuring dependency visibility and security scanning.

• Medium · Potential Hardcoded Credentials in Claude Commands — .claude/commands/ (pull.md, release-local.md, release-nightly.md, release.md, sync-branch.md). The .claude/commands directory contains release and deployment scripts that may handle credentials or sensitive information. These files should not be committed if they contain actual secrets, API keys, or authentication tokens. Fix: Review all command files to ensure no credentials are hardcoded. Use environment variables or secure credential management systems for sensitive data. Add patterns to .gitignore for any local config files containing secrets.
• Medium · GitHub Actions Workflow Security — .github/workflows/ (release.yml, ci.yml, nightly.yml, build-ghosttykit.yml, etc.). Multiple GitHub Actions workflows exist (.github/workflows/) that may have insufficient secret management, permission scoping, or third-party action vulnerabilities. Workflows like release.yml, ci.yml, and nightly.yml require careful review to prevent token leakage or privilege escalation. Fix: Implement least-privilege access for workflow permissions. Use GitHub's OIDC token provider instead of personal access tokens. Pin third-party action versions to specific commits. Regularly audit workflow logs for unexpected access patterns.
• Low · Incomplete Dependency Visibility — Project root (missing Package.swift, Podfile, or similar). No package manager files (Package.swift, Podfile, package.json, etc.) were provided in the analysis, making it impossible to assess dependency vulnerabilities. Swift and iOS projects may have unvetted dependencies. Fix: Provide complete dependency manifests for analysis. Regularly run dependency vulnerability scanners. Use Swift Package Manager security features and keep all dependencies updated.
• Low · CI/CD Configuration Exposure — .circleci/config.yml and .github/workflows/. CircleCI configuration (.circleci/config.yml) and various CI workflow files are present in the repository. While this is normal, ensure no sensitive environment variables or credentials are logged in build outputs. Fix: Ensure CI/CD platforms are configured to mask secrets in logs. Use separate service accounts for CI/CD with minimal permissions. Enable audit logging on all CI/CD platforms.
• Low · Third-party Integration Dependencies — .coderabbit.yaml, .greptile/config.json, .circleci/config.yml. The project integrates with multiple external services (CodeRabbit, Greptile, CircleCI, GitHub Actions) based on configuration files. Each integration requires proper authentication and authorization. Fix: Verify all third-party integrations use OAuth2 or token-based authentication. Regularly audit integration permissions and revoke access for unused integrations. Use dedicated API keys per integration.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/manaflow-ai/cmux shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live manaflow-ai/cmux repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/manaflow-ai/cmux.

What it runs against: a local clone of manaflow-ai/cmux — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in manaflow-ai/cmux | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of manaflow-ai/cmux. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/manaflow-ai/cmux.git
#   cd cmux
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of manaflow-ai/cmux and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "manaflow-ai/cmux(\\.git)?\\b" \\
  && ok "origin remote is manaflow-ai/cmux" \\
  || miss "origin remote is not manaflow-ai/cmux (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/manaflow-ai/cmux"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.