Bash Saver

Synced from bash-saver/README.md. The repository is the source of truth.

Standalone Pi package for automatically recovering quick-failing bash tool calls.

Install

Install this package into a Pi workspace from GitHub:

pi install git:github.com/applepi-ai/bash-saver

Then start Pi in that workspace as usual. The package manifest registers ./index.ts as a Pi extension.

What it does

The extension enriches Pi’s bash tool with two modes:

• command: execute an exact command, preserving normal bash behavior.
• goal: ask a constrained bash-only sub-agent to accomplish an operational shell goal and report what it did.

When a bash command call fails within the quick-failure threshold (default 5 seconds), the extension starts a minimal inner Pi agent with only:

• bash
• store_bash_context

The inner agent receives the original command, cwd, failure output, matched stored context, and strict instructions to run only a semantically equivalent corrected command for likely invocation/environment mistakes. It is instructed to return exactly NOOP for test, check, experiment, probe, or exploratory failures when the error output contains substantive details the outside caller needs to fix; in that case the original failed bash result is left unaltered. If goal was provided alongside command, it is used only as recovery context after the command fails. If recovery succeeds, the outer bash result is rewritten as successful and includes a transparent recovery summary.

When goal is provided without command, the inner agent chooses safe commands to accomplish the goal, verifies success, and returns commands run plus key info.

Files

• requirements.md — RFC 2119 requirements with unique IDs.
• index.ts — Pi extension entry point and enriched bash tool wrapper.
• src/core-v2.mjs — dependency-light core logic used by the extension and tests.
• src/core.mjs — prior core module retained for compatibility/reference.
• test/core.test.mjs — automated unit tests.

Local development

Clone and test the standalone package:

git clone https://github.com/applepi-ai/bash-saver.git
cd bash-saver
npm test
npm run check
npm run pack:dry-run

Use the checkout directly with Pi during development:

pi -e ./index.ts

Or install the local checkout into another Pi workspace if your Pi CLI supports local package sources:

pi install ./path/to/bash-saver

Configuration

Environment variables:

• PI_ABR_QUICK_FAILURE_MS — quick-failure threshold in ms. Default: 5000.
• PI_ABR_RECOVERY_TIMEOUT_MS — inner recovery session timeout in ms. Default: 60000.
• PI_ABR_MAX_RECOVERY_COMMANDS — max inner bash commands. Default: 6.
• PI_ABR_BLOCK_DANGEROUS_COMMANDS — set to 0 to disable dangerous-command blocking. Default: enabled.
• PI_ABR_STORE_PATH — custom JSON context store path. Default: <cwd>/.pi/auto-bash-recovery-context.json.

Rich bash usage

Exact command mode:

{ "command": "npm test", "timeout": 60 }

Command plus recovery context:

{ "command": "duckdb --version", "goal": "Ensure DuckDB CLI is available" }

Goal mode:

{
  "goal": "Install duckdb",
  "constraints": ["do not use sudo"],
  "verify": "duckdb --version works"
}

Stored context

The registered store_bash_context tool supports:

• action: "list"
• action: "upsert"
• action: "delete"

Entries can match command, goal, stderr/output, and cwd regexes. Matched entries are included in the inner recovery/goal prompt and in the outer summary so stale advice is visible and editable.

Tests

npm test