ShellPa

A safety-conscious, cross-platform terminal assistant. Describe the outcome; review the native command; stay in control.

ShellPa translates natural-language intent into a command for the active operating system and shell. Before anything runs, ShellPa applies a deterministic local safety policy and presents the proposal for review.

User intent
    -> structured command proposal
    -> deterministic safety assessment
    -> permission decision
    -> observable execution
    -> redacted recovery when needed

Why ShellPa

• Cross-platform commands — supports PowerShell, CMD, Bash, and Zsh.
• Deterministic safety — the model proposes; ShellPa decides whether a command may execute.
• Interactive terminal UX — themes, motion settings, history, completion, activity states, and keyboard navigation.
• Workspace awareness — detects bounded project, Git, tool, and Python environment metadata without reading source contents.
• Provider choice — supports OpenRouter, OpenAI API, Gemini, Anthropic, and eligible ChatGPT subscriptions through the optional Codex provider.
• Private by design — diagnostics and recovery exclude credentials, environment values, command output, and arbitrary Git filenames.

Installation

ShellPa requires Python 3.10 or newer. For a standalone command-line application, pipx is recommended because it creates an isolated environment while making shellpa available from any terminal.

pipx install shellpa

For ChatGPT subscription access through the embedded Codex provider:

pipx install "shellpa[codex]"

The configuration wizard can also install the optional Codex provider after explicit approval. A separate Codex CLI installation is not required.

If pipx is not installed, or for platform-specific update and removal instructions, see the installation guide.

Quick start

Configure a provider:

shellpa config

Run a natural-language request:

shellpa "show the five largest files in this directory"

Preview without execution:

shellpa "show the five largest files in this directory" --dry-run

Open the interactive session:

shellpa

Inside the session, use /help to see all interactive controls.

Providers

The Codex path delegates sign-in and session storage to the official embedded Codex runtime. ShellPa does not read or store Codex credentials. Existing sessions are preserved by default, and logout requires explicit confirmation.

For API-backed providers, ShellPa stores newly configured keys in Windows Credential Locker, macOS Keychain, Linux Secret Service, or KWallet through the active operating-system credential backend. Existing plaintext user configuration is migrated only after the secure copy is verified. When secure storage is unavailable, ShellPa can use a key for the current process without silently saving another plaintext copy.

shellpa login
shellpa login --device-code
shellpa logout

Safety model

ShellPa assesses every proposed command locally:

Approved commands inherit operational environment variables needed by the shell, but ShellPa withholds provider keys, its own configuration variables, and other secret-shaped values from child processes.

Permission modes:

• Ask — review commands before execution.
• Plan — display proposals without execution.
• Trusted — automatically runs only commands proven read-only.

--force does not bypass critical-policy boundaries.

Workspace transparency

ShellPa detects only bounded workspace facts:

• workspace boundary and allowlisted project markers;
• project types and known executable availability;
• Git branch, detached/unborn state, and change counts;
• active Python environment type.

It does not read source contents, .env contents, credential files, or arbitrary Git filenames to create the provider-safe summary.

shellpa context

The context view clearly separates local-only paths from the smaller summary that may influence a provider request.

Useful commands

See the complete command reference and v0.3 migration guide.

Development

Clone the repository and create a project environment:

git clone https://github.com/AMR-M-ALSHAMEERI/ShellPa.git
cd ShellPa
python -m venv venv

Activate it:

# Windows PowerShell
.\venv\Scripts\Activate.ps1

# macOS / Linux
source venv/bin/activate

Install the development and Codex extras:

python -m pip install -e ".[dev,codex]"

Run the quality suite:

python -m pytest
python -m ruff format --check .
python -m ruff check .
python -m mypy
python -m build
python scripts/verify_package_contents.py dist

See CONTRIBUTING.md before proposing a change. Report suspected vulnerabilities through the security policy, not through a public issue.

License

ShellPa is available under the MIT License.

Release status

Version 0.3.0 is available on PyPI. It was published through the protected Trusted Publishing workflow after TestPyPI and clean-install validation.