sairam0424/ag-bash

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
| Feature | Description |
| ExecutionPipeline | The composable 6-stage pipeline (normalize, parse, transform, sandbox, interpret, persist) is now the sole execution engine. The legacy monolith path has been removed. |
| Fork-Speculation | bash.fork() creates isolated copy-on-write branches; bash.speculate() runs N candidates in parallel and keeps the winner. Core moat for agentic workflows. |
| Observations at Source | Every command produces typed Observation objects with code and confidence fields, surfacing issues without blocking execution. |
| True Streaming | bash.execStream() yields stdout/stderr chunks via AsyncGenerator as statements produce output, byte-identical to buffered exec. |
| RunLoop v2 | Extended with mode, healer, and memory configuration. AgentMemory now persists across sessions. |
| MCP 2025-06-18 | Protocol bumped to latest spec with back-compat preserved for 2024-11-05 clients. Code Mode slice for structured output. |
| Destructive Detection | AST-based gate detects rm -rf /, fork bombs, and decode-pipe-to-shell patterns structurally. Default policy: WARN. |
| OTEL at Exec Level | Optional AgBashTracer wraps each exec() call in an OpenTelemetry span. Zero overhead when @opentelemetry/api is absent. |
## 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
bash
# 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:
typescript
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):
bash
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
text
/plugin marketplace add sairam0424/ag-bash
/plugin install ag-bash@ag-bash