Skip to content

Commit 9af9019

Browse files
author
Test
committed
🤖 feat: add workspace scripts with discovery and execution
Add complete workspace scripts feature with runtime-aware discovery, execution, and auto-completion for both local and SSH workspaces. **Script Discovery:** - New listScripts() function uses Runtime interface instead of local fs - Works with both local and SSH workspaces via execBuffered() - Extracts descriptions from # Description: or # @description comments - Adds WORKSPACE_LIST_SCRIPTS IPC handler - Includes unit tests with mocked runtime **Script Execution:** - New /script and /s slash commands with tab completion - WORKSPACE_EXECUTE_SCRIPT IPC handler using bash tool - Runtime-aware script existence checking via runtime.stat() - Scripts run in workspace directory with project secrets - 5-minute default timeout **Environment Variables:** - CMUX_OUTPUT: Write markdown for custom toast display - CMUX_PROMPT: Send follow-up message to agent after script runs **UI/UX:** - Script execution shows toast with exit code - Custom toast content from CMUX_OUTPUT (10KB limit) - Auto-send CMUX_PROMPT content as user message (100KB limit) - Command palette integration for script selection - Tab completion in chat input **Documentation:** - Add docs/scripts.md with usage examples - Demo scripts in .cmux/scripts/ - Storybook story for script execution flow Generated with cmux Change-Id: I301cff2ec5551b4b1a08d41be84c363dfbf13f72 Signed-off-by: Test <test@example.com>
1 parent 4a5ff11 commit 9af9019

File tree

24 files changed

+1154
-27
lines changed

24 files changed

+1154
-27
lines changed

‎.cmux/scripts/demo‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#!/usr/bin/env bash
2+
# Description: Demo script to showcase the script execution feature
3+
set -euo pipefail
4+
5+
# Regular output goes to stdout (visible in console logs)
6+
echo "Running demo script..."
7+
echo "Current workspace: $(pwd)"
8+
echo "Timestamp: $(date)"
9+
10+
# Write formatted output to CMUX_OUTPUT for toast display
11+
cat >> "$CMUX_OUTPUT" << 'EOF'
12+
## 🎉 Script Execution Demo
13+
14+
✅ Script executed successfully!
15+
16+
**Environment Variables Available:**
17+
- `CMUX_OUTPUT`: Custom toast display
18+
- `CMUX_PROMPT`: Send messages to agent
19+
EOF
20+
21+
# Write a prompt to CMUX_PROMPT to send a message to the agent
22+
cat >> "$CMUX_PROMPT" << 'EOF'
23+
The demo script has completed successfully. The script execution feature is working correctly with:
24+
1. Custom toast output via CMUX_OUTPUT
25+
2. Agent prompting via CMUX_PROMPT
26+
27+
You can now create workspace-specific scripts to automate tasks and interact with the agent.
28+
EOF

