🤖 feat: add background bash process execution with SSH support #920
Conversation
ethanndickson
force-pushed
the
background-process-file-storage
branch
2 times, most recently
from
0c99075 to
92ef0c8
Compare
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
abc50fe to
99af592
Compare
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
36ea849 to
c14210c
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
228b9dd to
6d815be
Compare
…ests" This reverts commit f6ac07c.
The bash tool blocks commands starting with 'sleep' to prevent wasting time. Changed test commands from 'sleep 30' to 'true && sleep 30' to bypass this validation while still testing background process behavior.
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
b2e8055 to
211d10c
Compare
bash_background_terminate returns { message: ... } not { output: ... }
- Replace platform-specific PGID detection with universal fallback chain: ps -o pgid= → /proc/$!/pgid → PID (works on Linux, macOS, MSYS2) - Use numeric signals (-15, -9) instead of named (-TERM, -KILL) for MSYS2 compat - Extract parsePidPgid() helper to backgroundCommands.ts (DRY) - Simplify LocalBackgroundHandle.terminate() from ~90 to ~17 lines - Remove Windows-specific conditional code - Now uses buildTerminateCommand via bash shell (same as SSH) - Add PGID parameter to SSHBackgroundHandle for proper process group termination _Generated with mux_
Without job control, backgrounded processes inherit the parent's PGID. On Linux locally, this caused 'kill -PGID' to kill mux itself. Adding 'set -m' enables bash job control, which creates a new process group for backgrounded processes (PID === PGID), making it safe to kill. _Generated with mux_
With set -m, PID === PGID is guaranteed (process is its own group leader).
Remove the redundant PGID lookup chain (ps → /proc → fallback) and use
just the PID throughout.
- buildSpawnCommand: echo $! instead of PGID lookup
- parsePidPgid → parsePid: return number instead of {pid, pgid}
- Remove pgid field from LocalBackgroundHandle and SSHBackgroundHandle
- Clean up tests: 46 → 20 tests, remove redundant assertions
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
dacdda9 to
df15f39
Compare
The EXIT trap in the process writes $? (which is 0 for SIGTERM) and would overwrite our exit code if we wrote it immediately. Now we wait for the process to exit before writing 143 (SIGTERM) or 137 (SIGKILL).
kill -0 ${pid} only checks if the parent is alive, but children may
survive SIGTERM. Changed to kill -0 ${negPid} to check if any process
in the group is still alive before deciding to send SIGKILL.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 43 out of 45 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Use execFileSync with args array in toPosixPath to avoid shell injection - Add 5s timeout to app dispose to ensure quit even if disposal hangs - Log warning when SSH /home/ethan resolution fails and falls back to /tmp - Add random suffix to test markers to prevent collision
ethanndickson
force-pushed
the
background-process-file-storage
branch
2 times, most recently
from
8064cbd to
54cd503
Compare
- Test that child processes are terminated when parent is killed (validates set -m) - Test that display_name round-trips through spawn and list
ethanndickson
force-pushed
the
background-process-file-storage
branch
from
54cd503 to
badae77
Compare
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
### Stack: 1. #923 <- This PR 1. #920 (base) --- Adds custom UI components for background bash tools: - **BashToolCall**: Shows `⚡ background • display_name` for background spawns instead of timeout/duration; shows output file paths in expanded view - **BashBackgroundListToolCall**: New component showing process list with status badges, exit codes, uptimes, scripts, and output file paths - **BashBackgroundTerminateToolCall**: New component showing terminated process with display_name from result <img width="984" height="946" alt="image" src="https://github.com/user-attachments/assets/3de5a0bb-6c00-4641-96cb-65c67e3d0085" /> **Testing:** Manually tested on Linux, Mac, and Windows. Closes #493 _Generated with mux_
1 participant
Stack:
🤖 feat: add UI styling for background bash processes #923
🤖 feat: add background bash process execution with SSH support #920 (base) <- This PR
Summary
Adds
run_in_background=trueoption to the bash tool, enabling agents to spawn long-running processes (dev servers, builds, file watchers) that persist independently.Why This Approach
We needed background process support that works identically for both local and SSH runtimes. A few considerations drove the design:
PTY-based output doesn't fit remote use cases. For SSH, maintaining a persistent PTY connection just to let agents read stdout would be fragile and complex. Agents need to search, filter, and tail output—not consume a live stream.
File-based output lets agents use standard tools. By writing stdout/stderr to files on the target machine, agents can use
tail -f,grep,head, etc. to inspect output. We don't need to reimplement these filtering capabilities in our own tooling.A proper long-lived remote daemon is future work. Ideally, SSH remotes would have a persistent mux process (or agent binary) that manages background jobs directly. The user's frontend would just connect to it. That's a significant architectural change. This PR provides background shell support without requiring that investment—the file-based approach works today with no remote-side dependencies.
Architecture
Key Design Decisions
tail/cat/grep.exit_codefile on list()Tools
bash(run_in_background=true)— spawns process, returnsstdout_path/stderr_pathbash_background_list— lists processes with status and file pathsbash_background_terminate— kills process group (SIGTERM → wait → SIGKILL)Output Structure
Technical Details
Process Spawning
The spawn command uses a subshell with job control enabled:
Key elements:
set -m— Enables bash job control, which makes backgrounded processes become their own process group leader (PID === PGID). This is a bash builtin available on all platforms.nohup— Prevents SIGHUP from killing the process when the terminal closes.(...)— Isolates the process group so the outer shell exits immediately after echoing the PID.< /dev/null— Detaches stdin so the process doesn't block waiting for input.Exit Code Detection
The wrapper script sets up a trap to capture the exit code:
When the process exits (normally or via signal), the trap writes
$?to theexit_codefile. Mux reads this file to determine if the process is still running (exit_codedoesn't exist) or has exited (file contains the code).Process Group Termination
Because
set -mensures PID === PGID, we can kill the entire process tree using a negative PID:Sequence:
-15) to the process group (-PIDtargets the group)kill -0 -PID)-9) and record exit code 137This ensures child processes spawned by the background job are also terminated, preventing orphaned processes.
Cross-Platform Compatibility
set -mkill -15/-9 -PIDnohupcygpathUsing
set -minstead of platform-specific tools likesetsid(Linux-only) ensures the same code works everywhere.Platform Support
Testing
backgroundProcessManager.test.ts(including process group termination)bash.test.tsbash_background_list.test.ts(including display_name)bash_background_terminate.test.tsbackgroundCommands.test.tstests/runtime/runtime.test.ts(Local & SSH)tests/ipc/backgroundBash.test.ts(real AI calls)Manual Testing
Tested on Linux, macOS, and Windows (MSYS2) to verify:
Generated with mux