Ag-Bash: The AI-Native Shell Monorepo

Ag-Bash is a production-grade, sandboxed Bash environment designed specifically for AI agents. It provides a virtualized Unix-like experience entirely in-process, featuring an in-memory filesystem, integrated runtimes for Python and JavaScript, and full support for modern agentic protocols.

🏗️ Monorepo Architecture

This repository is organized into a modular monorepo to support independent versioning and consumption of core engine components and protocol adapters.

Package	Version	Description
@ag-bash/bash		Core Engine: The virtual shell, filesystem, and sandboxed runtimes.
@ag-bash/mcp-server		MCP Server: A standalone Model Context Protocol server for seamless agent integration.
@ag-bash/agent-bridge		Agent Bridge: Terminal UI bridge for AI agent communication.

---

What's New in v4.1

Feature	Description
Agent RunLoop	Autonomous LLM execution loop — feed a goal, get back a completed task. Supports tool calling, streaming, and configurable termination policies.
Self-Healing	Typo correction and auto-retry. When a command fails due to a mistyped name or missing dependency, the engine repairs the environment and retries transparently.
Discoverability	Built-in commands, about, and doctor tools let agents introspect the shell's capabilities, health, and configuration without guessing.

---

Installation

# Latest (recommended)
npm install @ag-bash/bash

# With MCP server
npm install @ag-bash/mcp-server

Subpath imports for tree-shaking and targeted use:

import { Bash, createShell } from "@ag-bash/bash";
import { RunLoop } from "@ag-bash/bash/agent-runtime";
import { createTestBash } from "@ag-bash/bash/testing";

---

🚀 Quick Start

For Developers (Library)

If you are building an application and want to embed a sandboxed shell:

npm install @ag-bash/bash

import { Bash, createShell } from "@ag-bash/bash";

// Quick instantiation
const bash = new Bash();
const result = await bash.exec('echo "Hello Ag-Bash"');
console.log(result.stdout); // "Hello Ag-Bash\n"

// Or use createShell for full configuration
const shell = createShell({ filesystem: "overlay", cwd: "/workspace" });
await shell.exec("ls -la");

2. Standalone CLI & Shell (Global)

For human-in-the-loop debugging and interactive use, install the Ag-Bash suite globally.

Via Homebrew (macOS)

brew tap ag-bash/homebrew-tap
brew install ag-bash

Via NPM (Cross-platform)

npm install -g @ag-bash/bash @ag-bash/mcp-server

---

For AI Agents (MCP)

To provide a bash environment to your agent (e.g., in Claude Desktop or Cursor):

npm install -g @ag-bash/mcp-server

Then, add the server to your MCP configuration:

{
  "mcpServers": {
    "ag-bash": {
      "command": "ag-bash-mcp",
      "args": []
    }
  }
}

---

🛡️ Key Features

• v4.1 Architecture: RunLoop execution model, Tagged Template literals for ergonomic shell scripting, and Self-Healing error recovery with automatic retry and environment repair.
• v3.0 Architecture (Breaking): Dependency Injection via ServiceContainer, restructured BashOptions API with grouped sub-objects, and zero singletons.
• FNV-1a ASTCache: Non-cryptographic hashing with true LRU eviction for high-frequency script execution.
• Pipeline Early Termination: Static AST analysis detects head -N patterns and truncates upstream output.
• Type-Safe Core: Eliminated any types from core services, interpreter, and error hierarchy (unknown throughout).
• Hardened MCP Server: Sanitized JSON-RPC error messages (path stripping, length cap), zero console leakage from library code.
• Project V-Next: (v2.5.0+) Unified Permission Architecture, Real JSON-RPC MCP Client (Stdio/HTTP), and multi-step Planning Mode.
• Nexus Prime Suite: (v2.0.0+) Intelligent semantic analysis (ag-hover, ag-explain), symbol discovery, and persistent project management.
• Agentic Healer 2.0: (v2.4.0+) Tool-aware recovery loop with multi-keyword semantic scoring for automated remediation.
• High-Fidelity Observability: (v2.4.0+) EventEmitter-driven tool tracking with tool:start, tool:progress, and tool:end hooks.
• Tree-sitter AST Parser: High-fidelity shell parsing for complex scripts and security analysis.
• Virtual Filesystem: Choose between InMemoryFs, OverlayFs (COW), or ReadWriteFs.
• Integrated Runtimes: Out-of-the-box support for jq, sqlite3, python3 (WASM), and js-exec (QuickJS).
• Protocol First: Full Model Context Protocol (MCP) support with persistent session state.
• Defense in Depth: Robust sandbox prevents prototype pollution and unauthorized filesystem access.
• No Dependencies: The core engine is lightweight and runs in Node.js or the Browser.

📖 Documentation

• User Guide: Narrative introduction to Ag-Bash, installation, and core concepts.
• Command Registry: Categorized reference for all 110+ supported tools.
• Technical Architecture: Deep dive into the Nexus engine, performance, and resource accounting.
• Shell Engine Deep-Dive: Technical guide for filesystem options and custom commands.
• MCP Server Configuration: Agentic integration patterns and configuration.
• Security & Threat Model: Detailed breakdown of the sandbox architecture.

Version History

Version	Codename	Highlights
v4.1	Runtime	Agent RunLoop, Trap signals, Self-Healing error recovery, OpenTelemetry spans
v3.0	Breaking Redesign	ServiceContainer DI, new BashOptions grouped API, zero singletons
v2.x	Nexus Prime	Agentic tools (ag-hover, ag-explain), MCP integration, Planning Mode
v1.x	Genesis	Initial release, core interpreter, in-memory filesystem, basic builtins

See the CHANGELOG for detailed release notes.

---

📜 License

Apache-2.0