---
name: use-disag
description: Use the disag command runner in this repository to run one or more commands concurrently, mirror stdout/stderr, write optional raw log files, and test or modify the JavaScript implementation.
---

# Disag

Use this skill when an agent needs to run, test, or modify this repository's `disag` command runner.

## Implementations

- `./disag` is the original rc implementation. Keep it unless the user explicitly asks to replace it.
- `./disag.js` is the JavaScript implementation. It is designed for Bun via its shebang, but uses Node-compatible APIs and can also be run with `node ./disag.js`.

## Usage

Run one or more commands concurrently:

```sh
./disag.js 'echo hello'
./disag.js 'node tests/fixtures/diag-helper.js emit out err' -f ./command.log -n CMD
./disag.js 'echo out; echo err >&2' -s -f ./command.log -n SHELL
```

Options apply to the immediately preceding command:

- `-f, --file <path>` writes raw stdout and stderr for that command to the named log file. If repeated, the last file wins.
- `-n, --name <name>` prefixes displayed lines with `[name]`; prefixes are not written to log files.
- `-s, --shell` runs that command through `sh -c`. Use it only when shell syntax is required.
- `-z, --no-color` disables ANSI color on displayed stdout.
- `-h, --help` prints usage.
- Each command prints a display-only stderr line of the form `[DISAG] <name-or-command> exited with exit code <status>` when it exits. Use `-n` as the short name in that line when available; otherwise use the command text.

## Constraints

- By default, `./disag.js` tokenizes the command string into argv and invokes the executable directly. Shell syntax such as redirection, pipes, variables, and compound commands requires `-s/--shell`.
- Do not introduce implicit shell wrappers, named temporary files, fifos, or filesystem writes outside the paths explicitly passed with `-f`.
- For signal forwarding, prefer direct process APIs and `kill` semantics. The JavaScript implementation uses detached child process groups and forwards signals to the group and child PID.
- Preserve separate stdout and stderr display streams. Log files intentionally contain raw lines from both streams without prefixes or color.
- The `[DISAG]` exit-code line goes to stderr only, is not written to `-f` logs, and should use the same ANSI color as that command's displayed output when color is enabled.

## Validation

Run these checks after changing the tool:

```sh
./tests/disag-js.rc
node ./disag.js 'echo node-ok' -n NODE
```

Run `./tests/disag.rc` only when changing or validating the original rc implementation.