‎.cmux/scripts/echo‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
#!/usr/bin/env bash
2+
# Description: Echo arguments demo - shows how to access script arguments
3+
set -euo pipefail
4+
5+
# Check if arguments were provided
6+
if [ $# -eq 0 ]; then
7+
cat >> "$CMUX_OUTPUT" << 'EOF'
8+
## ⚠️ No Arguments Provided
9+
10+
Usage: `/s echo <message...>`
11+
12+
Example: `/s echo hello world`
13+
EOF
14+
exit 0
15+
fi
16+
17+
# Access arguments using standard bash positional parameters
18+
# $1 = first arg, $2 = second arg, $@ = all args, $# = number of args
19+
20+
cat >> "$CMUX_OUTPUT" << EOF
21+
## 🔊 Echo Script
22+
23+
**You said:** $@
24+
25+
**Arguments received:**
26+
- Count: $# arguments
27+
- First arg: ${1:-none}
28+
- Second arg: ${2:-none}
29+
- All args: $@
30+
31+
**Individual arguments:**
32+
EOF
33+
34+
# Loop through each argument
35+
for i in $(seq 1 $#); do
36+
echo "- Arg $i: ${!i}" >> "$CMUX_OUTPUT"
37+
done
38+
39+
# Optionally send a message to the agent
40+
if [ $# -gt 3 ]; then
41+
cat >> "$CMUX_PROMPT" << EOF
42+
The user passed more than 3 arguments to the echo script. They seem to be testing the argument passing feature extensively!
43+
EOF
44+
fi

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
- [SSH](./ssh.md)
1414
- [Forking](./fork.md)
1515
- [Init Hooks](./init-hooks.md)
16+
- [Workspace Scripts](./scripts.md)
1617
- [Models](./models.md)
1718
- [Keyboard Shortcuts](./keybinds.md)
1819
- [Vim Mode](./vim-mode.md)

‎docs/scripts.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Workspace Scripts
2+
3+
Execute custom scripts from your workspace using slash commands with full auto-completion.
4+
5+
## Overview
6+
7+
Scripts are stored in `.cmux/scripts/` within each workspace and can be executed via `/script <name>` or the shorter `/s <name>` alias. Scripts run in the workspace directory with full access to project secrets and environment variables.
8+
9+
**Key Point**: Scripts are workspace-specific, not project-global. Each workspace can have its own scripts in its `.cmux/scripts/` directory.
10+
11+
## Creating Scripts
12+
13+
1. **Create the scripts directory**:
14+
15+
```bash
16+
mkdir -p .cmux/scripts
17+
```
18+
19+
2. **Add an executable script**:
20+
21+
```bash
22+
#!/usr/bin/env bash
23+
# Description: Deploy to staging environment
24+
25+
echo "Deploying to staging..."
26+
# Your deployment commands here
27+
```
28+
29+
3. **Make it executable**:
30+
```bash
31+
chmod +x .cmux/scripts/deploy
32+
```
33+
34+
## Usage
35+
36+
### Basic Execution
37+
38+
Type `/s` or `/script` in chat to see available scripts with auto-completion:
39+
40+
```
41+
/s deploy
42+
```
43+
44+
### With Arguments
45+
46+
Pass arguments to scripts:
47+
48+
```
49+
/s deploy --dry-run
50+
/script test --verbose --coverage
51+
```
52+
53+
Arguments are passed directly to the script as `$1`, `$2`, etc.
54+
55+
## Script Descriptions
56+
57+
Add a description to make scripts easier to identify in auto-completion:
58+
59+
```bash
60+
#!/usr/bin/env bash
61+
# Description: Run full test suite with coverage
62+
```
63+
64+
or
65+
66+
```bash
67+
#!/usr/bin/env bash
68+
# @description Run full test suite with coverage
69+
```
70+
71+
The description appears in the command palette and slash command suggestions.
72+
73+
## Execution Context
74+
75+
Scripts run with:
76+
77+
- **Working directory**: The workspace directory (same as bash_tool)
78+
- **Environment**: Full workspace environment + project secrets + special cmux variables
79+
- **Timeout**: 5 minutes by default
80+
- **Streams**: stdout/stderr captured and logged
81+
82+
### Environment Variables
83+
84+
Scripts receive special environment variables for controlling cmux behavior:
85+
86+
#### `CMUX_OUTPUT`
87+
88+
Path to a temporary file for custom toast display content. Write markdown here for rich formatting in the UI toast:
89+
90+
```bash
91+
#!/usr/bin/env bash
92+
# Description: Deploy with custom output
93+
94+
echo "Deploying..." # Regular stdout for logs
95+
96+
# Write formatted output for toast display
97+
cat >> "$CMUX_OUTPUT" << 'EOF'
98+
## 🚀 Deployment Complete
99+
100+
✅ Successfully deployed to staging
101+
102+
**Details:**
103+
- Version: 2.1.3
104+
- Environment: staging
105+
- Duration: 45s
106+
EOF
107+
```
108+
109+
The toast will display the markdown-formatted content instead of the default "Script completed successfully" message.
110+
111+
#### `CMUX_PROMPT`
112+
113+
Path to a temporary file for sending messages to the agent. Write prompts here to trigger agent actions:
114+
115+
```bash
116+
#!/usr/bin/env bash
117+
# Description: Rebase with conflict handling
118+
119+
if git pull --rebase origin main; then
120+
echo "✅ Successfully rebased onto main" >> "$CMUX_OUTPUT"
121+
else
122+
echo "⚠️ Rebase conflicts detected" >> "$CMUX_OUTPUT"
123+
124+
# Send conflict details to agent for analysis
125+
cat >> "$CMUX_PROMPT" << 'EOF'
126+
The rebase encountered conflicts. Please help resolve them:
127+
128+
```
129+
130+
$(git status)
131+
132+
```
133+
134+
Analyze the conflicts and propose resolutions.
135+
EOF
136+
fi
137+
```
138+
139+
When the script completes, the prompt file content is automatically sent as a new user message, triggering the agent to respond.
140+
141+
#### Combined Usage
142+
143+
You can use both environment files together:
144+
145+
```bash
146+
#!/usr/bin/env bash
147+
# Description: Run tests and report failures
148+
149+
if npm test > test-output.txt 2>&1; then
150+
echo "✅ All tests passed" >> "$CMUX_OUTPUT"
151+
else
152+
# Show summary in toast
153+
echo "❌ Tests failed" >> "$CMUX_OUTPUT"
154+
155+
# Ask agent to analyze and fix
156+
cat >> "$CMUX_PROMPT" << EOF
157+
The test suite failed. Please analyze and fix:
158+
159+
\`\`\`
160+
$(cat test-output.txt)
161+
\`\`\`
162+
EOF
163+
fi
164+
```
165+
166+
**Result:**
167+
168+
1. Toast displays "❌ Tests failed"
169+
2. Agent receives test output and starts analyzing
170+
3. Agent proposes fixes
171+
172+
### File Size Limits
173+
174+
- **CMUX_OUTPUT**: Maximum 10KB (truncated if exceeded)
175+
- **CMUX_PROMPT**: Maximum 100KB (truncated if exceeded)
176+
177+
## Example Scripts
178+
179+
### Deployment Script
180+
181+
```bash
182+
#!/usr/bin/env bash
183+
# Description: Deploy application to specified environment
184+
set -euo pipefail
185+
186+
ENV=${1:-staging}
187+
echo "Deploying to $ENV..."
188+
189+
# Build
190+
npm run build
191+
192+
# Deploy
193+
aws s3 sync dist/ s3://my-bucket-$ENV/
194+
echo "Deployment complete!"
195+
```
196+
197+
### Test Runner
198+
199+
```bash
200+
#!/usr/bin/env bash
201+
# Description: Run tests with optional flags
202+
set -euo pipefail
203+
204+
FLAGS="${@:---coverage}"
205+
echo "Running tests with: $FLAGS"
206+
npm test $FLAGS
207+
```
208+
209+
### Database Migration
210+
211+
```bash
212+
#!/usr/bin/env bash
213+
# Description: Run database migrations
214+
set -euo pipefail
215+
216+
echo "Running migrations..."
217+
npm run migrate
218+
echo "Migrations complete!"
219+
```
220+
221+
## Tips
222+
223+
**Idempotency**: Scripts can run multiple times. Make them idempotent when modifying shared state.
224+
225+
**Error Handling**: Use `set -euo pipefail` to fail fast on errors.
226+
227+
**Logging**: Echo progress messages - they appear in real-time during execution.
228+
229+
**Arguments**: Always handle optional arguments with defaults:
230+
231+
```bash
232+
ENV=${1:-staging} # Default to 'staging' if no arg provided
233+
```
234+
235+
**Exit Codes**: Non-zero exit codes are displayed as warnings in the UI.
236+
237+
## Differences from Init Hooks
238+
239+
| Feature | Init Hooks (`.cmux/init`) | Scripts (`.cmux/scripts/*`) |
240+
| ------------- | -------------------------- | --------------------------- |
241+
| **When Run** | Once on workspace creation | On-demand via slash command |
242+
| **Execution** | Automatic | Manual user invocation |
243+
| **Use Case** | Setup dependencies | Development tasks |
244+
| **Arguments** | None | Supports arguments |
245+
| **Frequency** | One-time per workspace | Any time, any number |
246+
247+
## Script Discovery
248+
249+
- Scripts are discovered automatically from `.cmux/scripts/` in the current workspace
250+
- Only executable files appear in suggestions
251+
- Non-executable files are ignored
252+
- Cache refreshes when you switch workspaces
253+
254+
## Keyboard Shortcuts
255+
256+
Use existing chat and command palette shortcuts:
257+
258+
- Type `/s` in chat for inline suggestions
259+
- `Cmd+Shift+P` (or `Ctrl+Shift+P`) → `/s` for command palette
260+
- Arrow keys to select, Enter to run
261+
262+
## Troubleshooting
263+
264+
**Script not appearing in suggestions?**
265+
266+
- Ensure file is executable: `chmod +x .cmux/scripts/scriptname`
267+
- Verify file is in `.cmux/scripts/` directory within your workspace
268+
- Switch to another workspace and back to refresh the cache
269+
270+
**Script fails with "not found"?**
271+
272+
- Check shebang line is correct: `#!/usr/bin/env bash`
273+
- Verify script has execute permissions
274+
- Test script directly: `./.cmux/scripts/scriptname`
275+
276+
**Script times out?**
277+
278+
- Scripts have 5 minute timeout by default
279+
- Split long-running operations into separate scripts
280+
- Consider running processes in background if needed

0 commit comments

Comments
 (0)