@@ -7,162 +7,36 @@ Execute shell commands in the user's environment with full control over working
77
88## Core Concepts
99
10- **Execution Context**: Commands run in the user's default shell with access to all environment variables and the current workspace.
11- On Windows, PowerShell (pwsh/powershell) is used when available; otherwise, cmd.exe is used.
12- On Unix-like systems, ${SHELL} is used or /bin/sh as fallback.
13-
14- **Working Directory Management**:
15- - Default execution location: working directory of the agent
16- - Override with "cwd" parameter for targeted command execution
17- - Supports both absolute and relative paths
18-
19- **Command Isolation**: Each tool call creates a fresh shell session - no state persists between executions.
20-
21- **Timeout Protection**: Commands have a default 30-second timeout to prevent hanging. For longer operations, specify a custom timeout.
22-
23- ## Parameter Reference
24-
25- | Parameter | Type | Required | Description |
26- |-----------|--------|----------|-------------|
27- | cmd | string | Yes | Shell command to execute |
28- | cwd | string | Yes | Working directory (use "." for current) |
29- | timeout | int | No | Timeout in seconds (default: 30) |
10+ - Commands run in the user's default shell (Unix: ${SHELL} or /bin/sh; Windows: pwsh/powershell or cmd.exe)
11+ - Each call creates a fresh shell session — no state persists between executions
12+ - Default working directory: agent's working directory. Override with "cwd" parameter (absolute or relative paths)
13+ - Default timeout: 30s. Use "timeout" parameter for longer operations (e.g., builds, tests)
3014
3115## Best Practices
3216
33- ### ✅ DO
34- - Leverage the "cwd" parameter for directory-specific commands, rather than cding within commands
35- - Quote arguments containing spaces or special characters
36- - Use pipes and redirections
37- - Write advanced scripts with heredocs, that replace a lot of simple commands or tool calls
38- - This tool is great at reading and writing multiple files at once
39- - Avoid writing shell scripts to the disk. Instead, use heredocs to pipe the script to the SHELL
40- - Use the timeout parameter for long-running operations (e.g., builds, tests)
41-
42- ### Git Commits
43-
44- When user asks to create git commit
45-
46- - Add "Assisted-By: cagent" as a trailer line in the commit message
47- - Use the format: git commit -m "Your commit message" -m "" -m "Assisted-By: cagent"
48-
49- ## Usage Examples
50-
51- **Basic command execution:**
52- { "cmd": "ls -la", "cwd": "." }
17+ - Use "cwd" instead of cd within commands
18+ - Quote arguments with spaces or special characters
19+ - Use pipes, redirections, and heredocs to combine operations
20+ - Prefer inline heredocs over writing shell scripts to disk
21+ - For git commits, add trailer: git commit -m "message" -m "" -m "Assisted-By: cagent"
5322
54- **Long-running command with custom timeout:**
55- { "cmd": "npm run build", "cwd": ".", "timeout": 120 }
23+ ## Examples
5624
57- **Language-specific operations:**
5825{ "cmd": "go test ./...", "cwd": ".", "timeout": 180 }
59- { "cmd": "npm install", "cwd": "frontend" }
60- { "cmd": "python -m pytest tests/", "cwd": "backend", "timeout": 90 }
61-
62- **File operations:**
63- { "cmd": "find . -name '*.go' -type f", "cwd": "." }
6426{ "cmd": "grep -r 'TODO' src/", "cwd": "." }
65-
66- **Process management:**
67- { "cmd": "ps aux | grep node", "cwd": "." }
68- { "cmd": "docker ps --format 'table {{.Names}}\t{{.Status}}'", "cwd": "." }
69-
70- **Complex pipelines:**
71- { "cmd": "cat package.json | jq '.dependencies'", "cwd": "frontend" }
72-
73- **Bash scripts:**
74- { "cmd": "cat << 'EOF' | ${SHELL}
75- echo Hello
76- EOF" }
27+ { "cmd": "cat << 'EOF' | ${SHELL}\necho Hello\nEOF" }
7728
7829## Error Handling
7930
80- Commands that exit with non-zero status codes will return error information along with any output produced before failure.
81- Commands that exceed their timeout will be terminated automatically.
82-
83- ---
31+ Non-zero exit codes return error info with output. Timed-out commands are terminated automatically.
8432
8533# Background Jobs
8634
87- Run long-running processes in the background while continuing with other tasks. Perfect for starting servers, watching files, or any process that needs to run alongside other operations.
88-
89- ## When to Use Background Jobs
90-
91- **Use background jobs for:**
92- - Starting web servers, databases, or other services
93- - Running file watchers or live reload tools
94- - Long-running processes that other tasks depend on
95- - Commands that produce continuous output over time
96-
97- **Don't use background jobs for:**
98- - Quick commands that complete in seconds
99- - Commands where you need immediate results
100- - One-time operations (use regular shell tool instead)
101-
102- ## Background Job Tools
103-
104- **run_background_job**: Start a command in the background
105- - Parameters: cmd (required), cwd (optional, defaults to ".")
106- - Returns: Job ID for tracking
107-
108- **list_background_jobs**: List all background jobs
109- - No parameters required
110- - Returns: Status, runtime, and command for each job
111-
112- **view_background_job**: View output of a specific job
113- - Parameters: job_id (required)
114- - Returns: Current output and job status
115-
116- **stop_background_job**: Stop a running job
117- - Parameters: job_id (required)
118- - Terminates the process and all child processes
119-
120- ## Background Job Workflow
121-
122- **1. Start a background job:**
123- { "cmd": "npm start", "cwd": "frontend" }
124- → Returns job ID (e.g., "job_1731772800_1")
125-
126- **2. Check running jobs:**
127- Use list_background_jobs to see all jobs with their status
128-
129- **3. View job output:**
130- { "job_id": "job_1731772800_1" }
131- → Shows current output and status
132-
133- **4. Stop job when done:**
134- { "job_id": "job_1731772800_1" }
135- → Terminates the process and all child processes
136-
137- ## Important Characteristics
138-
139- **Output Buffering**: Each job captures up to 10MB of output. Beyond this limit, new output is discarded to prevent memory issues.
140-
141- **Process Groups**: Background jobs and all their child processes are managed as a group. Stopping a job terminates the entire process tree.
142-
143- **Environment Inheritance**: Jobs inherit environment variables from when they are started. Changes after job start don't affect running jobs.
144-
145- **Automatic Cleanup**: All background jobs are automatically terminated when the agent stops.
146-
147- **Job Persistence**: Job history is kept in memory until agent stops. Completed jobs remain queryable.
148-
149- ## Background Job Examples
150-
151- **Start a web server:**
152- { "cmd": "python -m http.server 8000", "cwd": "." }
153-
154- **Start a development server:**
155- { "cmd": "npm run dev", "cwd": "frontend" }
156-
157- **Run a file watcher:**
158- { "cmd": "go run . watch", "cwd": "." }
35+ Use background jobs for long-running processes (servers, watchers) that should run while other tasks are performed.
15936
160- **Start a database:**
161- { "cmd": "docker run --rm -p 5432:5432 postgres:latest", "cwd": "." }
37+ - **run_background_job**: Start a command, returns job ID. Example: { "cmd": "npm run dev", "cwd": "frontend" }
38+ - **list_background_jobs**: Show all jobs with status and runtime
39+ - **view_background_job**: Get output and status of a job by job_id
40+ - **stop_background_job**: Terminate a job and all its child processes by job_id
16241
163- **Multiple services pattern:**
164- 1. Start backend: run_background_job with server command
165- 2. Start frontend: run_background_job with dev server
166- 3. Perform tasks: use other tools while services run
167- 4. Check logs: view_background_job to see service output
168- 5. Cleanup: stop_background_job for each service (or let agent cleanup automatically)`
42+ **Notes**: Output capped at 10MB per job. Jobs inherit env vars at start time. All jobs auto-terminate when the agent stops.`
0 commit comments