Reference

ctx_shell

Input contract and parameters for ctx_shell.

Status by featureReviewed September 2026

MCP tool · Read, search & shell

Call this tool through your MCP client. Its availability depends on your active configuration and profile.

This registry contract is separate from the SDK. For terminal commands, use the CLI reference.

Example call

JSON for an MCP client. Replace example paths and queries with your own project values.

{
  "name": "ctx_shell",
  "arguments": {
    "command": "git status --short",
    "cwd": "."
  }
}

Parameters

Generated from the registered input schema. “Required” reflects the schema; individual actions can impose additional requirements.

background_actionstring

Inspect or cancel a background ctx_shell job; terminal status may include archiveId. Evicted/expired jobs return a structured lookup error.

Accepted: statuscancel

commandstring

Shell command

cwdstring

Working dir (persists across calls)

envobject

Extra env vars

inlineboolean

Return verbatim output inline up to archive.inline_max_bytes; larger output uses the archive/firewall

job_idstring

Job id returned by run_in_background.

rawboolean

Skip compression (verbatim)

run_in_backgroundboolean

Detach immediately and return a job id. The command keeps timeout_ms; poll or cancel with background_action and job_id.

timeout_msinteger

Job lifetime in ms (max 3600000) — NOT the inline wait. A command still running at the ~110s foreground cap detaches to a pollable shell_* job and keeps running up to timeout_ms. Overridden by LEAN_CTX_SHELL_TIMEOUT_MS.

Exact JSON schema

Inspect the complete input schema

{
  "properties": {
    "background_action": {
      "description": "Inspect or cancel a background ctx_shell job; terminal status may include archiveId. Evicted/expired jobs return a structured lookup error.",
      "enum": [
        "status",
        "cancel"
      ],
      "type": "string"
    },
    "command": {
      "description": "Shell command",
      "type": "string"
    },
    "cwd": {
      "description": "Working dir (persists across calls)",
      "type": "string"
    },
    "env": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Extra env vars",
      "type": "object"
    },
    "inline": {
      "description": "Return verbatim output inline up to archive.inline_max_bytes; larger output uses the archive/firewall",
      "type": "boolean"
    },
    "job_id": {
      "description": "Job id returned by run_in_background.",
      "type": "string"
    },
    "raw": {
      "description": "Skip compression (verbatim)",
      "type": "boolean"
    },
    "run_in_background": {
      "description": "Detach immediately and return a job id. The command keeps timeout_ms; poll or cancel with background_action and job_id.",
      "type": "boolean"
    },
    "timeout_ms": {
      "description": "Job lifetime in ms (max 3600000) — NOT the inline wait. A command still running at the ~110s foreground cap detaches to a pollable shell_* job and keeps running up to timeout_ms. Overridden by LEAN_CTX_SHELL_TIMEOUT_MS.",
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}

Runtime description

The following is the tool's own agent-facing description, reproduced from the reviewed registry. It can contain implementation terminology; it does not expand the public stability commitment.

Read the agent-facing description

WORKFLOW: preferred — auto-compresses output (build/test/log).
raw=true for verbatim output; inline=true for moderately-sized verbatim output.
[exit:N] on errors (lossless).
POLICY: allowlisted read-only path.
A [BLOCKED] command is permanent; ctx_execute shares the same allowlist — fix with `lean-ctx allow <cmd>`.
ANTIPATTERN: multi-line scripts, sh/bash script.sh, $var-as-command → ctx_execute (when exposed).

Sources & versions3 references Reviewed 18 Sept 2026

mcp_manifest.rsrust/src/core/mcp_manifest.rsReviewed checkout
registry.rsrust/src/server/registry.rsReviewed checkout
dynamic_tools.rsrust/src/server/dynamic_tools.rsReviewed checkout

Core checkout: 50fbff09c9
Installed runtime: 3.10.2
SDK release: 1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility