OTerminus

Local · structured-first · safety-first

OTerminus is a local, safety-first terminal assistant that turns natural-language requests into one proposed shell action, previews it, validates it, and asks before running.

It is for developers and terminal users who want help with common Unix-like workflows without handing execution authority to an LLM or opening the door to arbitrary shell generation.

Get startedInstallSupported workflowsArchitecture overviewGitHub

What OTerminus does

OTerminus sits between your request and your shell. It recognizes direct commands, routes specific natural-language requests to supported capabilities, asks a local Ollama model to produce structured proposals when planning is needed, validates the resulting command, renders a preview, and requires explicit confirmation by default.

Local LLM planning

Natural-language planning uses Ollama locally. PyPI installation gives you the CLI; it does not install Ollama or a model.

Direct command detection

Known shell-like commands can bypass natural-language planning, but they still go through validation and policy checks.

Structured proposals first

Supported command families use typed proposal data that OTerminus renders deterministically instead of trusting raw model text.

Validation and policy gates

Risk levels, platform support, command-family rules, and policy mode decide whether a proposal is allowed, warned, or rejected.

Preview before execution

OTerminus shows the proposed command, risk, warnings, and rejections before anything runs.

Confirmation by default

Execution normally waits for explicit confirmation. Experimental proposals and higher-risk operations require stronger confirmation.

Config, doctor, and evals

Use local configuration, oterminus doctor, generated references, and packaged evals to inspect and verify behavior.

Install

For normal CLI use, prefer pipx so OTerminus and its dependencies stay isolated from your system Python environment.

pipx install oterminus
oterminus --version
oterminus doctor
oterminus

If pipx is not available, install from PyPI with pip instead:

python -m pip install oterminus

Requirements include Python 3.13+, a macOS or Unix-like POSIX terminal environment, and Ollama for natural-language planning. Direct commands and some deterministic utility paths may be usable without a live model, but first-time natural-language usage depends on Ollama being installed, running, and having a local model available.

Get started

1. Install OTerminus with pipx install oterminus.
2. Run oterminus doctor to check the package, platform, config paths, command registry, and Ollama readiness.
3. Make sure Ollama is installed and running before relying on natural-language planning.
4. Start the interactive REPL with oterminus.
5. Try direct commands or specific, safe natural-language requests.
6. Use --dry-run and --explain before trusting a new command pattern.

oterminus "show disk usage for this folder"
oterminus --dry-run "find large files here"
oterminus --explain "find processes matching python"
oterminus "ls -lah"

The first bare interactive launch may offer a configuration wizard for local safety and privacy preferences. One-shot commands, --dry-run, --explain, doctor, version, completion, and config commands do not trigger onboarding.

How the safety model works

OTerminus treats LLM output as a proposal, not execution authority.

• Direct commands are detected before planning, but still go through validation and policy.
• Natural-language requests go through the local LLM planner only after routing and ambiguity checks.
• Ambiguous natural-language requests are blocked before planning or execution.
• Structured proposals are validated and rendered deterministically from typed fields.
• Unsupported commands, unsafe flag combinations, platform-incompatible commands, and blocked capabilities are rejected.
• Experimental proposals require stronger confirmation and do not qualify for safe auto-execute.
• LLM-planned commands cannot bypass validation, policy gates, preview, or confirmation.

See Request lifecycle, Routing and planning, and Validation and policy for the full flow.

Supported workflows

OTerminus is capability-first, not a fully general shell copilot. Current documentation and the command registry cover these workflow categories:

• filesystem inspection and constrained filesystem mutation;
• text inspection and search;
• process inspection;
• read-only Git inspection;
• constrained network diagnostics;
• archive inspection, creation, and extraction with explicit paths and guarded rules;
• system and manual-page inspection;
• curated project-health operations such as tests, lint, format checks, docs builds, and evals.

Review the Supported workflows guide and generated Command families reference before assuming a command family or flag set is supported.

Where to go next

What is OTerminus?Product principles and typical journey.User guideInstall, doctor, REPL, one-shot, dry-run, and explain.Supported workflowsCapabilities and examples that are currently in scope.Configuration referenceEnvironment variables, config file behavior, policy, audit, and history settings.Request lifecycleDirect detection, ambiguity handling, planning, validation, preview, and execution.Routing and planningHow natural-language requests become structured proposals.Validation and policyRisk, rejections, warnings, and policy boundaries.EvalsHow behavior is checked with deterministic fixtures.GitHub repositorySource code, issues, changelog, and contribution history.

Build and preview docs locally

poetry install --with dev
cd website
npm ci
npm run start
npm run build
npm run typecheck

See the contributor workflow for the complete local lint, format, test, and docs checklist.