# io.github.sairam0424/ag-bash (npm · @ag-bash/mcp-server)

Sandboxed AI-native bash with 70 agentic tools: run_bash, code edit/diff, WASM Python/JS.

- Trust score: 57/100 (low)
- Change this week: +13
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@ag-bash/mcp-server`: 57/100 (this document), [markdown](https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server.md), [page](https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@ag-bash/mcp-server`
- Version: `6.0.4`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (123 of 134), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (123 of 134), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 48 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 45/100
  - 2% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 5396 tokens (~16/item across 328 items; 70 tools + 258 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: two runs of the same published version returned different tool surfaces, so we cannot tell a change in the package from a difference in our own sandbox run.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (11% of tools); any adoption earns full credit.
- **Capabilities**: 60/100
  - Spec-recency check failed: implements MCP spec 2025-06-18; the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

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

### Codex

```bash
codex mcp add sairam0424-ag-bash -- npx -y @ag-bash/mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sairam0424-ag-bash": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@ag-bash/mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sairam0424-ag-bash --command npx --arg -y --arg @ag-bash/mcp-server
```

### Hermes

```yaml
mcp_servers:
  sairam0424-ag-bash:
    command: "npx"
    args: ["-y", "@ag-bash/mcp-server"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 57, +37)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security] Stability: Stability not yet verified: two runs of the same published version returned different tool surfaces, so we cannot tell a change in the package from a difference in our own sandbox run.
- [functional regression] MCP protocol: unverified → fail
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Schema quality: unverified → 2
- [functional improvement] Schema quality: unverified → good
- [functional] Licence: Apache-2.0

### 2026-08-01 (score 20, +1)

- [security improvement] Malware scan: unverified → pass
- [functional regression] Schema quality: 2 → unverified
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-31 (score 19, +13)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 6, −38)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 2 → unverified
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-27 (score 44)

First indexed and scored.

## MCP tools (70)

### `run_bash` (~44 tokens)

Run a bash script in a persistent sandboxed environment. State (cwd, variables, functions) persists between calls.

Input parameters:

- `script` (string, required): The bash script to execute.

Output parameters:

- `exitCode` (number): Process exit code (0 = success).
- `stderr` (string): Standard error captured from the script.
- `stdout` (string): Standard output captured from the script.

### `get_state` (~22 tokens)

Retrieve the current state of the shell (CWD and Environment Variables).

Output parameters:

- `cwd` (string): Current working directory of the shell.
- `env` (object): Environment variables.

### `snapshot` (~22 tokens)

Capture a complete binary snapshot of the current shell state (filesystem + environment).

Output parameters:

- `encoded` (string): Base64-encoded opaque state blob.

### `restore` (~34 tokens)

Restore the shell to a previously captured state via a snapshot.

Input parameters:

- `snapshot` (string, required): The base64 encoded snapshot state to restore.

Output parameters:

- `message` (string): Human-readable status message.
- `ok` (boolean): Whether the operation succeeded.

### `create_delta` (~37 tokens)

Create a differential delta between a base snapshot and current state for efficient sync.

Input parameters:

- `baseSnapshot` (string, required): The base64 encoded base snapshot.

Output parameters:

- `encoded` (string): Base64-encoded opaque state blob.

### `apply_delta` (~32 tokens)

Apply a differential delta to the current shell state.

Input parameters:

- `delta` (string, required): The base64 encoded delta to apply.

Output parameters:

- `message` (string): Human-readable status message.
- `ok` (boolean): Whether the operation succeeded.

### `fork_speculate` (~160 tokens)

Fork-speculation: copy-on-write branch the sandbox into N isolated children, run a candidate script sequence in each branch in parallel, and report each branch's output + exit code so you can pick a winner. Branch mutations (env, cwd, files) are invisible to the persistent shell and to each other. Optionally pass keepWinner to commit exactly one winning branch's scripts onto the persistent shell; otherwise the persistent shell is left untouched (all branches discarded).

Input parameters:

- `branches` (array, required): Candidate branches to try. Each branch is an array of bash scripts run in order within its own isolated fork.
- `keepWinner` (number): Optional 0-based index of the branch to commit onto the persistent shell. Omit to keep none (pure speculation).

Output parameters:

- `branches` (array): Per-branch results.
- `committed` (number)

### `search_tools` (~85 tokens)

Discover which agentic tools are available for a free-text task description (Code Mode). Returns the best-matching tools by relevance so an agent can pick a tool without pre-loading the full catalog.

Input parameters:

- `limit` (number): Maximum number of matches to return (1-25, default 5).
- `query` (string, required): Free-text description of the task or capability you need.

Output parameters:

- `matches` (array): Matching tools, best first.
- `query` (string): The query that was searched.

### `add_todo` (~34 tokens)

Add a new todo item.

Input parameters:

- `status` (string): Initial status.
- `task` (string, required): The task description.

### `ag_convert` (~150 tokens)

Convert documents (PDF, Docx, Xlsx) and images to Markdown with AI-powered visual intelligence and OCR.

Input parameters:

- `describeImages` (boolean): Use AI to describe images (default: false).
- `engine` (string): Engine override (default: auto).
- `filePath` (string, required): Path to the file to convert.
- `highFidelity` (boolean): Favor precision over speed (default: false).
- `llmModel` (string): Specific model for vision tasks.
- `llmProvider` (string): LLM provider for vision tasks.
- `visionMode` (string): Prompt template for image analysis.
- `visionPrompt` (string): Custom vision prompt (overrides visionMode).

### `ag_edit` (~93 tokens)

Advanced line-based file editor. Supports multiple non-contiguous edits in a single call and protects against stale writes using content hashes.

Input parameters:

- `edits` (string, required): List of edits to apply sequentially.
- `expectedHash` (string): The expected SHA-256 hash of the file content before applying edits. If it doesn't match, the edit will fail.
- `filePath` (string, required): Absolute path to the file to edit.

### `ag_explain` (~36 tokens)

Parse and explain a shell command string, showing its structure and components.

Input parameters:

- `command` (string, required): The shell command string to explain.

### `ag_find_files` (~51 tokens)

Find files by name or glob pattern recursively.

Input parameters:

- `path` (string): The directory to start searching from (default: current directory).
- `pattern` (string, required): The filename or glob pattern to search for.

### `ag_find_symbol` (~51 tokens)

Search for symbols (functions, variables, classes) by name or pattern across the workspace.

Input parameters:

- `query` (string, required): The symbol name or search pattern.
- `type` (string): Filter by symbol type.

### `ag_grep` (~64 tokens)

High-performance recursive pattern search within files.

Input parameters:

- `ignoreCase` (boolean): Whether to ignore case when searching.
- `path` (string): The directory or file to search in (default: current directory).
- `query` (string, required): The pattern or string to search for.

### `ag_hover` (~63 tokens)

Get semantic information about a symbol at a specific line and character position.

Input parameters:

- `character` (number, required): 1-indexed character position.
- `filePath` (string, required): Path to the file containing the symbol.
- `line` (number, required): 1-indexed line number.

### `ag_lsp` (~91 tokens)

Advanced code intelligence: goToDefinition, findReferences, hover, etc.

Input parameters:

- `character` (number): 1-based character position.
- `filePath` (string, required): Path to the file.
- `line` (number): 1-based line number.
- `operation` (string, required): The LSP operation to perform.
- `symbolName` (string): Name of the symbol (optional if position is provided).

### `ag_multi_edit` (~49 tokens)

Apply multiple non-contiguous text replacements to a file in a single operation.

Input parameters:

- `chunks` (string, required): List of replacement chunks.
- `path` (string, required): Absolute path to the file to edit.

### `ag_todo` (~88 tokens)

Manage project tasks and todos. Support for listing, adding, updating, and removing tasks.

Input parameters:

- `id` (string): The todo ID (required for 'update' and 'rm').
- `operation` (string, required): The operation to perform.
- `status` (string): The status to set (required for 'update').
- `task` (string): The task description (required for 'add').

### `ag_web_fetch` (~63 tokens)

Fetch the content of a web page and convert it to clean markdown. Results are cached for 15 minutes.

Input parameters:

- `noCache` (boolean): If true, bypass the cache and fetch fresh content.
- `url` (string, required): The URL of the page to fetch.

### `ag_web_search` (~61 tokens)

Search the web for current information, documentation, and answers.

Input parameters:

- `allowed_domains` (string): Restrict results to these domains.
- `blocked_domains` (string): Exclude results from these domains.
- `query` (string, required): The search query to execute.

### `agent_memory_read` (~54 tokens)

Read a memory entry for an agent type.

Input parameters:

- `agentType` (string, required): Agent type identifier.
- `key` (string, required): Memory key.
- `scope` (string, required): Memory scope: user, project, or local.

### `agent_memory_write` (~63 tokens)

Write a memory entry for an agent type.

Input parameters:

- `agentType` (string, required): Agent type identifier.
- `key` (string, required): Memory key.
- `scope` (string, required): Memory scope: user, project, or local.
- `value` (string, required): Memory value.

### `analyze_code` (~30 tokens)

Perform semantic analysis on a source file.

Input parameters:

- `path` (string, required): Absolute path to the file to analyze.

### `check_destructive` (~50 tokens)

Check if a command contains destructive patterns (rm -rf, DROP TABLE, git reset --hard, etc.). Returns warning or null.

Input parameters:

- `command` (string, required): The command to analyze for destructive patterns.

### `check_environment` (~16 tokens)

Get diagnostics about the sandboxed environment.

### `close_session` (~33 tokens)

Terminate a persistent session and release its resources.

Input parameters:

- `sessionId` (string, required): The ID of the session to close.

### `cron_create` (~94 tokens)

Schedule a recurring or one-shot prompt using a cron expression.

Input parameters:

- `cron` (string, required): 5-field cron expression (e.g., "*/5 * * * *").
- `durable` (boolean): True = persisted, false = session-only (default).
- `prompt` (string, required): The prompt/command to run at each fire time.
- `recurring` (boolean): True = repeating (default), false = one-shot.

### `cron_delete` (~27 tokens)

Delete a scheduled cron job.

Input parameters:

- `id` (string, required): The cron job ID to delete.

### `cron_list` (~14 tokens)

List all scheduled cron jobs.

### `diff_files` (~42 tokens)

Generate a unified diff between two files.

Input parameters:

- `file1` (string, required): Path to the first file.
- `file2` (string, required): Path to the second file.

### `edit_file` (~82 tokens)

Apply a text patch to a file (simple find and replace).

Input parameters:

- `path` (string, required): Absolute path to the file to edit.
- `replace_all` (boolean): If true, replaces all occurrences instead of just the first one.
- `replacement` (string, required): The new text to insert instead.
- `target` (string, required): The exact text block to be replaced.

### `enter_worktree` (~48 tokens)

Create and enter an isolated virtual worktree for independent development.

Input parameters:

- `branch` (string): Branch name (default: worktree/<name>).
- `name` (string, required): Worktree name.

### `exit_worktree` (~21 tokens)

Exit the active worktree and restore the original working directory.

### `explain_command` (~27 tokens)

Parse and explain a shell command.

Input parameters:

- `command` (string, required): The shell command to explain.

### `find_files` (~48 tokens)

Search for files by name or glob pattern.

Input parameters:

- `path` (string, required): The directory to start searching from.
- `pattern` (string, required): The filename pattern or glob (e.g., '*.ts').

### `find_symbols` (~32 tokens)

Search for symbols (functions, variables) across the workspace.

Input parameters:

- `query` (string): Query to filter symbol names.

### `get_definition` (~29 tokens)

Find the definition of a symbol.

Input parameters:

- `name` (string, required): The name of the symbol to find.

### `get_references` (~72 tokens)

Find all references to a function or variable.

Input parameters:

- `character` (number): 1-based character position
- `line` (number): 1-based line number
- `name` (string): The name of the symbol to find
- `path` (string): Path to the file where the symbol is referenced

### `git_audit_log` (~39 tokens)

Get the git operations audit log, optionally filtered to destructive operations only.

Input parameters:

- `destructiveOnly` (boolean): If true, return only destructive operations.

### `git_track` (~43 tokens)

Record and classify a git operation. Returns classification (safe/mutating/destructive) and audit entry.

Input parameters:

- `command` (string, required): The git command to classify and record.

### `glob_files` (~96 tokens)

Fast glob pattern matching over the filesystem. Returns matching file paths sorted by name or mtime.

Input parameters:

- `limit` (number): Max results (default: 1000).
- `path` (string): Root directory (default: cwd).
- `pattern` (string, required): Glob pattern (e.g., "**/*.ts", "src/**/*.{ts,tsx}").
- `sort` (string): "alpha" (default) or "mtime".

### `grep_search` (~47 tokens)

Search for a text pattern across multiple files.

Input parameters:

- `path` (string, required): Absolute path to the directory to search in.
- `query` (string, required): The text or regex pattern to search for.

### `help_builtin` (~30 tokens)

Get detailed help for a shell builtin command.

Input parameters:

- `command` (string, required): The name of the builtin command.

### `hover_info` (~53 tokens)

Get information about a symbol at a specific position.

Input parameters:

- `character` (number, required): 1-based character position
- `line` (number, required): 1-based line number
- `path` (string, required): Path to the file

### `index_workspace` (~37 tokens)

Trigger a full scan and indexing of all supported files in the workspace.

Input parameters:

- `path` (string): Root directory to scan. Defaults to /.

### `list_dir` (~28 tokens)

List contents of a directory.

Input parameters:

- `path` (string, required): Absolute path to the directory to list.

### `list_mcp_tools` (~19 tokens)

List all tools available via connected MCP servers.

### `list_todos` (~14 tokens)

List all todo items.

### `plan_enter` (~19 tokens)

Enter plan mode to design an approach before making changes.

### `plan_exit` (~17 tokens)

Exit plan mode and return to execution mode.

### `query_json` (~59 tokens)

Run a jq query against a JSON file or string.

Input parameters:

- `json` (string): Optional JSON string to query directly.
- `path` (string): Optional path to a JSON file to query.
- `query` (string, required): The jq filter/query string.

### `read_file` (~33 tokens)

Read the contents of a file from the virtual filesystem.

Input parameters:

- `path` (string, required): Absolute path to the file to read.

### `run_command` (~28 tokens)

Execute a shell command in the sandbox.

Input parameters:

- `command` (string, required): The shell command to execute.

### `run_js` (~37 tokens)

Execute JavaScript code in the sandbox. For persistent state, use run_js_session.

Input parameters:

- `code` (string, required): The JS code to execute.

### `run_js_session` (~62 tokens)

Execute JavaScript code in a persistent session (stateful REPL). Maintains variables and modules between calls.

Input parameters:

- `code` (string, required): The JS code to execute.
- `sessionId` (string, required): Session identifier (e.g., 'main', 'test').

### `run_python` (~36 tokens)

Execute Python code in the sandbox. For persistent state, use run_python_session.

Input parameters:

- `code` (string, required): The Python code to execute.

### `run_python_session` (~59 tokens)

Execute Python code in a persistent session (stateful REPL). Maintains variables and imports between calls.

Input parameters:

- `code` (string, required): The Python code to execute.
- `sessionId` (string, required): Session identifier (e.g., 'data-analysis').

### `search_tools` (~66 tokens)

Search for available tools by keyword, or select by exact name with 'select:Name1,Name2'.

Input parameters:

- `limit` (number): Max results (default: 10).
- `query` (string, required): Keyword query or "select:Name1,Name2" for exact lookup.

### `send_message` (~46 tokens)

Send a message from one agent to another.

Input parameters:

- `content` (string, required): Message content.
- `from` (string, required): Sender agent ID.
- `to` (string, required): Recipient agent ID.

### `sync_mcp_tools` (~22 tokens)

Synchronize and register all MCP tools into the central toolbox.

### `task_create` (~81 tokens)

Create a new tracked task with subject, description, owner, and progress text.

Input parameters:

- `activeForm` (string): Spinner text when in_progress (e.g., "Running tests").
- `description` (string, required): What needs to be done.
- `owner` (string): Agent ID that owns this task.
- `subject` (string, required): Brief title for the task.

### `task_get` (~29 tokens)

Get full details of a specific task by ID.

Input parameters:

- `taskId` (string, required): The task ID.

### `task_list` (~42 tokens)

List all tracked tasks, optionally filtered by status or owner.

Input parameters:

- `owner` (string): Filter by owner agent ID.
- `status` (string): Filter by status.

### `task_stop` (~29 tokens)

Stop (fail) a running task.

Input parameters:

- `taskId` (string, required): The task ID to stop.

### `task_update` (~114 tokens)

Update a task's status, subject, description, owner, or dependencies.

Input parameters:

- `addBlockedBy` (string): Task IDs that block this task.
- `addBlocks` (string): Task IDs that this task blocks.
- `description` (string): New description.
- `owner` (string): New owner agent ID.
- `status` (string): New status: pending, in_progress, completed, failed, blocked.
- `subject` (string): New subject.
- `taskId` (string, required): The task ID to update.

### `team_create` (~37 tokens)

Create a new agent team for coordinated multi-agent work.

Input parameters:

- `description` (string): Team purpose.
- `name` (string, required): Team name.

### `team_delete` (~24 tokens)

Delete an agent team.

Input parameters:

- `name` (string, required): Team name or ID.

### `update_todo` (~40 tokens)

Update the status of a todo item.

Input parameters:

- `id` (string, required): The ID of the todo to update.
- `status` (string, required): New status.

### `write_file` (~46 tokens)

Create or overwrite a file in the virtual filesystem.

Input parameters:

- `content` (string, required): The content to write to the file.
- `path` (string, required): Absolute path to the file to write.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server#diagnostics

## Score history

- 2026-08-03: 57
- 2026-08-02: 57
- 2026-08-01: 20
- 2026-07-31: 19
- 2026-07-30: 6
- 2026-07-28: 44
- 2026-07-27: 44

## Links

- npm package: https://www.npmjs.com/package/@ag-bash/mcp-server
- Socket report: https://socket.dev/npm/package/@ag-bash/mcp-server
- Repository: https://github.com/sairam0424/ag-bash
- Changelog RSS feed: https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server/changelog.json
- HTML version of this page: https://verifymcp.io/servers/sairam0424-ag-bash/ag-bash-mcp-server