Home
The AI-Native Bash Runtime
AI agents control computers through bash. MAINFRAME makes that safe, accurate, and efficient.
MAINFRAME is the runtime layer between AI agents and the operating system. It provides:
| Capability | Description |
|---|---|
| 2,000+ Pure Bash Functions | Complete standard library with zero external dependencies |
| Safe Execution | Validation before action, guardrails against damage |
| Structured Output (USOP) | JSON envelopes for every operation |
| First-Time Correctness | Clear errors, predictable behavior, no trial-and-error |
| Token Efficiency | 71% fewer tokens per bash task |
AI agents—whether Claude Code, GPT-4, Cursor, or custom LLM-powered tools—interact with computers primarily through bash. They write shell commands to:
- Navigate filesystems
- Manipulate data
- Manage processes
- Orchestrate system operations
The problem: Bash is hostile territory for AI.
- Commands fail silently or with cryptic errors
- Output is unstructured and unparseable
- Security vulnerabilities are one typo away
- Edge cases cause cascading failures
- Retries waste tokens and time
MAINFRAME solves this by providing a safe, predictable runtime with structured output that AI agents can reliably parse and act upon.
# Install MAINFRAME
git clone https://github.com/gtwatts/mainframe.git ~/.mainframe
echo 'export MAINFRAME_ROOT="$HOME/.mainframe"' >> ~/.bashrc
echo 'source "$MAINFRAME_ROOT/lib/common.sh"' >> ~/.bashrc
source ~/.bashrc
# Verify installation
mainframe version
# MAINFRAME v5.0 - 2,000+ functions | 77 libraries | Pure BashSee the full Installation Guide for detailed instructions.
| Page | Description |
|---|---|
| Installation | Complete installation guide with all methods |
| Quick Start | Get productive in 5 minutes |
| Troubleshooting | Common issues and solutions |
| FAQ | Frequently asked questions |
| Page | Description |
|---|---|
| Library Reference | Overview of all 77 libraries |
| USOP Protocol | Universal Structured Output Protocol |
| Configuration | Environment variables and settings |
| Page | Description |
|---|---|
| AI Agent Integration | Integration patterns for autonomous systems |
| Agent Safety | Safe command execution library |
| Agent Communication | Multi-agent coordination |
| Idempotent Operations | Retry-safe functions |
| Security Best Practices | Secure agent development |
| Page | Description |
|---|---|
| AI Coding Assistant Setup | Setup for Claude Code, Cursor, Aider, etc. |
MAINFRAME provides 77 libraries organized into categories:
json.sh · csv.sh · pure-string.sh · pure-array.sh · template.sh
pure-file.sh · proc.sh · env.sh · path.sh · docker.sh · k8s.sh
http.sh · crypto.sh · git.sh · datetime.sh
validation.sh · guard.sh · error.sh · safe.sh
output.sh · agent_safety.sh · agent_comm.sh · idempotent.sh · atomic.sh · observe.sh
typescript.sh · python.sh
ansi.sh · tui.sh · cli.sh · log.sh
See the Library Reference for complete documentation.
- GitHub Discussions - Ask questions, share ideas
- Issues - Report bugs, request features
- Contributing - How to contribute
- Full Function Reference (CHEATSHEET.md) - All 2,000+ function signatures
- README - Project overview
- SECURITY.md - Security policy
MAINFRAME · The AI-Native Bash Runtime
"Knowing Your Shell is half the battle."