MAINFRAME

The AI-Native Bash Runtime

+======================================================================+
|  ___  ___  ___  _____ _   _ ______ _____   ___  ___  ___ _____       |
|  |  \/  | / _ \|_   _| \ | ||  ___|  __ \ / _ \ |  \/  ||  ___|      |
|  | .  . |/ /_\ \ | | |  \| || |_  | |__) / /_\ \| .  . || |__        |
|  | |\/| ||  _  | | | | . ` ||  _| |  _  /|  _  || |\/| ||  __|       |
|  | |  | || | | |_| |_| |\  || |   | | \ \| | | || |  | || |___       |
|  \_|  |_/\_| |_/\___/\_| \_/\_|   \_|  \_\_| |_/\_|  |_/\____/       |
|                                                                      |
|     AI agents control computers through bash.                        |
|     MAINFRAME makes that safe, accurate, and efficient.              |
+======================================================================+

<div align="center">

AI agents control computers through bash. MAINFRAME makes that safe, accurate, and efficient.

3,821+ Pure Bash Functions | 152 Libraries | Zero Dependencies | AI-Native Runtime

</div>

---

Quick Install

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/gtwatts/mainframe/main/get-mainframe.sh | bash

Manual Install

git clone https://github.com/gtwatts/mainframe.git ~/.mainframe
~/.mainframe/install.sh

Verify installation:

source ~/.bashrc  # or restart your terminal
source "$MAINFRAME_ROOT/lib/common.sh" && uuid

That's it. Your AI agents now have a safe, efficient bash runtime with persistent memory.

For detailed installation options, see INSTALL.md.

---

What is MAINFRAME?

MAINFRAME is the runtime layer between AI agents and the operating system.

AI agents - whether Claude Code, Codex, Gemini, Cursor, or custom LLM-powered tools - interact with computers primarily through bash. They write shell commands to navigate filesystems, manipulate data, manage processes, and orchestrate system operations.

The problem: AI agents have finite context windows and bash is hostile territory.

| Problem | MAINFRAME Solution | |---------|-------------------| | Context windows fill up, losing critical state | Agent Working Memory (AWM) - persistent storage outside context | | Commands fail silently or with cryptic errors | Structured Output (USOP) - JSON envelopes with clear error codes | | Output is unstructured and unparseable | Typed Responses - every operation returns parseable JSON | | Security vulnerabilities are one typo away | Validation Layer - input sanitization, path traversal prevention | | Sub-agents can't inherit learnings from parent agents | AWM Inheritance - child agents receive parent discoveries | | External tools (jq, sed, awk) may not exist | Zero Dependencies - pure bash 4.0+, no external tools required |

MAINFRAME provides:

| Capability | What It Means | |------------|---------------| | Agent Working Memory (AWM) | Persistent memory OUTSIDE the context window - sessions, checkpoints, discoveries survive between turns | | Safe Execution | Validation before action, guardrails against damage, no accidental rm -rf / | | Structured Output | JSON envelopes for every operation - AI parses results reliably | | First-Time Correctness | Clear errors, predictable behavior, no trial-and-error loops | | Sub-Agent Inheritance | Child agents inherit discoveries and state from parent agents | | Zero Dependencies | Pure bash. Works on any system with bash 4.0+. No jq, no sed, no awk required. |

# One line gives AI access to 3,821+ battle-tested functions
source "${MAINFRAME_ROOT}/lib/common.sh"

---

Agent Working Memory (AWM)

The breakthrough feature for AI agents with finite context windows.

AI agents forget everything outside their context window. AWM gives them a file-backed working memory that survives context limits, interruptions, and crashes.

Golden Path

# Start a canonical AWM session
sid=$(awm_init "security-audit" --namespace review --model gpt-4o --backend file)
awm_resume "$sid"

# Persist high-signal state outside the context window
awm_checkpoint "current_phase" "scanning" --importance high
awm_discovery "Auth uses JWT refresh tokens" --importance critical --tags auth,jwt
awm_log "decisions" "Prefer PostgreSQL for transactional guarantees" --importance high
awm_progress "scan" "12/40" "Scanning auth module"

# Retrieve only what the next step needs
results=$(awm_find "jwt postgres" --kind mixed --limit 5)
ctx=$(awm_context_for "dependency review" --tokens 2000)

# Hand off to a sub-agent or later continuation
handoff=$(awm_handoff_prepare "dependency-reviewer" --tokens 2000)

Why It Matters

• Persistent state: checkpoints, discoveries, logs, and progress survive across turns.
• Deterministic retrieval: awm_find and awm_context_for pull back the highest-signal memory instead of replaying the whole session.
• Clean handoffs: awm_handoff_prepare and awm_handoff_accept turn memory transfer into a first-class product surface.
• Safe defaults: file-backed storage is the default; advanced backends are opt-in.
• Migration path: older sessions upgrade in place with awm_migrate.

Canonical AWM Surface

| Function | Purpose | |----------|---------| | awm_init | Create a new session, optionally inheriting from a parent | | awm_resume | Resume a session by ID | | awm_checkpoint | Store persistent key/value state with metadata | | awm_discovery | Record critical insights that should stay visible | | awm_log | Append structured categorized events | | awm_progress | Track current progress and latest task state | | awm_find | Search discoveries, checkpoints, and logs | | awm_context_for | Build a deterministic context package for a task | | awm_handoff_prepare | Create a budgeted handoff package | | awm_handoff_accept | Accept a handoff into a receiving session | | awm_status / awm_doctor | Inspect session health, schema, and layout | | awm_export / awm_migrate | Export human-readable reports and upgrade older sessions |

CLI

sid=$(mainframe awm init security-audit --namespace review)
mainframe awm checkpoint --session "$sid" current_phase scanning --importance high
mainframe awm discovery --session "$sid" "JWT refresh tokens enabled" --importance critical
mainframe awm find --session "$sid" jwt --kind mixed
mainframe awm handoff prepare --session "$sid" reviewer --tokens 2000
mainframe awm doctor --session "$sid"

---

Why MAINFRAME?

The Problem

AI agents write fragile bash that:

• Loses state - Context window resets, all learning lost
• Fails unpredictably - External tools like jq, sed, awk may not exist
• Requires retries - Cryptic errors need multiple attempts to debug
• Causes damage - No guardrails against destructive operations
• Wastes tokens - Verbose scripts consume context window
• Can't coordinate - Sub-agents start from scratch

Every failed command costs tokens, time, and trust.

The Solution

MAINFRAME provides a safe runtime with persistent memory and first-time correctness:

# WITHOUT MAINFRAME - AI writes fragile, volatile code
str="  hello  "
str="${str#"${str%%[![:space:]]*}"}"  # Cryptic parameter expansion
str="${str%"${str##*[![:space:]]}"}"  # Fails if AI forgets a quote
# State lost when context window fills

# WITH MAINFRAME - Safe, readable, persistent
source "$MAINFRAME_ROOT/lib/common.sh"
awm_init "my-task"
trim_string "  hello  "                              # Safe, tested
awm_checkpoint "processed" "$str"                    # Persists outside context
awm_discovery "String contained leading whitespace"  # Learning preserved

Result: AI agents complete tasks in one pass, remember what they learned, and pass knowledge to sub-agents.

---

For AI Agent Developers

MAINFRAME is designed for teams building autonomous AI systems that interact with operating systems through bash.

Universal Structured Output Protocol (USOP)

Every MAINFRAME operation can return structured JSON that AI agents parse reliably:

export MAINFRAME_OUTPUT=json

# Operations return structured envelopes
output_success "file created" "verify_file"
# {"ok":true,"data":"file created","hint":"verify_file","meta":{"elapsed_ms":2}}

output_error "E_NOT_FOUND" "Config missing" "run init first"
# {"ok":false,"error":{"code":"E_NOT_FOUND","msg":"Config missing","suggestion":"run init first"}}

# Typed outputs for type-safe parsing
output_int 42                    # {"ok":true,"data":42}
output_bool true                 # {"ok":true,"data":true}
output_json_object '{"id":1}'    # {"ok":true,"data":{"id":1}}

Why this matters: AI agents don't need to parse free-form text. They receive structured data they can act on immediately.

Safe Command Dispatch

MAINFRAME never uses eval. All operations validate inputs before execution:

# Path validation prevents directory traversal attacks
validate_path_safe "$user_input" "/allowed/base" || die 1 "Invalid path"

# Command validation blocks injection attempts
validate_command_safe "$cmd" || die 1 "Command rejected"

# Sanitization for all user-provided data
sanitized=$(sanitize_shell_arg "$untrusted_input")

Idempotent Operation