Contributing

We welcome contributions to AgentMux. This page covers how to set up, where the code lives, and the conventions we follow for the things that have hurt us the most when they were ignored.

Ways to contribute

Report bugs or request features on GitHub Issues
Fix outstanding issues
Improve the documentation
Star the repository

Please respect our Code of Conduct.

Getting started

Build from source — set up your dev environment
Create a feature branch from main
Make your changes
Submit a pull request

Branch naming

Use yourname/feature-description:

git checkout -b yourname/fix-terminal-scroll

Licensing of contributions

There is no contributor agreement to sign. Contributions are licensed under the project’s licence, Apache 2.0 (see License below), and you keep the copyright to your work.

Development workflow

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/agentmux.git
cd agentmux

# 2. Install dependencies
npm install

# 3. Create a feature branch
git checkout -b yourname/feature-name

# 4. Start the dev server (Vite + host hot-reload)
task dev

# 5. Make changes
#    - Frontend changes auto-reload
#    - Rust crates: task build:backend (or task build:host) and restart task dev

# 6. Run tests (see Building from Source → Tests)
npx vitest run
cargo test --workspace -- --test-threads=1

# 7. Add a changeset, then commit and push
scripts/changeset.sh patch "fix(term): what changed, for the changelog"
git commit -m "feat: description of change"
git push -u origin yourname/feature-name

# 8. Open a pull request on GitHub

Project structure

agentmux/
├── crates/launcher/          # Launcher: spawns the host and the sidecar, owns the Layer 1 reducer
├── crates/cef/               # Host: embeds Chromium via CEF, owns the OS window
├── crates/srv/               # Sidecar: app domain — workspaces / tabs / blocks / agents / sagas
├── crates/common/            # Shared library: path resolution, runtime mode, IPC types
├── crates/mcp/               # agentmux-mcp: the MCP server that gives agents MuxAPI
├── crates/bashwrap/          # Streaming bash wrapper + CLI hook helper
├── crates/remote/            # Helper installed on SSH hosts: durable sessions, remote files
├── crates/procstats/         # Per-process CPU and memory for Tower
├── frontend/                 # SolidJS + TypeScript renderer (Vite)
│   ├── app/view/             # Pane view implementations (term, browser, agent, drone, …)
│   ├── app/block/            # Block / pane rendering + registry
│   ├── app/store/            # State management (Solid signals and stores, slice reducers, RPC client)
│   └── app/element/          # Reusable UI components
├── docs/                     # Specs, plans, status documents
│   └── specs/                # Architecture specs (read these for design context)
├── schema/                   # JSON schema definitions
└── Taskfile.yml              # Build tasks

Where to look

You’re touching	Start here
A new pane type	`frontend/app/view/<view>/` + `frontend/app/block/block.tsx` to register
RPC commands the frontend calls	`crates/srv/src/server/app_api/mod.rs` (high-level) or the per-domain handler files
Window / pool / OS state	`crates/launcher/src/reducer/` + `docs/specs/`
Browser pane behavior	`frontend/app/view/browser/` + `crates/cef/src/browser_pane/`
Persistence	`crates/srv/src/persist*.rs`, `crates/srv/src/sagas/`, `crates/launcher/src/event_log.rs`
Reducer-stack work	`docs/specs/MASTER_REDUCER_STACK_STATUS_2026-05-05.md` and Discussion #707 — append PRs and analyses there, don’t fork threads

Style

Language: American English
Formatting: Prettier + EditorConfig (npx prettier --write <files>; there is no task format)
TypeScript: strict mode; prefer narrow return types; avoid any
Rust: cargo fmt + cargo clippy --workspace -- -D warnings before pushing

Pull request guidelines

Branch from main; don’t commit directly to main
Link the relevant issue or spec in the PR body — every architectural change should reference a spec or discussion thread
Add a changeset (see Version management); the changeset check fails a PR without one
For minor changes (a typo, a one-line fix), open a PR directly
For major changes (a new pane type, a reducer slice, a saga refactor), open an issue or comment on Discussion #707 first

Reviews

Every PR is auto-reviewed by:

muxreview (muxreview[bot]) — surfaces P1/P2/P3 issues; addresses correctness, missing tests, and consistency
chatgpt-codex-connector[bot] — second-opinion review focused on code quality and architecture. Codex isn’t run on every push: muxreview asks it once muxreview has approved a commit, and again only when a push could change its answer. The Codex review status on the PR shows where that stands.

Address every CHANGES_REQUESTED finding from muxreview. Codex inline comments are P2-level signal — read both /pulls/N/comments (inline) and /issues/N/comments (top-level).

To ask for another Codex pass, comment @muxreview codex re-review on the PR. Codex only responds to requests from the maintainer account, so a direct @codex review from anyone else is ignored — muxreview relays the request for you.

State-machine discipline

If your change touches the reducer stack or a saga:

Read docs/specs/MASTER_REDUCER_STACK_STATUS_2026-05-05.md first
For new slices, follow frontend-reducer-conventions-2026-05-03.md (Command/event types, slot lifecycle, audit, echo-loop guard)
Test inputs MUST replay the production emit order; out-of-order tests give false confidence
Property test inputs MUST pass the SUT’s filter — add an anti-vacuity assertion before the property loop

These rules are written into the AgentA team’s working memory because they each cost real PR rounds. The reducer-stack maintainers will push back hard on changes that don’t follow them.

Version management

Feature PRs don’t change version numbers. Each PR adds one changeset, a small file in .changesets/ that says what changed, for the changelog:

scripts/changeset.sh patch "fix(term): what changed, for the changelog"
# or: task changeset -- patch "..."

type is patch, minor or major. Commit the file it writes with your change; the changeset check fails a PR without one. The version moves only in a release commit: task release folds the pending changesets into VERSION_HISTORY.md and bumps the version files. See .changesets/README.md in the repo, and Local build labels for how local builds are labelled without a bump.

License

AgentMux is licensed under Apache-2.0. By contributing, you agree that your contributions will be licensed under the same terms.