Shell Escape

Run a shell command inline in praisonai code without spending a model turn

Next

Type !cmd in an interactive session to run a shell command without spending a model turn. !!cmd also attaches the output as context for your next message.

from praisonaiagents import Agent

# The shell escape lives in the `praisonai code` interactive REPL/TUI,
# not on the Agent class. Nothing to configure on the agent itself —
# just launch a session and enable the gate:
agent = Agent(
    name="Coder",
    instructions="You are a coding assistant.",
)

# Then from your terminal:
#   $ export PRAISONAI_ALLOW_SHELL=true
#   $ praisonai code
#   > !git status                # run inline, no model turn
#   > !!git diff                 # attach output as context for the next prompt
#   > summarise the change       # this turn sees the diff

Quick Start

1. Enable the gate and run a command

   Shell escape is off by default. Enable it, launch a session, and run a command inline:

   export PRAISONAI_ALLOW_SHELL=true
   praisonai code

   > !git status
   On branch main
   nothing to commit, working tree clean

   The command runs immediately and prints its output — no model turn is spent.

2. Attach output as context

   Prefix with !! to also stash the output as context for your next message:

   > !!git diff
   [diff prints here]
   Output attached as context for the next message.
   
   > summarise the change

   The follow-up turn sees the diff, prefixed as [shell output].

How It Works

The !cmd path never calls the model — agent.start() only fires on your next real prompt, prefixed with [shell output] if a !!cmd is pending.

!cmd vs !!cmd

Pick ! for a quick peek and !! when you want the model to read the output.

Configuration

Shell escape reuses the same gate that powers ` !cmd ` template substitution — there is no second flag to remember.

export PRAISONAI_ALLOW_SHELL=true
praisonai code

# .praisonai/config.yaml
commands:
  allow_shell: true

Safety Limits

Shell escape carries the same safety posture as ` !cmd ` template substitution.

Failure Behaviour

A non-zero exit, timeout, or output cap never raises into the REPL loop — the diagnostic is rendered inline instead. For !!cmd, the error text is still attached as context so the model can help debug it.

> !!pytest -x
[test failures print here]
Output attached as context for the next message.

> why did this fail?

The failing output is attached, so the follow-up turn can reason about it.

Pending-Context Lifecycle

!!cmd output is retained until the next model call succeeds. If that call raises, the context stays so you can retry without re-running the command.

Common Patterns

Review a staged diff with the model:

> !!git diff --staged
> review this diff

Debug a failing test:

> !!pytest -x
> why did this fail?

Quick peek with no attach:

> !ls -la

Best Practices

Related