The agent runs shell commands on your machine, such as builds, tests, installs, development servers, and watchers. This page explains timeouts, background commands, and how to control background work with /tasks.
Command timeouts
Each command the agent runs has a timeout:
| Setting | Value |
|---|---|
| Default timeout | 120 seconds |
| Longest timeout the agent can request | 600 seconds, or your default if higher |
| Change the default | Set BOLDCREATE_COMMAND_TIMEOUT (seconds) before starting BoldCreate. |
For example:
BOLDCREATE_COMMAND_TIMEOUT=300 boldcreateWhen a command exceeds its timeout, it isn’t killed. It moves to the background and keeps running. BoldCreate shows the task ID, process ID, latest output, and log file location so the agent can inspect the output later instead of starting the command again. A command starting with sleep is the exception and is stopped at its timeout.
Commands started in the background
For commands that do not finish on their own, such as development servers, watchers, or tail -f, the agent starts them in the background and returns with a task ID and output file.
Output is never lost
Every command writes stdout and stderr together to a log file:
~/.boldcreate/workspaces/<session-id>/tasks/<task>.log| Result | What the agent sees |
|---|---|
| Success, up to 30,000 characters | All output. |
| Longer success | First 2,000 characters and the log file path. |
| Failure | Start and end of output (where errors usually are), up to 10,000 characters, and the log file path. |
Exit code 1 from grep, rg, find, diff, test, git diff, or git grep means “nothing found” or “different”, so it isn’t treated as a failure. Short-result log files are deleted when no longer needed.
Stop commands
- Press Esc while the agent is waiting on a command to stop it, including everything it started in that process group.
- Background tasks aren’t tied to a run. They keep going after the agent’s answer and after you press Esc.
- All background tasks stop when BoldCreate exits.
- To stop one while BoldCreate stays open, use
/tasks→ Stop.
View and control work with /tasks
Type /tasks in an interactive session. Tasks waiting for you appear first, then running tasks, then the newest of the rest.
Possible states include running, waiting for approval, done, failed, and stopped. Select a task to see its command, state, how it started, process ID, output file, and recent output. Available actions include:
- Refresh to reload its state and output.
- Approve or Reject a helper agent waiting for approval.
- Stop a running or waiting task.
- Back to return to the task list.
Background helper agents
For larger jobs, the agent can start a background helper to work in parallel. Helpers share the session’s tools, folder, model, and approval rules. They may be running, waiting for approval, done, failed, or stopped. Use /tasks to inspect and manage them.
Helpers follow the current approval mode. Switching to auto mode (Alt+M or /mode auto) approves a helper that is waiting for approval.
Notices and automatic follow-up
BoldCreate checks on background work every few seconds. When a task finishes, fails, or stops, a notice appears and the agent receives the result before its next step. By default, it can continue working automatically.
To turn off automatic continuation, set this in ~/.boldcreate/settings.json:
{ "backgroundAutoContinue": false }Background work in print mode
Print mode waits for background helper agents, up to 600 seconds by default, then lets the agent continue. Set BOLDCREATE_BACKGROUND_WAIT to change the wait:
BOLDCREATE_BACKGROUND_WAIT=120 boldcreate -p "audit the dependencies"Background shell commands aren’t waited for; they stop when the print-mode process exits. If the wait for helpers expires, BoldCreate warns and stops them.