diff --git a/docs/cli/beta-background-processes.mdx b/docs/cli/beta-background-processes.mdx
new file mode 100644
index 00000000000..ac8427a3c6b
--- /dev/null
+++ b/docs/cli/beta-background-processes.mdx
@@ -0,0 +1,185 @@
+---
+title: "Background Process Execution (Beta)"
+description: "Run long-running terminal commands in the background while the AI continues other tasks"
+sidebarTitle: "Background Processes"
+---
+
+
+ This feature is in beta and may change. Enable with the `--beta-persistent-terminal-tools` flag.
+
+
+## Overview
+
+Background process execution allows the Continue CLI agent to run long-running terminal commands in the background, enabling workflows where processes like dev servers need to continue while the agent performs other tasks.
+
+## Motivation
+
+Previously, the `Bash` tool would block until a command completed. This made it impossible for the agent to:
+
+- Start a dev server and then take screenshots of the running application
+- Launch multiple long-running processes concurrently
+- Monitor ongoing processes while continuing other work
+
+Background process execution unlocks capabilities like automated testing of live applications, parallel command execution, and better handling of persistent services.
+
+## Enabling Background Processes
+
+To enable this beta feature, start the CLI with the `--beta-persistent-terminal-tools` flag:
+
+```bash
+cn chat --beta-persistent-terminal-tools "help me build and test my app"
+```
+
+## Available Tools
+
+When background processes are enabled, the following tools become available to the AI:
+
+### Bash (Enhanced)
+
+The existing `Bash` tool gains a new `run_in_background` parameter:
+
+```typescript
+Bash({
+ command: "npm run dev",
+ run_in_background: true,
+});
+// Returns: "Background process started with ID 1..."
+```
+
+### BashOutput
+
+Read buffered output from a background process:
+
+```typescript
+BashOutput({
+ bash_id: 1,
+ filter: "Local:.*http://localhost", // Optional regex filter
+});
+// Returns filtered output showing server URL
+```
+
+**Parameters:**
+- `bash_id` (required): The process ID to read output from
+- `filter` (optional): A regex pattern to filter output lines
+
+### ListProcesses
+
+List all running background processes:
+
+```typescript
+ListProcesses();
+// Returns list of active processes with IDs, commands, and status
+```
+
+### KillProcess
+
+Terminate a background process:
+
+```typescript
+KillProcess({ bash_id: 1 });
+// Returns confirmation of process termination
+```
+
+## Example Workflows
+
+### Starting and Monitoring a Dev Server
+
+```bash
+cn chat --beta-persistent-terminal-tools "start the dev server and tell me when it's ready"
+```
+
+The agent can:
+
+1. Start the server with `Bash({ command: "npm run dev", run_in_background: true })`
+2. Poll for ready signal with `BashOutput({ bash_id: 1, filter: "ready" })`
+3. Continue with other tasks once the server is running
+4. Clean up with `KillProcess({ bash_id: 1 })` when done
+
+### Running Tests Against a Live Server
+
+```bash
+cn chat --beta-persistent-terminal-tools "start the app and run e2e tests against it"
+```
+
+The agent can:
+
+1. Start the application server in the background
+2. Wait for the server to be ready using output monitoring
+3. Run tests using a separate `Bash` command
+4. Clean up the server process after tests complete
+
+### Parallel Command Execution
+
+```bash
+cn chat --beta-persistent-terminal-tools "build the frontend and backend in parallel"
+```
+
+The agent can start multiple background processes simultaneously and monitor their progress.
+
+## Technical Details
+
+### Process Management
+
+- **Process IDs**: Sequential numeric IDs (1, 2, 3...) for simple reference
+- **Process Limit**: Maximum 10 concurrent background processes
+- **Session Scope**: Processes are automatically terminated when the CLI exits
+
+### Output Buffering
+
+- **Buffer Size**: 10,000 lines per process
+- **Circular Buffer**: Oldest lines are discarded when the buffer is full
+- **Incremental Reading**: `BashOutput` returns only new output since the last read
+
+### Lifecycle
+
+- Processes are spawned using Node.js `spawn`
+- Exit codes are tracked and reported
+- Automatic cleanup on CLI exit via `gracefulExit()` handler
+- No persistence across CLI sessions
+
+## Limitations
+
+
+ - Processes are **session-scoped** and killed when the CLI exits
+ - **No persistence** across agent sessions
+ - Output buffer **limited to 10K lines** per process
+ - **No built-in readiness detection** (agent must parse output)
+ - Maximum **10 concurrent processes**
+
+
+## Use Cases
+
+
+
+ Start development servers and test running applications automatically
+
+
+
+ Run multiple build processes concurrently to speed up workflows
+
+
+
+ Monitor application logs while performing other development tasks
+
+
+
+ Start and manage multiple services for integration testing
+
+
+
+## Feedback
+
+This feature is in beta. Please share feedback:
+
+- [GitHub Discussions](https://github.com/continuedev/continue/discussions)
+- [Discord Community](https://discord.com/invite/EfJEfdFnDQ)
+
+## Future Considerations
+
+Potential enhancements being considered:
+
+- Persistent processes across sessions
+- Process groups and orchestration
+- Built-in readiness detection for common frameworks
+- Extended output history and streaming
+- Process resource monitoring and alerts
diff --git a/docs/cli/overview.mdx b/docs/cli/overview.mdx
index f2063b60587..7b10629cf8e 100644
--- a/docs/cli/overview.mdx
+++ b/docs/cli/overview.mdx
@@ -127,6 +127,7 @@ cn -p "Update documentation based on recent code changes"
- Codebase understanding and analysis
- Git integration
- Web search and documentation access
+- [Background process execution](/cli/beta-background-processes) (beta)
### Model Flexibility
diff --git a/docs/docs.json b/docs/docs.json
index afd202c9568..69e12a0d2f1 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -87,6 +87,7 @@
"cli/overview",
"cli/install",
"cli/quick-start",
+ "cli/beta-background-processes",
"cli/guides"
]
},