Shell Execution
Relevant source files
The following files were used as context for generating this wiki page:
Shell execution in the plugsuits project provides the agent with the capability to perform system-level operations, build tasks, and version control workflows. It serves as a fallback for operations that truly require a shell environment, such as git, npm, or running tests, while enforcing strict safety boundaries to prevent the agent from bypassing dedicated file-management tools.
The system is designed to handle timeouts, background processes, and environment-specific shell detection (e.g., bash, zsh, or cmd.exe). It integrates with the project's rendering layer to provide clear feedback on command outputs, exit codes, and execution status.
Sources: packages/cea/src/tools/AGENTS.md, packages/cea/src/context/system-prompt.ts:60-65, packages/cea/src/skills/git-workflow.md:17-19
Core Architecture and Logic
The shell execution module identifies the appropriate system shell and executes commands within a specified working directory. The execution flow includes environment detection, command invocation, and result capture (stdout, stderr, and exit codes).
Shell Detection and Configuration
The system automatically detects the available shell on the host machine. On Unix-like systems, it prioritizes SHELL environment variables or falls back to common paths like /bin/bash or /bin/zsh. On Windows, it looks for bash.exe or cmd.exe.
The system ensures that the selected shell is valid and executable before use.
Sources: packages/cea/src/tools/utils/execute/shell-detection.test.ts:58-100
Command Execution Lifecycle
When a command is executed via shell_execute, the system monitors the process for completion or timeouts.
| Feature | Description |
|---|---|
| Timeout Handling | Commands exceeding the timeoutMs (defaulting to 300ms in some tests) are terminated and return a [TIMEOUT] prefix. |
| Background Processes | Commands ending with & are detected as background processes, returning an immediate "Background process started" message. |
| Workdir Scoping | Commands can be restricted to a specific directory using the workdir option. |
| Output Merging | Stdout and Stderr are combined into a single output string for the agent. |
Sources: packages/cea/src/tools/execute/shell-execute.test.ts:47-51, packages/cea/src/tools/execute/shell-execute.test.ts:88-115
Safety and Constraints
The shell_execute tool is subject to strict "Anti-Patterns" and safety guardrails to ensure the agent uses the most efficient tool for a given task.
Forbidden Commands
The system explicitly rejects shell commands that attempt to perform operations for which specialized tools exist. This prevents the agent from using less deterministic or less safe shell utilities for file inspection.
| Forbidden Shell Command | Suggested Alternative | Reason |
|---|---|---|
cat, head, tail | read_file | Dedicated tools handle large files and hash-anchored edits better. |
grep, rg | grep_files | Provides structured output and hashline support. |
find, ls | glob_files | Better discovery and path handling. |
sed, awk | edit_file | Prevents non-deterministic file mutations. |
Sources: packages/cea/src/context/system-prompt.ts:66-70, packages/cea/src/tools/execute/shell-execute.test.ts:63-80
Workspace Integrity
The system detects workspace-specific configurations. For example, if a command like npm test is run in a repository that uses pnpm, the shell execution will fail with a message directing the agent to use the correct package manager.
Sources: packages/cea/src/tools/execute/shell-execute.test.ts:82-85
Rendering and Interaction
The project uses a specialized renderer to display shell execution results in the Terminal UI (TUI). This renderer processes the raw output and exit codes into a structured block.
The renderer truncates long outputs to maintain readability and highlights error states if the exit code is non-zero.
Sources: packages/cea/src/interaction/tool-renderers.ts:489-518
Usage Patterns: Git Workflow
A primary use case for shell execution is the Git Workflow. This workflow involves a sequence of shell commands to manage branches, commits, and pull requests.
Standard Workflow Sequence
- Status Check:
git status - Branch Creation:
git checkout -b feature/name - Staging:
git add . - Commit:
git commit -m "feat: description" - Remote Push:
git push -u origin feature/name - PR Creation:
gh pr create --title "..." --body "..."
Sources: packages/cea/src/skills/git-workflow.md:53-110
Command Safety Levels
The Git workflow skill categorizes shell commands by risk:
- Safe:
status,branch,log,diff. - Careful:
checkout -b,add,commit,push. - Dangerous:
push --force,reset --hard,rebase.
Sources: packages/cea/src/skills/git-workflow.md:32-49
Conclusion
Shell Execution serves as the "power user" interface for the agent, enabling complex interactions with the underlying operating system and development toolchains. By combining environment-aware shell detection with rigorous safety checks and structured output rendering, the system provides a robust execution environment that prioritizes the use of safer, project-specific tools whenever possible.