ashlr

ashlr__pipe [EXPERIMENTAL]

Experimental multi-step JavaScript expression pipeline. Runs grep/read/ls/glob internally — only the final result enters the model context. 80–95% token savings vs calling tools individually. Gated by ASHLR_PIPE_ENABLE=1.

ashlr__pipe is an experimental tool that lets the model run a multi-step JavaScript expression calling grep, read, ls, and glob internally. Intermediate results never enter the model's context — only the expression's return value does. This yields 80–95% token savings vs calling the same tools individually.

Status: experimental and not registered by default. Set ASHLR_PIPE_ENABLE=1 in the MCP server process environment before starting it to register the tool. It is excluded from the default tool count.

Why it exists

A common pattern in agentic code sessions is a chain like:

  1. grep for files matching a pattern → 40 results
  2. read each candidate → 40 × 3KB = 120KB of context
  3. Filter to 2 relevant files → 118KB was wasted

ashlr__pipe collapses this into one call. The expression body runs the chain locally; only the final filtered output enters the context window.

Enable

ASHLR_PIPE_ENABLE=1 bun run scripts/mcp-entrypoint.ts servers/_router.ts

Or export it before starting the MCP server from your shell:

export ASHLR_PIPE_ENABLE=1

For an MCP client that starts the server itself, set the variable in that server's environment configuration and restart the server.

To also allow bash calls inside expressions (off by default):

export ASHLR_PIPE_ALLOW_BASH=1

Usage

{
  "tool": "ashlr__pipe",
  "arguments": {
    "expr": "const output = await ctx.grep({ pattern: 'TODO', cwd: '/path/to/project' }); return output.split('\\n').filter(line => line.includes('auth')).slice(0, 5).join('\\n');"
  }
}

Replace /path/to/project with a directory inside an allowed root. The filter selects lines containing auth, including any status lines with that text.

Parameters

ParameterTypeRequiredDescription
exprstringyesJavaScript expression body (max 2000 chars). Must return a string or object.
cwdstringnoDirectory to validate against allowed roots; pass cwd to a context method separately to select its working directory.
timeout_msnumbernoExecution timeout in ms (default: 10000, hard max: 30000).
max_output_bytesnumbernoTruncate output to this many bytes (default: 4096).

Available functions inside expr

By default, only read-only context tools are available:

FunctionMaps to
ctx.grep(args)ashlr__grep
ctx.read(args)ashlr__read
ctx.ls(args)ashlr__ls
ctx.glob(args)ashlr__glob
ctx.bash(args)ashlr__bash — only when ASHLR_PIPE_ALLOW_BASH=1

Each method accepts an argument object matching the wrapped tool and returns its text output as a string, which may include status messages. Methods are async and must be awaited. The expression receives ctx and runs in strict mode; the deny-list is a best-effort guardrail, not a sandbox. The pipe serializes the return value as JSON.

Deny-list

The following are blocked regardless of flags:

  • File writes (write, edit, multi_edit)
  • Destructive shell commands (even with ASHLR_PIPE_ALLOW_BASH=1, commands matching the deny-list in pipe-server.ts are rejected)
  • Network calls outside the listed functions
  • process.exit, require, dynamic import

Token accounting

ashlr__pipe suppresses per-call accounting for intermediate tool invocations and records a single entry:

rawBytes    = sum of all intermediate tool result sizes
compactBytes = final output size
saved       = rawBytes − compactBytes

This prevents double-counting in /ashlr-savings.

Example — filter TODO output for auth

// expr:
const output = await ctx.grep({ pattern: 'TODO', cwd: '.', bypassSummary: true });
const lines = output.split('\n').filter(line => line.includes('auth'));
return lines.slice(0, 20).join('\n') || 'No auth lines found';

This returns up to 20 lines containing auth from the grep tool's text. If none do, it returns No auth lines found. The filter operates on text, so a status message containing auth can also be included; intermediate output may be capped.

Limitations

  • Experimental: API may change before stable release.
  • expr is limited to 2000 characters.
  • expr is an async function body, so it can use await directly.
  • Errors inside expr surface as isError: true responses with the JS error message.
  • bash inside pipe is a separate opt-in flag (ASHLR_PIPE_ALLOW_BASH=1) to prevent accidental shell execution.

On this page