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 v6.0.0

Installation & Distribution

Requires Node.js >=20.6.0. For full ESM-hook security hardening, Node.js >=23.5 is recommended.

Ag-Bash ships across multiple channels (current version 6.0.4, synchronized across all npm packages):

npm library

# Core engine (recommended)
npm i @ag-bash/bash

# With the standalone 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";

MCP server (npx / MCP Registry)

The MCP server exposes 70 tools over stdio. Add it to Claude Code in one command (no global install needed):

claude mcp add ag-bash -- npx -y @ag-bash/mcp-server
# or run it directly
npx @ag-bash/mcp-server

It is also published to the MCP Registry as io.github.sairam0424/ag-bash.

A submission to the Docker MCP Catalog (docker/mcp-registry) is currently in review.

Claude Code plugin

/plugin marketplace add sairam0424/ag-bash
/plugin install ag-bash@ag-bash

Homebrew (macOS)

brew tap sairam0424/tap
brew install ag-bash

This also installs the ag-shell and ag-bash-mcp binaries.

🚀 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 sairam0424/tap
brew install ag-bash

This installs the ag-bash, ag-shell, and ag-bash-mcp binaries.

#### 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 Code, Claude Desktop, or Cursor), register the MCP server via npx — no global install required:

claude mcp add ag-bash -- npx -y @ag-bash/mcp-server

Or add the server to your MCP configuration manually:

{
  "mcpServers": {
    "ag-bash": {
      "command": "npx",
      "args": ["-y", "@ag-bash/mcp-server"]
    }
  }
}

🛡️ Key Features

• v6.0 Architecture: ExecutionPipeline as sole engine, fork-speculation, observations-at-source, true streaming, OTEL tracing, destructive-detection gate.
• v6.0 RunLoop: Autonomous LLM execution loop with observation forwarding, AgenticHealer self-correction, AgentMemory persistence, plan-mode write-gating, and BudgetManager stopping conditions.
• v3.0 DI (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](./docs/user-guide.md): Narrative introduction to Ag-Bash, installation, and core concepts.
• [Command Registry](./docs/COMMAND_REGISTRY.md): Categorized reference for all 110+ supported tools.
• [Technical Architecture](./docs/ARCHITECTURE.md): Deep dive into the Nexus engine, performance, and resource accounting.
• [Shell Engine Deep-Dive](./packages/bash/README.md): Technical guide for filesystem options and custom commands.
• [MCP Server Configuration](./packages/mcp-server/README.md): Agentic integration patterns and configuration.
• [Security & Threat Model](./THREAT_MODEL.md): Detailed breakdown of the sandbox architecture.

Version History

See the CHANGELOG for detailed release notes.

📜 License

Apache-2.0