Interactive Bash & Shell
Relevant source files
The following files were used as context for generating this wiki page:
The Interactive Bash and Shell system within Oh-My-OpenCode provides AI agents with a powerful environment for executing terminal commands, managing long-running processes, and performing complex CLI-based verifications. This system is primarily utilized via the interactive_bash tool, often running within a tmux session to allow for persistent interactions, keystroke injection, and real-time output validation.
In the context of the project, this system serves as the backbone for technical execution tasks such as running test suites (e.g., bun test), executing git operations via the Git Master skill, and performing automated Quality Assurance (QA) scenarios. It bridges the gap between high-level agent planning and the underlying operating system.
Sources: src/agents/prometheus/plan-template.ts:74-78, src/features/builtin-skills/skills/git-master.ts:47-60
Architecture and Core Components
The shell execution environment is designed to be asynchronous and parallel-capable. Primary agents like Sisyphus and Hephaestus utilize the shell to perform codebase assessments, run build commands, and verify implementation results.
Execution Flow
The following diagram illustrates how an agent interacts with the shell to verify a task.
The system leverages tmux to manage TUI (Terminal User Interface) applications, allowing the agent to send specific keys and assert that the output contains expected strings.
Sources: src/agents/prometheus/plan-template.ts:133-140, sisyphus-prompt.md:154-158
Key Verification Tools
Agents use specific shell-based tools depending on the deliverable type:
| Deliverable Type | Primary Tool | Verification Method |
|---|---|---|
| TUI / CLI | interactive_bash (tmux) | Run command, send keys, validate stdout/stderr |
| API / Backend | Bash (curl / httpie) | Send requests, parse JSON responses, assert status |
| Library / Module | Bash (REPL) | Import module, call functions, compare outputs |
| Config / Infra | Bash (Shell) | Apply config, run state checks, validate environment |
Sources: src/agents/prometheus/plan-template.ts:80-90
Git Master: Advanced Shell Operations
The git-master skill represents one of the most sophisticated uses of the shell system. It combines three specializations: Commit Architect, Rebase Surgeon, and History Archaeologist. It relies heavily on parallel shell command execution to minimize latency during context gathering.
Parallel Context Gathering
Before performing operations, the system executes multiple shell groups in parallel:
# Group 1: Current state
git status
git diff --staged --stat
# Group 2: History context
git log -30 --oneline
# Group 3: Branch context
git branch --show-current
git merge-base HEAD main
Sources: src/features/builtin-skills/skills/git-master.ts:14-16, src/features/builtin-skills/git-master/SKILL.md:46-60
Interaction Sequence for Rebase
The shell system handles interactive operations like rebasing by using environment variables to automate what would normally require human input.
The use of GIT_SEQUENCE_EDITOR=: allows the agent to perform "interactive" rebases autonomously by auto-accepting the todo list generated by Git.
Sources: src/features/builtin-skills/skills/git-master.ts:314-320, src/features/builtin-skills/git-master/SKILL.md:314-320
Agent-Executed QA Scenarios
A critical constraint of the shell system is the Universal Rule: Zero Human Intervention. All shell-based verification must be executable by the agent alone.
Scenario Requirements
Every shell task must include detailed scenarios following a strict format:
- Tool: Explicitly naming
interactive_bashorBash. - Steps: Exact commands or keystrokes (e.g.,
Send "q" then Enter). - Assertions: Concrete observable outcomes (e.g.,
Assert exit code 0). - Evidence: Paths for terminal output captures (e.g.,
.sisyphus/evidence/task-1-output.txt).
Sources: src/agents/prometheus/plan-template.ts:100-115
Example CLI Verification Snippet
Scenario: CLI loads config and displays menu
Tool: interactive_bash (tmux)
Steps:
1. tmux new-session: ./my-cli --config test.yaml
2. Wait for: "Configuration loaded" in output
3. Assert: Menu items visible
4. Send keys: "3" then Enter
5. Assert: Process exited with code 0
Sources: src/agents/prometheus/plan-template.ts:153-165
Operational Constraints and Anti-Patterns
To ensure stability and deterministic behavior, the system enforces several shell-specific constraints.
Forbidden Actions
- Interactive Input: Using commands that require manual user input (e.g.,
git add -iorgit rebase -iwithout editor overrides) is strictly forbidden. - Sleep Commands: Using
sleep Nis discouraged; agents should use conditional waits (e.g., waiting for a specific string in the output). - Directory Management: Using
cd dir && cmdis an anti-pattern; agents are instructed to use theworkdirparameter provided by the shell tools. - File Operations: Using
mkdir,touch, orrmdirectly in code is forbidden; these must be executed via the bash tool.
Sources: src/agents/hephaestus.ts:190-200, src/agents/sisyphus.ts:400-410, sisyphus-prompt.md:145-155
Summary
The Interactive Bash & Shell system is a high-discipline environment that empowers agents to act as "Senior Staff Engineers" by providing direct, automated access to the terminal. By enforcing strict verification rules and utilizing tools like tmux for TUI management, the project ensures that code changes are not only implemented but also rigorously tested and verified without human oversight.