# marsh manual

marsh is a shell for composing agents on Apple Silicon Macs. It opens your
project in Linux at its Mac path, runs registered agent commands in fresh
containers, and lets you combine their work with shell syntax.

## Getting started

- [Install](https://runmar.sh/docs/install.md): requirements, installation methods, upgrades, removal.
- [Quickstart](https://runmar.sh/docs/quickstart.md): one agent job on a project copy to find the
  repository's test command and verify its source.

## Guides

- [Make independent changes in parallel](https://runmar.sh/docs/guides/race-two-agents.md): give
  each task a project copy and bring the patches back yourself.
- [Review a change with a panel](https://runmar.sh/docs/guides/review-with-a-panel.md): ask two
  reviewers different questions about the same diff.
- [Let an agent farm out work](https://runmar.sh/docs/guides/farm-out-work.md): have an agent start
  one bounded child job from its shell tool.
- [Review split results in a pipeline](https://runmar.sh/docs/guides/add-a-judge.md): send results
  to another agent for an optional second opinion.
- [Set up your marsh home](https://runmar.sh/docs/guides/set-up-your-home.md): skills, dotfiles,
  shared and per-Kit MCP servers and extra mounts.

## Using marsh

- [The shell](https://runmar.sh/docs/shell.md): guest paths, startup files, Bash compatibility.
- [Using bash or zsh instead](https://runmar.sh/docs/shells.md): shell selection and startup files.
- [Commands and Kits](https://runmar.sh/docs/kits.md): packaged commands and your own registrations.
- [Agents running agents](https://runmar.sh/docs/agents.md): child jobs, launch limits, cancellation.
- [Split and join](https://runmar.sh/docs/split.md): project copies and patch handling.
- [Fanout and collect](https://runmar.sh/docs/fanout.md): parallel commands on shared files.
- [Agent sessions (ACP)](https://runmar.sh/docs/acp.md): long-lived sessions for ACP clients.
- [MCP](https://runmar.sh/docs/mcp.md): server setup and published pipelines.

## Reference

- [Configuration](https://runmar.sh/docs/configuration.md): settings and paths.
- [Troubleshooting](https://runmar.sh/docs/troubleshooting.md): refused jobs, stuck VMs, cleanup.
- [Security model](https://runmar.sh/docs/security.md): process authority and isolation boundaries.
- [FAQ](https://runmar.sh/docs/faq.md): costs, authentication, comparisons with other tools.
- `man marsh`: command options ([source](https://runmar.sh/docs/marsh.1.md)).

## Working on marsh

- [CONTRIBUTING.md](https://github.com/mcavage/marsh/blob/main/CONTRIBUTING.md): build and test loop.
- [Design documents](https://runmar.sh/docs/design/index.md): architecture, contracts, TLA+ model.
- [GitHub Discussions](https://github.com/mcavage/marsh/discussions): Kits
  and recipes from other users.