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 | | --- | --- | | bash_start | Start a command in the background | | bash_status | Check status, get new output (long-poll supported) | | bash_kill | Kill a running process | | bash_stdin | Write to a process's stdin | | bash_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: bash_start("npm run build")
  → { id: "pk7qx", pid: 1234 }

agent: bash_status("pk7qx")
  → { status: "running", newOutput: "compiling 42/100..." }

agent: (reviews a PR while the build runs)

agent: bash_status("pk7qx", { wait: 5000 })
  → { status: "done", newOutput: "...built in 12s", exitCode: 0 }

Run tests while fixing another file

bash_start("pytest tests/ -v")
  → { id: "pm2va", pid: 4521 }

# Agent edits src/auth.py while tests run

bash_status("pm2va", { wait: 30000 })
  → { status: "done", newOutput: "48 passed, 2 failed in 12.3s", exitCode: 1 }

# Agent sees which tests failed, fixes them
bash_status("pm2va", { all: true })
  → { newOutput: "FAILED tests/test_login.py::test_expired_token..." }

Start a dev server and wait for it to be ready

bash_start("npm run dev")
  → { id: "pq9dx", pid: 8834 }

bash_status("pq9dx", { wait: 10000 })
  → { status: "running", newOutput: "Server running on http://localhost:3000" }

# Server is ready, agent can now test endpoints

Monitor a database migration

bash_start("npx prisma migrate deploy")
  → { id: "pz4mn", pid: 2291 }

bash_status("pz4mn", { wait: 15000 })
  → { status: "running", newOutput: "Applying migration 20240101_add_users..." }

bash_status("pz4mn")
  → { status: "done", newOutput: "3 migrations applied successfully.", exitCode: 0 }

Pipe input to an interactive script

bash_start("psql -U postgres mydb")
  → { id: "pa8kx", pid: 3301 }

bash_stdin("pa8kx", "SELECT count(*) FROM users WHERE active = true;")
bash_status("pa8kx")
  → { newOutput: " count\n-------\n   847\n(1 row)" }

Stdin

Send input to running processes, useful for interactive scripts, REPLs, and CLIs:

bash_start("python manage.py shell")
  → { id: "ph3tq", pid: 6612 }

bash_stdin("ph3tq", "from django.contrib.auth.models import User")
bash_stdin("ph3tq", "User.objects.filter(is_active=False).count()")
bash_status("ph3tq")
  → { 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 unless needed; PowerShell escapes with backtick (`), not backslash
• ; | & < > { } 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() | Yes | Set eof: true after optional data | | Python readlines() | Yes | Set eof: true after optional data | | PowerShell Read-Host | Yes | | | PowerShell $input pipe | No | Known limitation |

API

bash_start(command, opts?)

| Param | Type | Default | Description | | --- | --- | --- | --- | | command | string | required | Shell command | | workdir | string | cwd | Working directory | | timeout | number | 0 | Process timeout in ms; 0 disables timeout (unlimited) |

Returns: { id, pid, status }

bash_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 | Reset pagination and return output from beginning |

Returns: { id, status, exitCode, newOutput, totalOutputSize, truncated, hasMore, elapsed }

Statuses: running done killed error timed_out

bash_kill(id)

Running process: "Process X terminated." Already exited: "Process X already exited with status 'done' (exit code 0)."

bash_stdin({ id, data?, eof? })

Write optional data to stdin. Newline auto-appended if missing. Set eof: true to close stdin after data and signal EOF. Close-only call: bash_stdin({ id: "pk7qx", eof: true }).

bash_list()

Returns all processes with ID, PID, command, status, exit code, output size, elapsed time.

Development

bun install
bun test
bun run build        # dist/
bun run typecheck

License

MIT