clawdbot/docs/background-process.md

summary, read_when

summary	read_when
Background bash execution and process management	Adding or modifying background bash behavior Debugging long-running bash tasks

Background Bash + Process Tool

Clawdbot runs shell commands through the bash tool and keeps long‑running tasks in memory. The process tool manages those background sessions.

bash tool

Key parameters:

• command (required)
• yieldMs (default 10000): auto‑background after this delay
• background (bool): background immediately
• timeout (seconds, default 1800): kill the process after this timeout
• elevated (bool): run on host if elevated mode is enabled/allowed
• Need a real TTY? Use the tmux skill.
• workdir, env

Behavior:

• Foreground runs return output directly.
• When backgrounded (explicit or timeout), the tool returns status: "running" + sessionId and a short tail.
• Output is kept in memory until the session is polled or cleared.

Environment overrides:

• PI_BASH_YIELD_MS: default yield (ms)
• PI_BASH_MAX_OUTPUT_CHARS: in‑memory output cap (chars)
• PI_BASH_JOB_TTL_MS: TTL for finished sessions (ms, bounded to 1m–3h)

Config (preferred):

• agent.bash.backgroundMs (default 10000)
• agent.bash.timeoutSec (default 1800)
• agent.bash.cleanupMs (default 1800000)

process tool

Actions:

• list: running + finished sessions
• poll: drain new output for a session (also reports exit status)
• log: read the aggregated output (supports offset + limit)
• write: send stdin (data, optional eof)
• kill: terminate a background session
• clear: remove a finished session from memory
• remove: kill if running, otherwise clear if finished

Notes:

• Only backgrounded sessions are listed/persisted in memory.
• Sessions are lost on process restart (no disk persistence).
• Session logs are only saved to chat history if you run process poll/log and the tool result is recorded.
• process list includes a derived name (command verb + target) for quick scans.
• process log uses line-based offset/limit (omit offset to grab the last N lines).

Examples

Run a long task and poll later:

{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}

{"tool": "process", "action": "poll", "sessionId": "<id>"}

Start immediately in background:

{"tool": "bash", "command": "npm run build", "background": true}

Send stdin:

{"tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n"}