Computers, terminal and Git

Manage background processes

Start a command that outlives a chat turn, follow its output, and stop it when you no longer need it.

Start one

Ask Chetty to run the command with run_in_background: true.
Note the process ID it returns; Chetty notifies you when the process finishes.
Continue with other work.

Set backgroundMode: "service" for a long-running server or watcher. The default background mode is job. Bash accepts only run_in_background for detached execution; the retired background argument is rejected.

Find and read a process

The Processes section of the chat rail shows running background processes and lets you inspect output or stop one.

ListProcesses lists the background processes started in this conversation.
ProcessOutput returns new output since the last read; set all: true for the retained output.
A read waits up to 30 seconds by default and 600 seconds at most. A timed-out read does not stop the process, and block: false peeks without waiting.
In the CLI, Ctrl+B can also release a waiting read and leave the process running for a later read.

The output buffer keeps only a rolling tail under the output limit, so older output can be lost and the result reports how much. Reading a finished process returns its remaining output and collects it, so its ID no longer works.

Stop a process

KillProcess immediately stops the process and its tracked descendants, without a clean shutdown or flush, and discards the output buffer. Use it only when that is acceptable, because a build or migration may be left incomplete. An unknown ID does not stop any process.

Limits

A session and account can keep at most 16 background processes by default; the configured range is 1–64.
When the limit is full, another process cannot start or detach. A process stops counting once it has exited.
The next attempt to start a background process removes exited processes from the list, so read the output of a finished process before you start another one.
A daemon restart ends background processes and removes their process records, so start a server or watcher again afterwards.
Scheduled jobs and workers without a conversation cannot start or detach background processes.

Plans and permissions

In plan mode, ListProcesses and ProcessOutput are available. Bash stays available only under plan mode's non-destructive shell rules, and KillProcess is not available while planning.

Bash and KillProcess can change system state. Direct-host background execution requires Linux, and a command you approve at a permission prompt is never moved to the background on its own.

If a process will not start

The limit is full: read or stop a finished process, then try again.
The process vanished after a restart: daemon restarts clear background processes. Start it again.
A prompt is waiting: approve the command, then start it in the background if it needs to keep running.

Terminal overview, Run a shell command, Run a command in the background, Open an interactive Project terminal.