Shell Execution (Bash)
Relevant source files
The following files were used as context for generating this wiki page:
The Shell Execution system, primarily implemented through the bash tool, provides QQcode with the capability to execute one-off shell commands within the user's local environment. It serves as a versatile utility for system exploration, package management, and version control operations that are not covered by specialized tools like read_file or edit.
Sources: vibe/core/tools/builtins/prompts/bash.md:1-5, CLAUDE.md:37-39
System Overview and Architecture
The bash tool is a stateless component within the QQcode toolset. Each command execution occurs independently in a fresh environment, meaning environment variables or state changes from one call do not automatically persist to the next.
Sources: vibe/core/tools/builtins/prompts/bash.md:5-7
Execution Workflow
When a bash command is requested, the system follows a specific flow involving validation, user approval (depending on configuration), and execution via the platform's default shell.
The diagram above illustrates the logic path from an agent's request to the final display of results in the UI.
Sources: vibe/core/prompts/plan_mode.md:8-12, vibe/cli/textual_ui/widgets/tool_widgets.py:44-50, vibe/core/system_prompt.py:270-280
Execution Environments
The behavior of the shell execution system varies significantly based on the host operating system. The system prompt dynamically adjusts instructions to ensure the agent uses platform-compatible commands.
| Feature | Unix-like (Linux/macOS) | Windows |
|---|---|---|
| Default Shell | sh (via asyncio) | COMSPEC or cmd.exe |
| Path Separators | Forward slashes (/) | Backslashes (\\) |
| Common Commands | ls, grep, cat | dir, where, type |
| Shebang Support | Supported | Not applicable |
Sources: vibe/core/system_prompt.py:270-305
Usage Restrictions and Best Practices
To optimize performance and safety, QQcode enforces strict guidelines on when the bash tool should be used versus specialized internal tools.
Restricted Commands in Plan Mode
When the agent is in "Plan Mode," the bash tool is restricted to read-only operations to prevent accidental state changes during the analysis phase.
- Allowed:
ls,find,tree,pwd,git log,git status,grep,awk,wc. - Blocked:
rm,mv,cp,touch,mkdir,git commit,git push,pip install,curl.
Sources: vibe/core/prompts/plan_mode.md:15-30
Tool Substitution Rules
The system strongly discourages using bash for operations where dedicated tools exist.
| Bash Command | Preferred Tool | Rationale |
|---|---|---|
cat <file> | read_file | Handles encoding and large file chunking |
grep <pattern> | grep | Integrated with project indexing/ripgrep |
sed -i | edit | Provides safer diff-based modifications |
echo "..." > file | write_file | Ensures proper file permission handling |
Sources: vibe/core/tools/builtins/prompts/bash.md:10-40
User Interface Components
The system utilizes specialized Textual widgets to handle the display of bash operations in the CLI.
BashApprovalWidget
This widget presents the command to the user for review before execution. It formats the command in a syntax-highlighted Markdown block.
Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:44-54
# vibe/cli/textual_ui/widgets/tool_widgets.py:44-54
class BashApprovalWidget(ToolApprovalWidget):
def compose(self) -> ComposeResult:
command = self.data.get("command", "")
description = self.data.get("description", "")
if description:
yield Static(description, markup=False, classes="approval-description")
yield Static("")
yield Markdown(f"```bash\n{command}\n```")
BashResultWidget
Once execution is complete, this widget displays the output. It supports a collapsed view by default, which can be expanded using ctrl+o to show full details.
Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:57-73
Git Integration
A significant use case for the bash tool is version control. The system prompt specifically instructs the agent to use git commit via bash when finalizing changes. These commits are automatically appended with a signature:
Co-Authored-By: QQcode <qqcode@qqcode.dev>
Sources: vibe/core/system_prompt.py:308-319
Conclusion
The Bash Execution system provides the necessary "escape hatch" for the agent to interact with the underlying operating system and development tools. By balancing flexibility with strict read-only modes and tool-substitution rules, the project ensures that shell access is used primarily for high-level system tasks while maintaining the safety and efficiency of specialized file manipulation tools.