🤖 feat: add workspace scripts with discovery and execution

.cmux/scripts/demo

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Description: Demo script to showcase the script execution feature
+set -euo pipefail
+
+# Regular output goes to stdout (visible in console logs)
+echo "Running demo script..."
+echo "Current workspace: $(pwd)"
+echo "Timestamp: $(date)"
+
+# Write formatted output to CMUX_OUTPUT for toast display
+cat >> "$CMUX_OUTPUT" << 'EOF'
+## 🎉 Script Execution Demo
+
+✅ Script executed successfully!
+
+**Environment Variables Available:**
+- `CMUX_OUTPUT`: Custom toast display
+- `CMUX_PROMPT`: Send messages to agent
+EOF
+
+# Write a prompt to CMUX_PROMPT to send a message to the agent
+cat >> "$CMUX_PROMPT" << 'EOF'
+The demo script has completed successfully. The script execution feature is working correctly with:
+1. Custom toast output via CMUX_OUTPUT
+2. Agent prompting via CMUX_PROMPT
+
+You can now create workspace-specific scripts to automate tasks and interact with the agent.
+EOF

.cmux/scripts/echo

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Description: Echo arguments demo - shows how to access script arguments
+set -euo pipefail
+
+# Check if arguments were provided
+if [ $# -eq 0 ]; then
+  cat >> "$CMUX_OUTPUT" << 'EOF'
+## ⚠️ No Arguments Provided
+
+Usage: `/s echo <message...>`
+
+Example: `/s echo hello world`
+EOF
+  exit 0
+fi
+
+# Access arguments using standard bash positional parameters
+# $1 = first arg, $2 = second arg, $@ = all args, $# = number of args
+
+cat >> "$CMUX_OUTPUT" << EOF
+## 🔊 Echo Script
+
+**You said:** $@
+
+**Arguments received:**
+- Count: $# arguments
+- First arg: ${1:-none}
+- Second arg: ${2:-none}
+- All args: $@
+
+**Individual arguments:**
+EOF
+
+# Loop through each argument
+for i in $(seq 1 $#); do
+  echo "- Arg $i: ${!i}" >> "$CMUX_OUTPUT"
+done
+
+# Optionally send a message to the agent
+if [ $# -gt 3 ]; then
+  cat >> "$CMUX_PROMPT" << EOF
+The user passed more than 3 arguments to the echo script. They seem to be testing the argument passing feature extensively!
+EOF
+fi

docs/SUMMARY.md

@@ -13,6 +13,7 @@
   - [SSH](./ssh.md)
   - [Forking](./fork.md)
   - [Init Hooks](./init-hooks.md)
+  - [Workspace Scripts](./scripts.md)
 - [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.md)
   - [Vim Mode](./vim-mode.md)

docs/scripts.md

@@ -0,0 +1,280 @@
+# Workspace Scripts
+
+Execute custom scripts from your workspace using slash commands with full auto-completion.
+
+## Overview
+
+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.
+
+**Key Point**: Scripts are workspace-specific, not project-global. Each workspace can have its own scripts in its `.cmux/scripts/` directory.
+
+## Creating Scripts
+
+1. **Create the scripts directory**:
+
+   ```bash
+   mkdir -p .cmux/scripts
+   ```
+
+2. **Add an executable script**:
+
+   ```bash
+   #!/usr/bin/env bash
+   # Description: Deploy to staging environment
+
+   echo "Deploying to staging..."
+   # Your deployment commands here
+   ```
+
+3. **Make it executable**:
+   ```bash
+   chmod +x .cmux/scripts/deploy
+   ```
+
+## Usage
+
+### Basic Execution
+
+Type `/s` or `/script` in chat to see available scripts with auto-completion:
+
+```
+/s deploy
+```
+
+### With Arguments
+
+Pass arguments to scripts:
+
+```
+/s deploy --dry-run
+/script test --verbose --coverage
+```
+
+Arguments are passed directly to the script as `$1`, `$2`, etc.
+
+## Script Descriptions
+
+Add a description to make scripts easier to identify in auto-completion:
+
+```bash
+#!/usr/bin/env bash
+# Description: Run full test suite with coverage
+```
+
+or
+
+```bash
+#!/usr/bin/env bash
+# @description Run full test suite with coverage
+```
+
+The description appears in the command palette and slash command suggestions.
+
+## Execution Context
+
+Scripts run with:
+
+- **Working directory**: The workspace directory (same as bash_tool)
+- **Environment**: Full workspace environment + project secrets + special cmux variables
+- **Timeout**: 5 minutes by default
+- **Streams**: stdout/stderr captured and logged
+
+### Environment Variables
+
+Scripts receive special environment variables for controlling cmux behavior:
+
+#### `CMUX_OUTPUT`
+
+Path to a temporary file for custom toast display content. Write markdown here for rich formatting in the UI toast:
+
+```bash
+#!/usr/bin/env bash
+# Description: Deploy with custom output
+
+echo "Deploying..." # Regular stdout for logs
+
+# Write formatted output for toast display
+cat >> "$CMUX_OUTPUT" << 'EOF'
+## 🚀 Deployment Complete
+
+✅ Successfully deployed to staging
+
+**Details:**
+- Version: 2.1.3
+- Environment: staging
+- Duration: 45s
+EOF
+```
+
+The toast will display the markdown-formatted content instead of the default "Script completed successfully" message.
+
+#### `CMUX_PROMPT`
+
+Path to a temporary file for sending messages to the agent. Write prompts here to trigger agent actions:
+
+```bash
+#!/usr/bin/env bash
+# Description: Rebase with conflict handling
+
+if git pull --rebase origin main; then
+  echo "✅ Successfully rebased onto main" >> "$CMUX_OUTPUT"
+else
+  echo "⚠️ Rebase conflicts detected" >> "$CMUX_OUTPUT"
+
+  # Send conflict details to agent for analysis
+  cat >> "$CMUX_PROMPT" << 'EOF'
+The rebase encountered conflicts. Please help resolve them:
+
+```
+
+$(git status)
+
+```
+
+Analyze the conflicts and propose resolutions.
+EOF
+fi
+```
+
+When the script completes, the prompt file content is automatically sent as a new user message, triggering the agent to respond.
+
+#### Combined Usage
+
+You can use both environment files together:
+
+```bash
+#!/usr/bin/env bash
+# Description: Run tests and report failures
+
+if npm test > test-output.txt 2>&1; then
+  echo "✅ All tests passed" >> "$CMUX_OUTPUT"
+else
+  # Show summary in toast
+  echo "❌ Tests failed" >> "$CMUX_OUTPUT"
+
+  # Ask agent to analyze and fix
+  cat >> "$CMUX_PROMPT" << EOF
+The test suite failed. Please analyze and fix:
+
+\`\`\`
+$(cat test-output.txt)
+\`\`\`
+EOF
+fi
+```
+
+**Result:**
+
+1. Toast displays "❌ Tests failed"
+2. Agent receives test output and starts analyzing
+3. Agent proposes fixes
+
+### File Size Limits
+
+- **CMUX_OUTPUT**: Maximum 10KB (truncated if exceeded)
+- **CMUX_PROMPT**: Maximum 100KB (truncated if exceeded)
+
+## Example Scripts
+
+### Deployment Script
+
+```bash
+#!/usr/bin/env bash
+# Description: Deploy application to specified environment
+set -euo pipefail
+
+ENV=${1:-staging}
+echo "Deploying to $ENV..."
+
+# Build
+npm run build
+
+# Deploy
+aws s3 sync dist/ s3://my-bucket-$ENV/
+echo "Deployment complete!"
+```
+
+### Test Runner
+
+```bash
+#!/usr/bin/env bash
+# Description: Run tests with optional flags
+set -euo pipefail
+
+FLAGS="${@:---coverage}"
+echo "Running tests with: $FLAGS"
+npm test $FLAGS
+```
+
+### Database Migration
+
+```bash
+#!/usr/bin/env bash
+# Description: Run database migrations
+set -euo pipefail
+
+echo "Running migrations..."
+npm run migrate
+echo "Migrations complete!"
+```
+
+## Tips
+
+**Idempotency**: Scripts can run multiple times. Make them idempotent when modifying shared state.
+
+**Error Handling**: Use `set -euo pipefail` to fail fast on errors.
+
+**Logging**: Echo progress messages - they appear in real-time during execution.
+
+**Arguments**: Always handle optional arguments with defaults:
+
+```bash
+ENV=${1:-staging}  # Default to 'staging' if no arg provided
+```
+
+**Exit Codes**: Non-zero exit codes are displayed as warnings in the UI.
+
+## Differences from Init Hooks
+
+| Feature       | Init Hooks (`.cmux/init`)  | Scripts (`.cmux/scripts/*`) |
+| ------------- | -------------------------- | --------------------------- |
+| **When Run**  | Once on workspace creation | On-demand via slash command |
+| **Execution** | Automatic                  | Manual user invocation      |
+| **Use Case**  | Setup dependencies         | Development tasks           |
+| **Arguments** | None                       | Supports arguments          |
+| **Frequency** | One-time per workspace     | Any time, any number        |
+
+## Script Discovery
+
+- Scripts are discovered automatically from `.cmux/scripts/` in the current workspace
+- Only executable files appear in suggestions
+- Non-executable files are ignored
+- Cache refreshes when you switch workspaces
+
+## Keyboard Shortcuts
+
+Use existing chat and command palette shortcuts:
+
+- Type `/s` in chat for inline suggestions
+- `Cmd+Shift+P` (or `Ctrl+Shift+P`) → `/s` for command palette
+- Arrow keys to select, Enter to run
+
+## Troubleshooting
+
+**Script not appearing in suggestions?**
+
+- Ensure file is executable: `chmod +x .cmux/scripts/scriptname`
+- Verify file is in `.cmux/scripts/` directory within your workspace
+- Switch to another workspace and back to refresh the cache
+
+**Script fails with "not found"?**
+
+- Check shebang line is correct: `#!/usr/bin/env bash`
+- Verify script has execute permissions
+- Test script directly: `./.cmux/scripts/scriptname`
+
+**Script times out?**
+
+- Scripts have 5 minute timeout by default
+- Split long-running operations into separate scripts
+- Consider running processes in background if needed