Shell (bash)

The bash tool lets Yukkai execute shell commands on your Mac, providing full access to the Unix command-line toolchain. From git operations to system scripts, package managers to file manipulation — anything you can do in Terminal, Yukkai can do for you.

Overview

The tool returns combined stdout and stderr output. If the command fails, you'll see the error message in the output.

How It Works

• Working directory: Use cd <workspace> as a prefix when you need to run commands in a specific directory.
• Combined output: Both stdout and stderr are returned in a single stream — you see everything the terminal would show.
• Timeout: The process is killed after the specified duration. The default is 120 seconds. Increase it for long-running builds or downloads.
• Environment: Commands run in the user's shell environment with access to all installed tools (git, npm, brew, python, swift, etc.).

Common Use Cases

Git Operations

cd ~/Documents/GIT/MyProject && git status
cd ~/Documents/GIT/MyProject && git log --oneline -10
cd ~/Documents/GIT/MyProject && git diff HEAD~1

Build & Run

cd ~/Documents/GIT/MyApp && swift build
cd ~/Documents/GIT/MyApp && xcodebuild -scheme MyScheme build
cd ~/Projects/api && npm run build

Package Management

brew install jq
pip3 install requests
npm install -g typescript

System Information

sw_vers                    # macOS version
sysctl -n machdep.cpu.brand_string   # CPU info
df -h                      # Disk space
top -l 1 -n 0              # System summary

File Operations

ls -la ~/Documents
mkdir -p ~/Projects/new-app/src
cp -r ~/Templates/swift-app ~/Projects/new-app
find . -name "*.swift" | wc -l

Important Rules

Do NOT use heredocs for file creation

# ❌ Never do this
cat << EOF > file.txt
content here
EOF

# ✅ Use file_write instead
file_write(file_path: "file.txt", content: "content here")

The file_write tool is the correct way to create files. Heredocs in bash are error-prone and can truncate content.

Prefer specialized tools

The specialized tools provide better error handling, structured output, and safety checks. Reserve bash for operations that genuinely need the shell — process management, git, builds, installs, scripting.

Timeout awareness

Long-running processes like npm install, xcodebuild, or docker build may exceed the default 120-second timeout. Set a higher timeout:

bash(command: "cd ~/Project && xcodebuild build", timeout: 600)

Examples

Check project state

bash(command: "cd ~/Documents/GIT/MyProject && git branch && git status --short")

Install dependencies

bash(command: "cd ~/Projects/api && npm install", timeout: 300)

Run tests

bash(command: "cd ~/Documents/GIT/MyApp && swift test", timeout: 300)

Quick file count

bash(command: "find ~/Documents/GIT/MyProject -name '*.swift' | wc -l")

Process management

bash(command: "ps aux | grep node")
bash(command: "kill -9 12345")

Tips

• Chain commands with && to ensure sequential execution only on success.
• Use cd prefix to set the working directory — each bash call starts in the default working directory.
• Check exit status by examining the output for error messages — the tool returns combined stdout+stderr.
• Avoid interactive commands — tools like vim, top, or less that wait for input will hang until timeout.
• Quote paths with spaces — use "/Users/name/My Documents" not /Users/name/My Documents.