FAQ

Frequently Asked Questions

Common questions about MAINFRAME.

---

General

What is MAINFRAME?

MAINFRAME is the AI-Native Bash Runtime - a library of 2,000+ pure bash functions designed to make AI agents safer, more accurate, and more efficient when controlling computer systems through bash.

Who is MAINFRAME for?

• AI Agent Developers building autonomous systems
• AI Coding Assistants like Claude Code, Cursor, Aider
• DevOps Engineers who want reliable bash scripts
• Anyone who writes bash and wants better tooling

Why "MAINFRAME"?

The name reflects our mission: providing a solid, reliable foundation (like a mainframe) for AI agents operating in bash environments.

---

Technical

Does MAINFRAME require any dependencies?

No. MAINFRAME is pure bash with zero external dependencies. No jq, sed, awk, python, or other tools required.

The only requirement is Bash 4.0+ (5.0+ recommended).

What bash version do I need?

• Minimum: Bash 4.0
• Recommended: Bash 5.0+

Check your version:

bash --version

Does it work on macOS?

Yes, but macOS ships with Bash 3.x. Install a modern version:

brew install bash

Does it work in Docker?

Yes. Use the bash:5.2 base image:

FROM bash:5.2
RUN git clone https://github.com/gtwatts/mainframe.git /opt/mainframe
ENV MAINFRAME_ROOT=/opt/mainframe

Can I use specific libraries without loading everything?

Yes. Load only what you need:

export MAINFRAME_ROOT="$HOME/.mainframe"
source "$MAINFRAME_ROOT/lib/json.sh"
source "$MAINFRAME_ROOT/lib/validation.sh"

How do I update MAINFRAME?

cd "$MAINFRAME_ROOT"
git pull origin main

---

Functions

How do I find a specific function?

1. CHEATSHEET.md - Complete reference: CHEATSHEET.md
2. Wiki Library Reference - Library Reference
3. Search in code:

   grep -r "function_name" "$MAINFRAME_ROOT/lib/"

Why doesn't json_object use jq?

MAINFRAME prioritizes zero dependencies. json_object creates valid JSON using pure bash, ensuring scripts work everywhere without external tools.

What's the difference between mkdir and ensure_dir?

mkdir	ensure_dir
Fails if exists	Succeeds if exists
Not idempotent	Idempotent
Returns error	Returns status

ensure_dir is safe to run multiple times, making it ideal for AI agents that may retry operations.

What is USOP?

Universal Structured Output Protocol - MAINFRAME's standard for JSON output that AI agents can reliably parse.

export MAINFRAME_OUTPUT=json
output_success "done"
# {"ok":true,"data":"done"}

---

AI Agent Integration

How does MAINFRAME help AI agents?

1. Structured Output - JSON that agents can parse reliably
2. Safe Execution - Guardrails prevent destructive mistakes
3. Idempotency - Operations safe to retry
4. Validation - Input checking prevents errors
5. Token Efficiency - 71% fewer tokens per task

Which AI assistants work with MAINFRAME?

Any AI that can execute bash:

• Claude Code
• Cursor
• Aider
• OpenCode
• Continue
• Custom LLM agents

How do I teach my AI to use MAINFRAME?

1. Add documentation to CLAUDE.md or system prompt
2. Reference CHEATSHEET.md for function lookup
3. Enable JSON output: export MAINFRAME_OUTPUT=json

See AI Coding Assistant Setup for detailed guides.

Can agents use MAINFRAME without internet?

Yes. Once installed, MAINFRAME has no network dependencies. All functions work offline.

---

Security

Is MAINFRAME safe for production?

Yes, with proper configuration:

• Enable AGENT_STRICT_MODE for whitelisting
• Set AGENT_AUDIT_LOG for audit trail
• Validate all paths with validate_path_safe
• Use agent_safe_exec instead of eval

How does agent_safe_exec prevent injection?

It passes arguments as an array, not a string:

# Vulnerable
eval "cat $user_input"  # user_input="file; rm -rf /"

# Safe
agent_safe_exec "cat" "$user_input"  # Tries to cat literal filename

What commands are blocked by default?

Patterns like:

• rm -rf /
• dd if=
• mkfs
• chmod 777
• curl | bash

How do I report security issues?

DO NOT open public issues. Use:

• GitHub Security Advisories
• See SECURITY.md

---

Performance

Is MAINFRAME fast?

Yes. Pure bash operations are 20-72x faster than external tools:

Operation	External	MAINFRAME	Speedup
Trim string	2379ms	33ms	72x
Lowercase	778ms	16ms	49x
JSON create	1200ms	25ms	48x

Will it slow down my shell startup?

By default, all libraries load at source time. For faster startup:

export MAINFRAME_LAZY=1  # Load on first use

Or load only needed libraries.

How can I profile MAINFRAME functions?

# Time a function
time json_object "key=value"

# Run benchmarks
bash "$MAINFRAME_ROOT/benchmarks/superpower_benchmarks.sh"

---

Contributing

How do I contribute?

1. Fork the repository
2. Create a feature branch
3. Write tests (BATS)
4. Follow the style guide
5. Submit a PR

See CONTRIBUTING.md

What's the coding style?

• Pure bash (no external dependencies)
• Functions use snake_case
• Export functions with export -f
• Document with comments
• Add BATS tests

How do I run tests?

cd "$MAINFRAME_ROOT"
git submodule update --init
./tests/bats/bin/bats tests/

---

Support

Where do I get help?

1. Wiki - Documentation
2. Discussions - Q&A
3. Issues - Bug reports
4. Troubleshooting - Common solutions

Is there commercial support?

Currently, MAINFRAME is community-supported. For enterprise needs, open a Discussion.

---

MAINFRAME · The AI-Native Bash Runtime

Home · Installation · Troubleshooting