Better Bash

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:

{
  "plugin": ["better-bash"]
}

MiMoCode

Add to ~/.config/mimocode/mimocode.json:

{ 
  "plugin": ["better-bash"] 
}

From Source

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:

agent: bash("npm run build")
agent: ... waits 45 seconds doing nothing ...
agent: "Build complete!"

With better-bash:

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

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

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

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

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:

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

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
• Source: 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.