Skip to content

CLAUDE.md

Latest commit

 

History

History
119 lines (101 loc) · 8.44 KB

CLAUDE.md

File metadata and controls

119 lines (101 loc) · 8.44 KB
Raw

cmux agent notes

Keep repo-wide decisions here; procedures belong in CONTRIBUTING.md, area instructions and task skills. Read the matching skill before changing an area, then only the references needed.

Manaflow AI team members and their agents: read the private cmuxterm-hq CLAUDE.md and AGENTS.md before fleet or CI work. They are the entry point for fleet builds, CI routing, agent coordination, and landing rules. Start fleet work at Fleet and CI: start here. External contributors can ignore this block; those links return 404 for them.

Verification and isolation

  • Before committing, setup or a native build, choose scoped verification. Start with python3 scripts/verify-local.py; docs and portable tooling need no app build. Run repository commands only in a trusted checkout, including verify-local.py --help, --list and --repo. Push does not run checks for you.
  • Use CONTRIBUTING.md for setup. Outside cmuxterm-hq-created checkouts, set CMUX_DEV_BACKEND_MODE=local for dev builds. Follow tagged builds for commands and cache reuse; team fleet tasks start at Fleet and CI: start here. Never use bare xcodebuild or an untagged cmux DEV.app. Clean up only your own tags.
  • A same-repo app PR gets a fleet dogfood build and link comment only while it has the dev-build label. Add it when someone will dogfood the PR, not by default; under load the fleet builds the newest push, and the comment says how to build a skipped commit.
  • Never quit, kill, relaunch, replace or launch-profile the user's running cmux (/Applications/cmux.app, com.cmuxterm.app), including through a Release build or another bundle with that ID. Never set CMUX_ALLOW_REPLACING_RUNNING_CMUX; only the user may. Reproduce in a tagged build and attach profiling to its PID.
  • Dogfood through CMUX_TAG=<tag> scripts/cmux-debug-cli.sh, never /tmp/cmux-cli. Never report raw .app paths or file:// URLs.
  • App-linked code (Sources/, CLI/, TunnelExtension/ and their packages) must remain Swift 6.0 compatible.

Area instructions

Read these before working in their scope; nested files may not load automatically:

Contributions and publication

Before fixing a bug or adding a feature, search open upstream PRs by symptom or issue number. Prefer landing an outside contributor's existing PR; push fixups only when maintainer edits are allowed, and explain the changes. If using their approach in your own PR, credit them in every such commit with Co-authored-by using their commit email, link your PR from theirs and thank them. Let a human close it; never close an outside PR without a human-written explanation.

The server directories listed in LICENSE (web/, workers/ci-artifacts/, workers/iroh-v2/, workers/presence/, services/iroh-relay-minter/, cmux-tui/relays/cloudflare-do/) use the Business Source License, which needs every outside author's CLA grant. Do not merge a PR that changes those directories while CLA Assistant is red, and do not copy an outside contributor's work there under a Co-authored-by trailer unless that person has signed the CLA. Keep code that ships in the macOS or iOS app out of those directories.

Read STYLE.md before drafting or revising issues, PR descriptions, RFCs or progress updates. Fill the PR's ## Changelog section with one Added/Changed/Fixed/Removed line for user-visible changes, otherwise none. Do not edit CHANGELOG.md in feature PRs; release tooling owns it.

CI, review and merge

  • Commit the failing behavioral regression before its fix; record the same focused command's red and green results (testing policy). A bug-fix PR body names that command, its failure on the base and its pass on the head, then an ### Observed / Not run section: what you ran and saw, then what you only read or didn't run. gh-merge-green warns when a fix PR lacks it; it does not block.
  • Check executed tests on the current SHA; green skipped jobs do not establish coverage. Add full-ci only for a user-requested or agreed broad validation plan, naming the extra lanes and why (CI coverage).
  • Keep branches current locally with scripts/merge-main.sh; follow the merge-main guide and never force-push over its merge.
  • gh pr merge saying "base branch policy prohibits the merge" means the token lacks the workflow scope or GitHub timed out, not a rule: run gh auth refresh -h github.com -s workflow, or merge with gh api -X PUT repos/OWNER/REPO/pulls/N/merge -f merge_method=squash -f sha=SHA, which names the cause. Never --admin.
  • A first implementation pass ends with passed scoped verification and an open PR; do not watch CI or run speculative reviews by default.
  • Before opening a PR and before merging, check it against REVIEW.md (draft), the mistakes our review history keeps catching.
  • Before merging, use a review subagent, correctness first; a second model is not a review gate. Disclose skipped verification on the PR. main is nightly: fix forward, do not revert.
  • A PR merges when an independent review subagent passes it and it causes no red of its own; base reds, flakes and pending checks don't hold it. Don't wait for a person. Ship risky user-visible behavior behind a setting or Debug toggle and fix a bad default in the next nightly. Merge with gh-merge-green; merge freezes still hold. gh-merge-green still waits for the checks it requires; never get around it with --override or the API merge path. Follow dogfood and merge receipts. Notify with cmux notify when a socket is available.
  • A red base (main doesn't compile, or CI is red on every PR) is priority zero. Fix it directly in its own PR; don't note it and leave it for an owner.

Implementation rules by task

Use these existing owners instead of duplicating their checklists here:

Touching Read before editing
Typing paths, SwiftUI list/store boundaries, rendering, find layering, UTTypes or OS-specific bugs cmux-debugging
Packages, workspace groups, lockfiles or feature flags cmux-architecture
Submodules or GhosttyKit cmux-ghostty
User-facing strings, docs or help cmux-localization; report the localization audit
New cmux shortcuts cmux-keyboard-shortcuts
Tests or target wiring cmux-testing; run scripts/sync-test-wiring after adding, renaming or deleting a cmuxTests/ file
Multiple entrypoints or a bug that tests previously missed cmux-shared-behavior; share action/mutation paths, verify every entrypoint, and cover the missed repro

Remote CLI relay

For v2 socket methods and remote CLI changes, read relay authorization. RemoteRelayCommandPolicy defaults to deny. Allowlist only for a needed remote flow, scoped to the session's objects; command-bearing params stay denied on every method. The PR must analyze local command/content execution, access to unowned objects and local-state exposure, and include the required policy tests and ID scoping. Unsafe local effects must be redesigned. Never allowlist terminal spawn/respawn without live verification that it executes on the remote host. An allowlist addition without this analysis blocks review.