> ## Documentation Index
> Fetch the complete documentation index at: https://desktopcommander.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Process

> Launch terminal sessions and execute commands with intelligent process management

# start\_process

The `start_process` tool is the primary way for Claude to run commands, launch programs, and start interactive sessions on your computer. It's essential for data analysis, automation, and any task that requires executing code or commands.

## What it does

Starts new terminal processes with smart detection features:

* Launch terminal sessions (bash, zsh, PowerShell)
* Start interactive environments (Python REPL, Node.js, R)
* Execute single commands or long-running processes
* Handle both quick tasks and persistent sessions
* Automatically detect when processes are ready for input

## How it works

Simply ask Claude to run commands or start programs:

```
"Start a Python session so we can analyze this data"
"Run the npm install command in my project directory" 
"Launch a bash shell to explore the system"
"Execute this Python script and show me the results"
```

Claude will use start\_process to launch the appropriate program or command.

## Key Features

> **Intelligent Detection**
>
> Automatically recognizes REPL prompts, process completion, and when programs are ready for input

> **Cross-Platform Support**
>
> Works seamlessly on Windows, macOS, and Linux with platform-specific optimizations

> **Interactive Sessions**
>
> Perfect for Python, Node.js, R, and other interactive programming environments

> **Process Management**
>
> Smart handling of both short-lived commands and long-running processes

## Common Use Cases

### Data Analysis Workflows

The most powerful use of start\_process is for data analysis:

```
"Start a Python session and load this CSV file for analysis"
```

This enables Claude to:

1. Launch Python with `start_process("python3 -i")`
2. Import libraries like pandas, numpy, matplotlib
3. Load and analyze your data interactively
4. Create visualizations and generate insights
5. Save results back to files

### Development Tasks

```
"Run the test suite in my project"
"Start a development server"
"Execute the build process"
"Run linting and code formatting"
```

### System Administration

```
"Check system resource usage"
"Monitor log files in real-time"
"Run maintenance scripts"
"Update system packages"
```

### File Processing

```
"Process all images in this directory"
"Convert files between formats"
"Batch rename files with patterns"
"Archive old project files"
```

## Interactive vs Command Execution

**Interactive Sessions (REPL)**

**Best for:** Data analysis, development, exploratory tasks

**Examples:**

* `python3 -i` - Python REPL for data analysis
* `node -i` - Node.js for JavaScript processing
* `R` - R statistical computing environment
* `bash` - Interactive shell for system tasks

**Benefits:**

* Maintain state between commands
* Build complex workflows step by step
* Ideal for data exploration and analysis
* Perfect for iterative development

**Single Commands**

**Best for:** Quick tasks, system commands, simple operations

**Examples:**

* `ls -la /home/user/Documents` - List directory contents
* `wc -l data.csv` - Count lines in a file
* `grep "error" application.log` - Search for errors in logs
* `npm install` - Install project dependencies

**Benefits:**

* Fast execution for simple tasks
* Clear input/output for straightforward commands
* Good for file system operations
* Efficient for system monitoring

## Critical: Local File Analysis

> [!WARNING]
>
> For ANY work with local files (CSV analysis, JSON processing, data exploration), you MUST use start\_process with interactive sessions. The analysis tool cannot access local files and will fail.

### Correct Workflow for File Analysis

1. **Start interactive session**: `start_process("python3 -i")`
2. **Import libraries**: Use `interact_with_process` to load pandas, numpy, etc.
3. **Load local files**: Read CSV/JSON files from your file system
4. **Analyze data**: Perform calculations, create summaries, generate insights
5. **Save results**: Write findings back to files

### Why This Matters

* **Analysis tool**: Browser-only, cannot read your local files
* **Process tools**: Direct access to your file system and data
* **Always use processes**: For any local file work, always start with start\_process

## Smart Process Detection

Desktop Commander includes intelligent detection features:

### REPL Recognition

Automatically identifies when interactive environments are ready:

* Python `>>>` prompt
* Node.js `>` prompt
* R `>` prompt
* Shell `$` or `#` prompts

### Completion Detection

Knows when processes finish vs when they're still running:

* Short commands complete quickly
* Long-running processes stay active
* Interactive sessions wait for more input
* Error conditions are properly handled

### Early Exit Prevention

Prevents timeouts when processes are simply waiting for input:

* No unnecessary waiting for prompts
* Clean output without extra prompt characters
* Clear status indicators for process state
* Efficient handling of different response patterns

## Platform-Specific Features

**macOS**

**Default Shell:** zsh

**Package Manager:** Homebrew (`brew`)

**Python:** Usually `python3` command

**Special Commands:**

* `open` - Open files/applications
* GNU tools may have different names (e.g., `gsed`)

**Notes:**

* System Integrity Protection may block some operations
* Xcode Command Line Tools may be required for development

**Windows**

**Shells:** PowerShell, Command Prompt, WSL

**Package Managers:** Chocolatey, Scoop, Windows Package Manager

**Path Format:** Backslashes (`C:\Users\username`)

**Special Features:**

* WSL integration for Linux-style commands
* PowerShell for advanced scripting
* Native Windows command support

**Linux**

**Shells:** bash, zsh, fish

**Package Managers:** apt, yum, dnf, pacman

**Python:** May be `python` or `python3` depending on distribution

**Features:**

* Full POSIX compliance
* Extensive command-line tools
* Container and Docker support

## Security Considerations

> **Command Blocking**
>
> Desktop Commander blocks dangerous system commands by default:
>
> * File system formatting commands (`mkfs`, `format`)
> * User management commands (`sudo`, `passwd`, `useradd`)
> * System control commands (`shutdown`, `reboot`)
> * Network security commands (`iptables`, `firewall`)

### Configurable Security

* Review blocked commands with `get_config`
* Customize security settings as needed
* Add or remove command restrictions
* Configure directory access limitations

### Best Practices

* Always review what Claude plans to execute
* Start with restricted permissions and expand as needed
* Use directory limitations for sensitive projects
* Monitor process activity with `list_sessions`

## Performance Tips

> [!TIP]
>
> For data analysis or multi-step processes, start an interactive session once and reuse it rather than running separate commands.

> [!TIP]
>
> Short commands need brief timeouts, while data processing or compilation may need longer timeouts.

> [!TIP]
>
> Use `list_sessions` to see what processes are running and clean up unused sessions with `force_terminate`.

## Troubleshooting

### Process Won't Start

* Check that the command exists and is in your PATH
* Verify you have permissions to execute the command
* Ensure required software is installed (Python, Node.js, etc.)
* Check for typos in command names

### Session Appears Stuck

* Process might be waiting for input (use `interact_with_process`)
* Check if it's a long-running operation that needs more time
* Use `read_process_output` to see current status
* Consider `force_terminate` if truly stuck

### Permission Errors

* Some commands require elevated privileges
* Check directory permissions for file operations
* Review security settings and blocked commands
* Consider running with appropriate user permissions

## Related Tools

* [interact\_with\_process](https://desktopcommander.mintlify.site/tools/process-management/interact-with-process.md) - Send input to running processes
* [read\_process\_output](https://desktopcommander.mintlify.site/tools/process-management/read-process-output.md) - Read output from processes
* [list\_sessions](https://desktopcommander.mintlify.site/tools/process-management/list-sessions.md) - Monitor active sessions
* [force\_terminate](https://desktopcommander.mintlify.site/tools/process-management/force-terminate.md) - Stop running processes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.