| name | muxrun-init |
| description | Analyze the current repository and generate a tailored muxrun.toml. Use when the user wants to start using muxrun in a project that has no config yet, or asks to "set up muxrun" / "generate muxrun.toml" / "initialize muxrun". |
muxrun-init
Generate a working muxrun.toml for the current repository by inspecting the codebase, then validate it with muxrun check.
When to invoke
- The user asks to set up / initialize / bootstrap muxrun in a project.
- No
muxrun.toml exists in the current directory or any ancestor.
- The user wants a starter config they can edit.
If a muxrun.toml already exists, ask whether to overwrite, augment, or abort before proceeding.
Procedure
-
Confirm prerequisites.
- Run
muxrun --version to confirm the CLI is installed. If missing, point the user at the install instructions in README.md and stop.
- Run
find . -maxdepth 3 -name muxrun.toml to detect existing configs.
-
Discover runnable processes. Investigate the repository for long-running dev processes. Useful signals:
package.json → scripts.dev, scripts.start, scripts.watch (per-package in monorepos: check pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, top-level workspaces).Procfile, Procfile.dev → each line is an app.docker-compose.yml / compose.yml → services with command and working_dir (note: prefer /muxrun-import-compose if Compose is the source of truth).Makefile → targets like dev, run, serve, watch.- Go:
main.go files (find . -name main.go -not -path '*/vendor/*'); each is a candidate app.
- Python:
manage.py runserver, uvicorn/fastapi entrypoints in pyproject.toml/setup.cfg.
- Rust:
[[bin]] entries in Cargo.toml.
- Static frontends:
vite, next, astro, remix, nuxt configs.
.env, .env.example to understand required vars (do NOT copy secrets into the config).
-
Group apps sensibly. A group is a tmux session and shares one dir. Reasonable defaults:
- One group per top-level concern:
backend, frontend, infra, worker.
- In a monorepo, a group per workspace package is also valid; prefer the smaller number of groups that still keeps
dir shared.
- Do not put apps with different working directories in the same group — split them.
-
Decide watch settings. Enable watch only for apps that benefit from live restart (servers, workers). Leave watch = false (the default — omit the field) for one-shot or already-self-reloading processes (vite, next dev, nodemon, air).
- When enabling watch, add an
exclude list. Always start from project signals: read .gitignore, look for node_modules/, dist/, build/, .next/, target/, vendor/, __pycache__/, test fixtures (testdata/), generated mocks. Exclude patterns are Go regex matched against paths relative to the group dir.
- Common defaults to consider:
_test\\.go$, mock_.*\\.go$, \\.tmp$, node_modules/, \\.next/, dist/, target/.
-
Write muxrun.toml. Place it at the repository root (or wherever the user is). Use relative dir = "." style paths so the config travels well across worktrees (see docs/config.md). Naming rules: group/app names must match ^[a-zA-Z0-9_-]+$ with no duplicates within scope.
-
Validate. Run muxrun check (or muxrun -c <path> check). Fix any reported errors. If muxrun check is unavailable, validate by re-reading the file and confirming the rules in docs/config.md.
-
Report. Show the user:
- The generated config and where it was written.
- Apps you considered but skipped, with one-line reasons (e.g., "ran tests, not a long-running process").
- Suggested next step:
muxrun up.
Reference
The full configuration schema, validation rules, and watch semantics are in config.md (symlink to the canonical docs). Treat that file as the source of truth — do not invent fields.
Anti-patterns
- Do not invent a
port, env, or depends_on field. Those don't exist in muxrun.toml.
- Do not enable watch on processes that already have live reload — you'll fight the inner loop.
- Do not group apps with different
dir values together.
- Do not include secrets from
.env in the generated config.
