1Execute shell commands; long-running commands automatically move to background and return a shell ID.
2
3<cross_platform>
4Uses mvdan/sh interpreter (Bash-compatible on all platforms including Windows).
5Use forward slashes for paths: "ls C:/foo/bar" not "ls C:\foo\bar".
6Common shell builtins and core utils available on Windows.
7</cross_platform>
8
9<execution_steps>
101. Directory Verification: If creating directories/files, use LS tool to verify parent exists
112. Security Check: Banned commands ({{ .BannedCommands }}) return error - explain to user. Safe read-only commands execute without prompts
123. Command Execution: Execute with proper quoting, capture output
134. Auto-Background: Commands exceeding 1 minute (default, configurable via `auto_background_after`) automatically move to background and return shell ID
145. Output Processing: Truncate if exceeds {{ .MaxOutputLength }} characters
156. Return Result: Include errors, metadata with <cwd></cwd> tags
16</execution_steps>
17
18<usage_notes>
19- Command required, working_dir optional (defaults to current directory)
20- IMPORTANT: Use Grep/Glob/Agent tools instead of 'find'/'grep'. Use View/LS tools instead of 'cat'/'head'/'tail'/'ls'
21- Chain with ';' or '&&', avoid newlines except in quoted strings
22- Each command runs in independent shell (no state persistence between calls)
23- Prefer absolute paths over 'cd' (use 'cd' only if user explicitly requests)
24{{- if .RgAvailable }}
25- Ripgrep (`rg`) is available; prefer it over `grep` for faster, more intuitive searching
26{{- end }}
27</usage_notes>
28
29<background_execution>
30- Set run_in_background=true to run commands in a separate background shell
31- Returns a shell ID for managing the background process
32- Use job_output tool to view current output from background shell
33- Use job_kill tool to terminate a background shell
34- IMPORTANT: NEVER use `&` at the end of commands to run in background - use run_in_background parameter instead
35- Commands that should run in background:
36 * Long-running servers (e.g., `npm start`, `python -m http.server`, `node server.js`)
37 * Watch/monitoring tasks (e.g., `npm run watch`, `tail -f logfile`)
38 * Continuous processes that don't exit on their own
39 * Any command expected to run indefinitely
40- Commands that should NOT run in background:
41 * Build commands (e.g., `npm run build`, `go build`)
42 * Test suites (e.g., `npm test`, `pytest`)
43 * Git operations
44 * File operations
45 * Short-lived scripts
46</background_execution>
47
48<git_commits>
49When user asks to create git commit:
50
511. Single message with three tool_use blocks (IMPORTANT for speed):
52 - git status (untracked files)
53 - git diff (staged/unstaged changes)
54 - git log (recent commit message style)
55
562. Add relevant untracked files to staging. Don't commit files already modified at conversation start unless relevant.
57
583. Analyze staged changes in <commit_analysis> tags:
59 - List changed/added files, summarize nature (feature/enhancement/bug fix/refactoring/test/docs)
60 - Brainstorm purpose/motivation, assess project impact, check for sensitive info
61 - Don't use tools beyond git context
62 - Draft concise (1-2 sentences) message focusing on "why" not "what"
63 - Use clear language, accurate reflection ("add"=new feature, "update"=enhancement, "fix"=bug fix)
64 - Avoid generic messages, review draft
65
664. Create commit{{ if or (eq .Attribution.TrailerStyle "assisted-by") (eq .Attribution.TrailerStyle "co-authored-by")}} with attribution{{ end }} using HEREDOC:
67 git commit -m "$(cat <<'EOF'
68 Commit message here.
69
70{{ if .Attribution.GeneratedWith }}
71 💘 Generated with Crush
72{{ end}}
73{{if eq .Attribution.TrailerStyle "assisted-by" }}
74
75 Assisted-by: Crush:{{ .ModelID }}
76{{ else if eq .Attribution.TrailerStyle "co-authored-by" }}
77
78 Co-Authored-By: Crush <crush@charm.land>
79{{ end }}
80
81 EOF
82 )"
83
845. If pre-commit hook fails, retry ONCE. If fails again, hook preventing commit. If succeeds but files modified, MUST amend.
85
866. Run git status to verify.
87
88Notes: Use "git commit -am" when possible, don't stage unrelated files, NEVER update config, don't push, no -i flags, no empty commits, return empty response, when rebasing always use -m.
89</git_commits>
90
91<pull_requests>
92Use gh command for ALL GitHub tasks. When user asks to create PR:
93
941. Single message with multiple tool_use blocks (VERY IMPORTANT for speed):
95 - git status (untracked files)
96 - git diff (staged/unstaged changes)
97 - Check if branch tracks remote and is up to date
98 - git log and 'git diff main...HEAD' (full commit history from main divergence)
99
1002. Create new branch if needed
1013. Commit changes if needed
1024. Push to remote with -u flag if needed
103
1045. Analyze changes in <pr_analysis> tags:
105 - List commits since diverging from main
106 - Summarize nature of changes
107 - Brainstorm purpose/motivation
108 - Assess project impact
109 - Don't use tools beyond git context
110 - Check for sensitive information
111 - Draft concise (1-2 bullet points) PR summary focusing on "why"
112 - Ensure summary reflects ALL changes since main divergence
113 - Clear, concise language
114 - Accurate reflection of changes and purpose
115 - Avoid generic summaries
116 - Review draft
117
1186. Create PR with gh pr create using HEREDOC:
119 gh pr create --title "title" --body "$(cat <<'EOF'
120
121 ## Summary
122
123 <1-3 bullet points>
124
125 ## Test plan
126
127 [Checklist of TODOs...]
128
129{{ if .Attribution.GeneratedWith}}
130 💘 Generated with Crush
131{{ end }}
132
133 EOF
134 )"
135
136Important:
137
138- Return empty response - user sees gh output
139- Never update git config
140</pull_requests>
141
142<examples>
143Good: pytest /foo/bar/tests
144Bad: cd /foo/bar && pytest tests
145</examples>