# Better Bash > Background process management for LLM coding agents — non-blocking bash with streaming output, stdin, and long-polling - **Type:** MCP server - **Install:** `agentstack add mcp-alper-dev-better-bash` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [alper-dev](https://agentstack.voostack.com/s/alper-dev) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [alper-dev](https://github.com/alper-dev) - **Source:** https://github.com/alper-dev/better-bash - **Website:** https://www.npmjs.com/package/better-bash ## Install ```sh agentstack add mcp-alper-dev-better-bash ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About better-bash Background process management for LLM coding agents Non-blocking bash with streaming output, stdin, and long-polling --- Your agent runs `npm run build` and waits. Does nothing. Watches output scroll by. Wastes tokens. better-bash fixes that. Five tools that turn blocking bash into background process management: the agent starts a command, does other work, checks back when it's ready. ## Install ### OpenCode Add to `~/.config/opencode/opencode.json`: ```json { "plugin": ["better-bash"] } ``` ### MiMoCode Add to `~/.config/mimocode/mimocode.json`: ```json { "plugin": ["better-bash"] } ``` ### From Source ```bash git clone https://github.com/alper-dev/better-bash.git cd better-bash bun install && bun run build ``` ## What You Get | Tool | Does | | --- | --- | | `bb_start` | Start a command in the background | | `bb_status` | Check status, get new output (long-poll supported) | | `bb_kill` | Kill a running process | | `bb_stdin` | Write to a process's stdin | | `bb_list` | List all running processes | ## Examples **Without better-bash:** ```text agent: bash("npm run build") agent: ... waits 45 seconds doing nothing ... agent: "Build complete!" ``` **With better-bash:** ```text agent: bb_start("npm run build") → { id: "p1", pid: 1234 } agent: bb_status("p1") → { status: "running", newOutput: "compiling 42/100..." } agent: (reviews a PR while the build runs) agent: bb_status("p1", { wait: 5000 }) → { status: "done", newOutput: "...built in 12s", exitCode: 0 } ``` ### Run tests while fixing another file ```text bb_start("pytest tests/ -v") → { id: "p1", pid: 4521 } # Agent edits src/auth.py while tests run bb_status("p1", { wait: 30000 }) → { status: "done", newOutput: "48 passed, 2 failed in 12.3s", exitCode: 1 } # Agent sees which tests failed, fixes them bb_status("p1", { all: true }) → { newOutput: "FAILED tests/test_login.py::test_expired_token..." } ``` ### Start a dev server and wait for it to be ready ```text bb_start("npm run dev") → { id: "p2", pid: 8834 } bb_status("p2", { wait: 10000 }) → { status: "running", newOutput: "Server running on http://localhost:3000" } # Server is ready, agent can now test endpoints ``` ### Monitor a database migration ```text bb_start("npx prisma migrate deploy") → { id: "p3", pid: 2291 } bb_status("p3", { wait: 15000 }) → { status: "running", newOutput: "Applying migration 20240101_add_users..." } bb_status("p3") → { status: "done", newOutput: "3 migrations applied successfully.", exitCode: 0 } ``` ### Pipe input to an interactive script ```text bb_start("psql -U postgres mydb") → { id: "p4", pid: 3301 } bb_stdin("p4", "SELECT count(*) FROM users WHERE active = true;") bb_status("p4") → { newOutput: " count\n-------\n 847\n(1 row)" } ``` ## Stdin Send input to running processes, useful for interactive scripts, REPLs, and CLIs: ```text bb_start("python manage.py shell") → { id: "p5", pid: 6612 } bb_stdin("p5", "from django.contrib.auth.models import User") bb_stdin("p5", "User.objects.filter(is_active=False).count()") bb_status("p5") → { newOutput: ">>> 42" } ``` Newline is auto-appended if missing. ## Shell Quoting PowerShell uses Base64-encoded commands. Rules: - Use single quotes: `echo 'hello world'` - Avoid double quotes; they get backslash-escaped - Backtick is PowerShell's escape char, not literal - `; | & { }` work fine for chaining - `$HOME` expands, so wrap in single quotes to prevent ## Stdin Compatibility | Consumer | Works | Notes | | --- | --- | --- | | Python `input()` | Yes | Newline auto-appended | | Python `readline()` | Yes | Newline auto-appended | | Python `read()` | No | Blocks until EOF (by design) | | Python `readlines()` | No | Use `readline()` loop | | PowerShell `Read-Host` | Yes | | | PowerShell `$input` pipe | No | Known limitation | ## API ### `bb_start(command, opts?)` | Param | Type | Default | Description | | --- | --- | --- | --- | | `command` | string | required | Shell command | | `workdir` | string | cwd | Working directory | | `timeout` | number | 120000 | Process timeout in ms | Returns: `{ id, pid, status }` ### `bb_status(id, opts?)` | Param | Type | Default | Description | | --- | --- | --- | --- | | `id` | string | required | Process ID | | `maxOutput` | number | 30000 | Max bytes to return | | `wait` | number | 0 | Long-poll timeout in ms | | `all` | boolean | false | Return full output | Returns: `{ id, status, exitCode, newOutput, totalOutputSize, truncated, elapsed }` Statuses: `running` `done` `killed` `error` `timed_out` ### `bb_kill(id)` Running process: `"Process X terminated."` Already exited: `"Process X already exited with status 'done' (exit code 0)."` ### `bb_stdin(id, data)` Write to stdin. Newline auto-appended if missing. ### `bb_list()` Returns all processes with ID, PID, command, status, exit code, output size, elapsed time. ## Development ```bash bun install bun test # 32 tests bun run build # dist/ bun run typecheck ``` ## License MIT ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [alper-dev](https://github.com/alper-dev) - **Source:** [alper-dev/better-bash](https://github.com/alper-dev/better-bash) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/better-bash Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-alper-dev-better-bash - Seller: https://agentstack.voostack.com/s/alper-dev - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.