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

Parameter	Type	Required	Description
command	string	Yes	Shell command to execute
timeout	integer	No	Timeout in seconds (default: 120)

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

Task	Use	Not
Read a file	file_read	cat file
Write a file	file_write	echo > file
Edit a file	file_edit	sed -i
Find files	glob	find
Search file contents	grep	grep -rn

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.