User Guide

Public install / normal user flow

For released versions, OTerminus is published to PyPI as the oterminus package. The package installs two console scripts: oterminus for the assistant CLI and oterminus-evals for the packaged evaluation smoke check.

For normal CLI use, prefer pipx because it installs OTerminus in an isolated environment instead of mixing OTerminus and its dependencies into your system Python environment:

pipx install oterminus
oterminus --version
oterminus doctor
oterminus

Run oterminus --version after installation to confirm the installed package version. Then run oterminus doctor; it is the recommended post-install diagnostic for checking the detected package version, Python runtime, executable path, pipx or virtualenv context, platform, configuration paths, selected model state, Ollama CLI/service readiness, local model availability, audit/history paths, registry metadata, eval fixtures, and relevant developer-tool status.

Supported environments

OTerminus currently targets macOS and Unix-like POSIX terminal environments. Linux-like environments may work when Python 3.13+, Ollama, and the required shell commands are installed. Native Windows Command Prompt and PowerShell are not first-class supported targets yet; Windows users should run OTerminus inside WSL when they need the Unix-like shell behavior expected by the current command registry.

Command packs and individual command specs can be platform-aware. The macOS desktop pack, including open, is available only on supported macOS (darwin) platforms. Unsupported platform commands are hidden from autocomplete, planner context, and discovery output where practical, but the validator remains the authoritative boundary and rejects platform-unsupported commands before execution.

After doctor reports a usable setup, start the interactive app or run one-shot requests:

oterminus
oterminus "show disk usage for this folder"
oterminus "find Python files up to three levels deep"
oterminus "find files larger than 100 MB"
oterminus "show the man page for grep"
oterminus --dry-run "copy notes.txt to backup/notes.txt"
oterminus --explain "find processes matching python"

Read-only file finding

Filesystem find requests use a structured, read-only subset. OTerminus can combine a single starting path with supported predicates for literal name patterns, file-vs-directory type, bounded max depth, files modified within a number of days (-mtime -N), and files larger than an exact byte threshold (-size +Nc). For example, “find large log files modified in the last two days” renders a deterministic argv shape like find . -type f -name '*.log' -mtime -2 -size +104857600c when “large” is planned as 100 MiB. Allowed-root restrictions apply to the starting path only; pattern, type, depth, day count, and byte count are not treated as path operands. OTerminus rejects arbitrary find expressions, deletion or exec actions, output files, Boolean operators, permission/owner filters, and symlink-following flags.

Upgrade and uninstall

Update an existing isolated pipx install with:

pipx upgrade oterminus
oterminus --version

The version check is a lightweight package diagnostic and does not require Ollama.

Remove the isolated CLI with:

pipx uninstall oterminus

pip fallback

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

python -m pip install oterminus

pipx remains preferred for command-line use because it keeps the OTerminus application environment separate from your system Python and from other Python projects.

Development install

Use Poetry only when you are developing OTerminus from a source checkout:

poetry install
poetry run oterminus

Development commands can use the same CLI forms with a poetry run prefix, for example poetry run oterminus --version, poetry run oterminus doctor, or poetry run oterminus --dry-run "ls". Local wheel/package validation with poetry run python scripts/validate_package_install.py is a contributor and release-maintainer workflow, not the primary user install path. See the contributor workflow and release guide for package validation and publishing details.

Ollama requirement for natural-language planning

PyPI installation gives you the OTerminus CLI; it does not install Ollama, start the Ollama service, or download a local model. Ollama is still required for natural-language planning. Direct commands and retained deterministic_shortcut utility requests may skip model planning, but first-run natural-language usage depends on Ollama being ready.

Startup and doctor readiness checks include:

1. ollama is available on PATH.
2. Ollama service is reachable (ollama list).
3. At least one model is installed.

Check only the installed package version with:

oterminus --version
oterminus version

Both version forms print the same concise package version, exit successfully, and do not start the REPL, run doctor/setup checks, read or write request history, or require Ollama. Inside the REPL, version prints the same diagnostic output without going through natural-language planning.

Run environment diagnostics explicitly with:

oterminus doctor

doctor prints the readiness report and exits. It does not start the REPL, execute a request, invoke the LLM planner, or send model schema probes. Unlike --version, it checks environment readiness such as Ollama availability, reports the installed-model count, and shows the selected model, its configuration source, and whether it is installed. It points to oterminus models test for the separate, active schema-compliance diagnostic.

For a focused view of local models and the current selection, run either equivalent form:

oterminus models
oterminus models list

The list report shows Ollama CLI and service status, installed model names, the selected OTerminus model and its configuration source, and whether that selection is installed. The selected model is marked with * in the installed-model list. Change the selection with oterminus config set model <model-name>.

models list reporting is diagnostic-only: it does not start the REPL, invoke a model or planner, propose or execute a shell command, run onboarding, or write request audit/history entries. If the Ollama CLI is missing, the service cannot be reached, no models are installed, or the selected model does not match an installed model, the report prints a next step. OTerminus never pulls a model automatically; install one explicitly with ollama pull <model>.

Test whether the configured model follows OTerminus's strict planner proposal contract with:

oterminus models test
oterminus models test gemma4:latest

The second form tests that installed model for this invocation only and does not change user configuration. The test sends three fixed, read-only planning prompts to the local model and calls the normal planner schema and structured-argument validation path. It never renders, dry-runs, asks to confirm, or executes any proposed command, and it does not write normal request audit or history events.

This is a proposal-compliance diagnostic, not a general-intelligence or benchmark-quality test. A first-pass success is the strongest result. A pass after the planner's single repair attempt remains usable, but is shown separately because frequent repairs indicate lower reliability. A schema or simple command-family mismatch fails the test; try another installed model or run oterminus doctor when readiness prevents the test from starting.

If no model is configured yet, OTerminus shows installed models and prompts you to choose one. The selection is saved in ~/.oterminus/config.json (or OTERMINUS_CONFIG_PATH if set).

Model returned invalid proposal JSON

Some smaller or faster local models may produce malformed JSON or valid JSON with invalid proposal values, such as putting a command name in action_type or mode. OTerminus requests a JSON Schema-constrained response from Ollama, uses deterministic low-temperature planning, retries one repair attempt, and rejects the output if it still does not match the proposal schema.

Schema-constrained output improves formatting reliability, but it does not guarantee semantic correctness. OTerminus still validates and previews every proposal before execution, and invalid model output is never executed. If a model repeatedly fails schema validation:

• run oterminus models test to check the selected model with fixed read-only probes
• check the selected model with oterminus config get model
• try another installed model with oterminus config set model <model-name>
• run oterminus doctor to inspect local Ollama/model readiness
• use a direct command when you already know the command you want

On the first bare interactive launch (oterminus) when the persistent config file does not exist and stdin is a TTY, OTerminus offers a first-time configuration wizard. The wizard does not run for one-shot requests, --dry-run, --explain, doctor, version, completion, models, config commands, or non-interactive stdin. Declining onboarding saves safe defaults with onboarding_completed: true, explains that you can rerun it with oterminus config init, and then continues into the REPL. If that save fails, OTerminus continues with in-memory safe defaults and may ask again next time because the completion state could not be persisted.

The wizard asks only high-value first-run questions:

• command profile, default safe
• safe auto-execute, default disabled
• audit logging, default enabled
• audit redaction, default enabled
• persistent history, default disabled
• persistent-history redaction, default enabled
• local Ollama failure explanations, default disabled
• optional Ollama model selection when installed models are discoverable

Ollama is optional during configuration. If the CLI is missing, the service is unavailable, or no models are installed, onboarding saves the non-model preferences and leaves model setup for later. Direct commands and deterministic shortcuts remain usable without a configured model. Advanced settings such as numeric limits, paths, allowed roots, policy mode, and explicit disabled packs stay editable in the JSON config file.

The user config file is validated JSON with schema_version: 1. It can persist local preferences such as the selected model, command profile, disabled command packs, policy mode, allowed roots, audit/history paths, output limits, terminal color mode, and reserved onboarding state. Existing legacy files with only model and optional audit_log_path still work and are treated as already onboarded in memory. Invalid config JSON or invalid field values stop startup with a concise configuration error instead of being ignored. Environment variables and current-directory .env values remain available as overrides, with precedence: exported environment, .env, user config, then built-in defaults. OTERMINUS_ALLOW_DANGEROUS is environment/.env only and is not accepted in the persistent config. The config file is not secret storage.

Terminal color policy is controlled by OTERMINUS_COLOR or the persisted color_mode field: auto enables semantic styling only for capable TTY output, always also allows redirected output, and never disables it.

export OTERMINUS_COLOR=auto
export OTERMINUS_COLOR=always
export OTERMINUS_COLOR=never
NO_COLOR=1 oterminus

Colors are semantic and supplementary. Preview labels such as Risk level, Warnings, Rejections, and Confirmation remain visible without color, as do doctor status labels such as PASS, WARN, and FAIL. NO_COLOR disables ANSI styling at render time even when the resolved mode is always; auto mode disables color when output is redirected. Command stdout/stderr is never recolored, shell completion and version output remain plain, and audit/history files do not contain ANSI styling.

Manage this file with the dedicated config namespace:

oterminus config
oterminus config path
oterminus config show
oterminus config get color_mode
oterminus config set color_mode never
oterminus config init
oterminus config init --defaults
oterminus config init --defaults --force
oterminus config validate
oterminus config edit

These commands are local configuration tools. They do not require Ollama, do not start the REPL, and do not enter request routing, planning, validation, confirmation, execution, audit writing, or history writing. The management interface is oterminus config rather than oterminus --config so that a future global --config <path> option can still mean "run with this alternate config file."

config path prints only the active path and does not create the file. config show displays effective values and sources without dumping unrelated environment values. Bare config init runs the interactive onboarding wizard when stdin is a TTY. In non-interactive use, run config init --defaults to create safe defaults without prompting; add --force to replace an existing valid config with those defaults. Invalid existing files are preserved so you can repair or move them. config validate checks only the persistent file and suggests config init when it is missing. config edit creates defaults first if needed, then launches $VISUAL or $EDITOR with the config path appended; if no editor is configured, it prints the path and manual-edit guidance. Editor commands are parsed as argv, not through a shell.

Path handling

OTerminus executes commands as argv, not through a shell. For local path operands, structured rendering intentionally supports only current-user home shorthand: ~ and ~/....

In natural-language planning, common folders such as Downloads, Desktop, Documents, Pictures, Movies, and Music are interpreted as current-user folders where appropriate, for example ~/Downloads. OTerminus does not expand $HOME, ${HOME}, globs, or command substitution, and it does not guess arbitrary system, project, application, or hidden directories.

Use config get <key> to print a single effective value, such as color_mode=auto or auto_execute_safe=false. It uses normal precedence: exported environment, current-directory .env, user config, then default. Use config set <key> <value> to persist one safe setting in the user config only. Use config reset <key> to remove one persisted safe setting so the effective value falls back through environment, .env, then default. These commands never edit .env, exported environment variables, or shell startup files, so an environment or .env value may continue to control the effective value.

config get, config set, and config reset support model, command_profile, auto_execute_safe, audit_enabled, audit_redact, history_enabled, history_redact, explain_failures, color_mode, timeout_seconds, and max_output_chars. Boolean values accept true, false, 1, 0, yes, no, on, and off. color_mode accepts auto, always, or never. command_profile accepts beginner, safe, developer, or power. Positive integer settings must be whole numbers greater than zero. Use none or null to clear a persisted model. config reset --all-safe resets exactly the same safe key set and preserves paths, allowed roots, disabled command packs, policy mode, history limits, failure explanation limits, schema version, and onboarding state.

Unsupported fields include dangerous execution, paths, lists, schema state, onboarding state, and advanced policy fields. In particular, allow_dangerous and policy.allow_dangerous cannot be persisted; dangerous execution remains an environment-only opt-in through OTERMINUS_ALLOW_DANGEROUS.

Doctor troubleshooting

Run oterminus doctor after a PyPI or pipx install and after changing Ollama, config, audit, or history settings. Doctor is diagnostics-only: it reports readiness and suggested next steps, but it does not install Ollama, start services, download models, edit config, or write audit/history records.

The report groups checks by package/runtime, platform, Ollama, model/config, local files, optional features, and developer-only checks:

• package import and oterminus version mean the installed OTerminus package can be imported and package metadata is visible. A source checkout may warn that package metadata is unavailable and a local fallback version is being used.
• python runtime shows the Python version and executable path. Unsupported Python is a critical failure; install Python 3.13 or newer, then reinstall OTerminus in that environment.
• environment and install context identify virtualenv and likely pipx installs when practical. Detection is best-effort; unknown context is a hint, not proof of a broken install.
• ollama CLI missing means the ollama executable is not on PATH. Install Ollama, then rerun doctor.
• ollama service failing means the CLI exists but ollama list cannot reach the local service. Start Ollama, for example with ollama serve, then rerun doctor.
• local ollama models failing means the service is reachable but no local models are installed. Pull a model, for example ollama pull gemma4.
• configured model shows the selected value and its configuration source, warns when no model has been selected, and fails when the selection is not installed. Use oterminus models to inspect local choices and oterminus config set model <name> to select one. Installation is not a claim of schema reliability: doctor never sends probes; run oterminus models test for that active check.
• config path, audit log path, and history path show whether OTerminus can read or create the relevant local directories. Audit logging is enabled by default; persistent history is disabled by default, so a disabled history check is normally OK.
• eval fixtures and dev tools are developer-only checks. They may warn when doctor is run from a source checkout, but they are not expected for normal PyPI or pipx installs.

Direct commands may still work without a configured model because they can skip LLM planning after local detection. Natural-language planning needs Ollama installed, running, at least one local model available, and a selected configured model.

Shell completion strategy

OTerminus separates two different completion surfaces:

1. Shell-level completion happens in your outer shell before OTerminus starts. OTerminus can print generated completion scripts for zsh, bash, and fish with oterminus completion zsh|bash|fish. The command only prints the script to stdout. Installing, upgrading, or running OTerminus with pipx does not edit .zshrc, .bashrc, config.fish, or any other shell startup file automatically.
2. REPL Tab autocomplete happens inside interactive OTerminus after you run oterminus. This is supported through prompt_toolkit and is documented in the Autocomplete section. It completes built-ins, supported commands/capabilities, and local filesystem paths.

Current shell-level status:

Shell	OTerminus shell-level completion status
zsh	oterminus completion zsh prints a static completion script.
bash	oterminus completion bash prints a static completion script.
fish	oterminus completion fish prints a static completion script.

See Shell completion for shell-specific manual setup and removal instructions. Shell-level completion remains opt-in manual configuration chosen by the user, not an automatic install-time or runtime mutation.

Model selection behavior

• First interactive onboarding: optionally choose from discovered local models.
• Later runs: saved model is reused.
• If saved model is missing: OTerminus warns and asks for a new selection.
• If onboarding skipped model selection or Ollama was unavailable, model setup can happen later when a model-planned request needs it, or by rerunning oterminus config init.

Running OTerminus

OTerminus has three user-facing CLI entry points:

• REPL mode: oterminus
• one-shot request mode: oterminus "show disk usage for this folder"
• diagnostics mode: oterminus doctor

Use the same commands with a poetry run prefix when running from a source checkout.

REPL mode

oterminus

REPL mode starts an interactive session. Requests entered in the REPL follow the same lifecycle as one-shot requests: direct-command detection, natural-language ambiguity handling when applicable, planning for specific natural-language requests, validation, preview, confirmation, execution, and audit logging.

If a non-direct REPL request is ambiguous, OTerminus gives you one chance to replace it with a complete, specific request before anything is planned. It shows the ambiguity reason, safe inspection ideas, one clarifying question, and cancel guidance. Press Enter, type cancel, interrupt the prompt, or provide another ambiguous request to return to the main REPL prompt without planning or execution. A specific replacement is submitted through the normal lifecycle; dry-run and explain prefixes from the original REPL line are preserved, and clarified requests never use safe auto-execute. The original ambiguous line and the final replacement appear as separate linked history entries when clarification succeeds; cancelled or unresolved clarification records only the original source entry. For example, clean this folder may prompt for a replacement, and answering list large files in ~/Downloads records the clarification outcome before previewing the list large files request normally. Rerunning the original entry resubmits the original ambiguous text rather than replaying that old answer.

On a first interactive launch with no config file, onboarding may run before the REPL starts. One-shot requests are never blocked by onboarding: direct commands still load built-in or existing effective config, detect locally, validate, preview, follow confirmation policy, and execute if confirmed without requiring Ollama.

REPL built-ins include (all local, deterministic, and backed by command-registry metadata; they do not call Ollama):

• help, help capabilities, help <capability_id>, help <command_family>
• capabilities, commands, examples
• history, history <n>, explain <history_id>, rerun <history_id>
• last failure, explain last failure, suggest fix for last failure, recover last failure
• dry-run <request>, explain <request>
• audit status, audit tail [n], audit clear, exit, quit

last failure shows the most recent failed command recorded in the current REPL session, including the history id, original input, rendered command, exit code, status, and recorded stderr/stdout snippets when available. explain last failure shows any stored failure explanation, or explicitly requests the configured local failure explainer if no explanation has been stored yet. Both commands are inspection-only: they do not plan, validate, confirm, execute shell commands, or run any suggested next action. Plain last failure does not invoke the LLM.

suggest fix for last failure and recover last failure ask OTerminus to propose one conservative next step for the most recent failed command. Recovery suggestions prefer read-only diagnostics such as checking a path, listing a parent directory, or inspecting Git status. A dry-run suggestion is sent back through the normal request lifecycle, so it is detected or planned, validated, previewed, policy-checked, and recorded like any other request. A copy-only suggestion is displayed only and is not planned, validated, audited, or executed unless you copy it into the prompt yourself. Recovery suggestions never use safe auto-execute and never run automatically; mutating fixes require explicit user intent and the normal confirmation and policy flow.

One-shot mode

oterminus "find all .py files"

One-shot mode accepts the remaining command-line words as a single request. It detects direct commands first, checks non-direct natural-language requests for ambiguity, plans specific natural-language requests, validates accepted proposals, renders a preview, and asks for confirmation before execution.

Doctor mode

oterminus doctor

Doctor mode is diagnostic-only. It prints readiness and integrity checks, including configuration, selected model, Python runtime, install context, Ollama CLI/service/model availability, audit/history paths, registry, eval fixture, and developer-tool status where applicable. It exits with the doctor report status and does not start the REPL, execute a request, or invoke the Ollama planner. In color-enabled terminals, status labels and section headings use semantic colors while the literal PASS, WARN, and FAIL labels remain visible.

Direct commands

You can enter supported command families directly (for example ls -la, ls -ltrh, ls --color=auto, cd src, pwd, or ping -c 4 example.com).

Direct commands skip LLM planning when local direct-command detection succeeds. They still pass through validator + policy gates and show a preview before any execution. In normal execute mode, they require confirmation by default.

ls accepts a broader guarded set of display flags when typed directly. Natural-language requests still use the strict typed ls fields, so OTerminus does not invent arbitrary ls flags from prose.

Network direct commands are detected only for exact constrained forms: ping -c <count> <host>, curl -I <http-or-https-url>, dig <domain>, and nslookup <domain>. Broad network commands cannot bypass validation through the direct-command path.

If you explicitly enable safe auto-execute, some warning-free local read-only direct commands can skip the confirmation prompt after preview:

export OTERMINUS_AUTO_EXECUTE_SAFE=true

You can also put the same key in a .env file in the directory where you start OTerminus:

OTERMINUS_AUTO_EXECUTE_SAFE=true

Exported shell values override .env values.

This is not a general yes mode. Network commands, write or dangerous commands, experimental commands, commands with warnings, project-health commands, archive extraction/creation, and reruns still require confirmation.

Experimental fallback

Structured mode is preferred because OTerminus renders the command from typed arguments. Experimental mode is a constrained fallback for supported commands that cannot yet be represented that way.

When a preview says:

Experimental command: this was not rendered from typed structured arguments. Review it carefully before running.

review the exact rendered command before approving it. Experimental proposals require the exact confirmation phrase EXECUTE EXPERIMENTAL and are never eligible for safe auto-execution, even when the command is read-only.

Natural-language requests

You can ask for tasks like:

• “show disk usage for this folder”
• “search TODO in Python files”
• “find processes matching python”
• “show HTTP headers for https://example.com”
• “look up DNS for example.com”

These requests first pass through ambiguity detection. If the request is specific enough, it goes through capability routing and planning before validation.

Ambiguous natural-language requests

OTerminus may stop vague natural-language requests before any planner call. Examples include:

clean this folder
delete unnecessary files
repair permissions
make this project work

Expected behavior:

• OTerminus stops before planning.
• It shows that the request is ambiguous and includes the reason when useful.
• It suggests safe read-only inspection alternatives, such as listing large files, recently modified files, temporary-looking files, project files, or inspecting permissions.
• It does not ask for confirmation and does not execute anything.

Use a more specific request when you know the target and action. Specific requests can continue to routing, planning, validation, preview, and confirmation, for example:

list large files in this folder
show permissions for run.sh
make run.sh executable

Ambiguity detection is only for vague natural-language requests. Direct shell commands such as chmod +x run.sh or rm -rf build are not intercepted as ambiguous; they continue to the direct command path and must still pass validator and policy checks before any execution.

Proposal modes in previews

Previews show the proposal mode so you can understand how OTerminus will handle the command:

• Structured is the normal, preferred path. OTerminus uses a curated command_family and typed arguments, then renders the final command deterministically.
• Experimental is a constrained fallback for command text that cannot be represented by structured arguments yet. It is still strictly validated and requires stronger confirmation.

If validation or policy checks fail, OTerminus does not ask for execution confirmation.

Safe auto-execute (optional)

By default, OTerminus prompts before execute-mode commands run. Users who prefer a faster workflow for narrowly safe read-only commands can opt in with:

export OTERMINUS_AUTO_EXECUTE_SAFE=true

or with a local .env file:

OTERMINUS_AUTO_EXECUTE_SAFE=true

When enabled, OTerminus still performs the normal lifecycle first: direct detection or planning, validation, policy checks, and deterministic preview rendering. Only after the preview is printed can the runtime skip confirmation, and only when every safe auto-execute rule passes.

Eligible proposals must be:

• structured
• accepted by validation
• exact safe risk
• warning-free and rejection-free
• rendered to a non-empty command and argv
• backed by an enabled, platform-supported, normally executable command spec
• produced by direct-command detection or a deterministic shortcut
• local-only

These requests never qualify:

• network-touching commands such as ping, curl, dig, and nslookup
• write or dangerous commands, including touch
• commands with warnings
• experimental proposals
• LLM-planned proposals
• project-health commands
• archive extraction or creation (tar -xf, unzip ... -d, tar -czf, zip -r)
• history reruns
• dry-run and explain mode
• commands whose registry metadata cannot be resolved, whose pack is disabled, or whose platform is unsupported

When confirmation is skipped, OTerminus prints a concise notice and audit logs record confirmation_result: "skipped_auto_execute_safe". Verbose mode also prints a trace line such as [trace] confirmation=skipped_auto_execute_safe origin=direct_command.

Safety/inspection modes

Dry run

oterminus --dry-run "copy notes.txt to backup/notes.txt"

Dry run is a safety preview for checking what OTerminus would do. It still follows the normal inspection path: detect a direct command when possible, or plan a specific natural-language request after ambiguity checks; then validate the proposal and render the preview. It stops there: dry run does not show a confirmation prompt and never executes the command.

Use dry run when you want to verify detection, planning, validation, policy outcome, and the final rendered command before deciding whether to run the request normally. Direct commands that can be detected locally skip Ollama planning, so a command like oterminus --dry-run "ls" does not require a live Ollama service. Ambiguous natural-language requests stop before planning.

The CLI flag is for one-shot requests only. Inside the REPL, use the built-in form dry-run <request> instead.

Explain mode

oterminus --explain "show running processes"

Explain mode is for learning and debugging why OTerminus chose a command. Like dry run, it performs direct-command detection or natural-language planning, validation, and preview, then skips the confirmation prompt and execution. It additionally renders reasoning about the selected command, available flag or argument meanings, risk level, and policy interpretation, including blocked-policy rationale when validation or policy rejects a proposal.

Use explain mode when you want to understand the path from request to command rather than simply check the final preview. Direct commands that can be detected locally skip Ollama planning, so a command like oterminus --explain "ls" does not require a live Ollama service. Ambiguous natural-language requests stop before planning.

The CLI flag is for one-shot requests only. Inside the REPL, use the built-in form explain <request> or explain <history_id> instead.

When you run with --verbose, trace output includes proposal-source diagnostics such as proposal_source=direct_command planner=skipped, proposal_source=llm_planner planner=invoked, proposal_source=deterministic_shortcut ... planner=skipped, or proposal_source=unknown planner=skipped reason=ambiguity_blocked. It can also include bounded planner schema-repair state such as planner=schema_validation_failed stage=initial and planner=repair_attempt succeeded, plus a concise timing summary (for example: [trace] timings direct=1ms route=1ms planner=skipped ... total=4ms). Trace output does not print full prompts or full raw model output.

REPL session history and rerun safety

REPL always keeps in-memory session history for the current process. Persistent history is optional and controlled by OTERMINUS_HISTORY_ENABLED (default false).

• When OTERMINUS_HISTORY_ENABLED=false, history is session-local only and is cleared when you exit the REPL.
• When OTERMINUS_HISTORY_ENABLED=true, OTerminus also appends local JSONL records to OTERMINUS_HISTORY_PATH (default ~/.oterminus/history.jsonl).
• OTERMINUS_HISTORY_LIMIT controls how many recent persisted records are loaded into the next REPL session (default 100; the env value must be a valid integer; loaded values are clamped to at least 1).
• OTERMINUS_HISTORY_REDACT controls redaction before persisted writes and defaults to the current effective audit-redaction setting when unset everywhere.

History commands:

• history shows all loaded records for the current REPL session (session records plus any loaded persisted records, when enabled).
• history <n> shows the most recent n records.
• explain <history_id> explains the recorded plan/validation result for that entry and never executes.
• rerun <history_id> replays the original user input through the full request lifecycle again (ambiguity checks when applicable, planning/direct-detection path, validation/policy, preview, and explicit confirmation before execution).

rerun does not execute previously rendered command text directly, and cannot bypass policy gates for rejected, ambiguous, cancelled, dry-run, or explain-only outcomes. Reruns never qualify for safe auto-execute.

History output and persisted history files may include command text, local paths, and execution context. Persisted history does not store stdout/stderr, full failure output, or raw planner responses, and OTERMINUS_HISTORY_REDACT is enabled by default when audit redaction is enabled. Review carefully before sharing terminal screenshots or history snippets publicly.

--dry-run and --explain are mutually exclusive and apply to requests, not to the doctor or version diagnostics commands. For example, poetry run oterminus --dry-run doctor, poetry run oterminus doctor --dry-run, and poetry run oterminus --dry-run version are invalid combinations.

Autocomplete

REPL Tab autocomplete is available only inside interactive REPL mode (oterminus, or poetry run oterminus from a development checkout) and is local (prompt_toolkit) for:

• built-ins
• supported command families
• capability IDs (and optional capability hints)
• local filesystem paths

Autocomplete is deterministic and does not call Ollama. It is separate from shell-level completion: oterminus completion zsh|bash|fish prints outer command completion scripts, and OTerminus does not modify zsh, bash, or fish startup files automatically. See Shell completion for shell-level setup.

If REPL Tab autocomplete does not work:

poetry install
poetry run oterminus

If you use a globally installed or pipx build, rebuild/reinstall after dependency changes.

Clear command

clear is supported and handled specially by the local executor using ANSI clear-screen output.

Audit management commands

Audit logs are local JSONL files (default: ~/.oterminus/audit.jsonl) and are not uploaded by OTerminus.

• audit status shows whether audit is enabled, the active path, file presence, and redaction state.
• audit tail shows the most recent 10 events; audit tail <n> shows the newest n events.
• audit clear prompts for exact confirmation (CLEAR AUDIT) before clearing the local audit log.

When audit logging is disabled (OTERMINUS_AUDIT_ENABLED=false), tail/clear commands report that audit is disabled and do not create a log file.

Redaction is enabled by default (OTERMINUS_AUDIT_REDACT=true). Audit events store output truncation metadata and exit codes, not full stdout/stderr. Even with redaction, logs may still contain local paths, command context, and validation decisions, so review before sharing publicly.

If safe auto-execute skips a confirmation prompt, audit events include the bounded decision fields auto_execute_safe_enabled, auto_execute_safe_eligible, auto_execute_safe_reason, and proposal_origin, plus confirmation_result: "skipped_auto_execute_safe".

Safety expectations

• OTerminus may block ambiguous broad/destructive natural-language requests before planning and suggest safer read-only inspections.
• Direct shell commands are not intercepted as ambiguous; they still go through validation and policy checks.
• Unsupported flags, operators, redirection/pipeline chains, and disallowed paths are rejected.
• Experimental mode is a constrained fallback for commands outside typed structured rendering; review the exact command and type EXECUTE EXPERIMENTAL to run it.
• Experimental proposals are never eligible for safe auto-execution.
• Safe auto-execute is disabled by default and applies only to validated, warning-free, local read-only structured commands from direct detection or deterministic shortcuts.
• Commands that fail validation or policy checks are never executed.

Network diagnostics

OTerminus is local-first by default. The network_diagnostics capability is intentionally small and read-only, but it still contacts external hosts and may reveal your IP address, DNS query, target host, or other network metadata. Preview/help text shows the network warning, and execution still requires confirmation. Network commands never qualify for safe auto-execute.

Supported operations:

• ping -c <count> <host> with count from 1 to 10
• curl -I <http-or-https-url> for HTTP HEAD only
• dig <domain>
• nslookup <domain>

Unsupported operations include POST/PUT/PATCH/DELETE, request bodies, arbitrary headers, authorization headers, cookies, downloads, scanning, traceroute, SSH/SCP, netcat, nmap, wget, network commands through sudo, arbitrary network shell commands, and shell pipelines/redirection. OTerminus is still not a general network automation tool.

Environment variable lookup privacy

Curated env support is intentionally narrow because full environment output often includes secrets. Bare env and multi-variable dumps are rejected; accepted requests use a single variable, for example env PATH. OTerminus still warns that environment values may contain secrets, and secret-like lookups such as env TOKEN should not be pasted into public issues, chats, logs, or screenshots without review.

Command pack availability

You can disable specific command packs with OTERMINUS_DISABLED_COMMAND_PACKS. For the exact format, validation rules, and behavior details, see Command pack availability.

You can also choose a profile preset with OTERMINUS_COMMAND_PROFILE: beginner, safe, developer, or power. Profiles are convenience presets for disabled packs only; policy mode, validation, and confirmation remain authoritative. Disabled packs are hidden from autocomplete, planner hints, and discovery output, and disabled commands are rejected before execution even when typed directly. The same profile and explicit disabled-pack fields can be persisted in the user config; exported environment and .env values override persisted values.

Platform-specific commands

Some command families are platform-specific. For example, open is available by default on macOS (darwin) only. On unsupported platforms, these commands are hidden from suggestions and planner hints where practical, and rejected by the validator before execution.

Output size guards

Execution output can be large for commands like cat, grep, find, ps, and lsof. OTerminus truncates each captured stream (stdout and stderr) to OTERMINUS_MAX_OUTPUT_CHARS (default 20000) after command completion, and prints a clear truncation notice when this happens.

Dry-run/explain paths are unchanged because they do not execute commands. Audit logs and persisted history do not store full stdout/stderr content.

Git inspection (read-only)

OTerminus supports read-only Git inspection in curated mode. You can ask directly (for example git status --short) or in natural language (for example "show git status" or "show last 5 commits").

Supported operations:

• git status --short
• git branch --show-current
• git log --oneline -n <count>
• git diff --stat
• git diff --name-only

Explicitly unsupported in curated mode:

• Git mutation operations (git add, git commit, git checkout, git switch, git restore, git reset, git clean, git merge, git rebase, git stash)
• Git network operations (git push, git pull, git fetch)
• Arbitrary Git subcommands not represented by the structured Git inspection schema

All requests still go through routing, planning, validation, and confirmation policy checks. OTerminus is not a replacement for Git automation workflows.

Archive inspection, extraction, and creation

Archive support includes read-only inspection, guarded extraction, and guarded creation for local tar and zip files. Inspection is safe-risk. Extraction and creation are write-risk because they can create files and may overwrite existing files depending on the underlying archive tool behavior.

Supported inspection operations:

• tar -tf <archive>
• unzip -l <archive>

Supported extraction operations:

• tar -xf <archive> -C <destination>
• unzip <archive> -d <destination>

Supported creation operations:

• tar -czf <archive_path> <source_paths...>
• zip -r <archive_path> <source_paths...>

Extraction rules:

• destination is required and must be explicit
• extraction to / and broad system roots is rejected
• configured allowed_roots policy is applied to archive and destination paths
• preview and confirmation are required before execution
• users should inspect archives before extracting them

Creation rules:

• output archive path and every source path must be explicit
• source path /, broad system roots, broad home-directory targets, ., .., and wildcards are rejected
• configured allowed_roots policy is applied to output archive paths and source paths
• archive creation may overwrite or update an existing archive path depending on the underlying tar or zip behavior
• preview and confirmation are required before execution

Explicitly unsupported in this stage:

• extraction without an explicit destination (tar -xf archive.tar, unzip archive.zip)
• overwrite flags such as unzip -o
• password-protected archives, encryption, split archives, append/update flags, deleting sources after compression, arbitrary tar/zip/unzip options, path-transforming tar options, wildcard source or archive selection, hidden automatic source discovery, recursive archive operations, network archive URLs, and sudo

Archive commands still go through validation and confirmation before execution. Unsupported archive forms are rejected rather than treated as broad shell access.

OTerminus does not claim full protection from malicious archive contents in this PR. It validates the command shape, archive path, destination path, and policy boundaries, but it does not inspect archive member paths or block path traversal inside archive contents before calling tar or unzip.

Failure explanations (opt-in)

If OTERMINUS_EXPLAIN_FAILURES=true, OTerminus may print a concise explanation after a confirmed command exits non-zero.

• Runs only after command execution (not in dry-run/explain modes).
• Never auto-executes suggested next actions.
• Suggestions are guidance only (dry-run/copy-only).
• Context sent to explanation is redacted and truncated before it is sent to the configured local Ollama model. Full audit logs and persisted history are not sent.
• Model-returned suggested actions and summaries are redacted before display/audit metadata where applicable.

For exact environment variables, see Configuration reference.

Directory tree inspection

OTerminus supports tree as a structured, read-only filesystem inspection command when the optional external tree executable is already installed and available on PATH. It never installs tree automatically; if it is missing, oterminus doctor reports non-critical guidance to install it with your normal OS package manager.

Supported structured fields are:

• path: one local starting path, defaulting to .. OTerminus expands only ~ and ~/...; it does not expand $HOME, ${HOME}, ~otheruser, globs, or command substitutions.
• max_depth: an optional integer from 1 through 20, rendered as -L <depth>.
• show_hidden: optional hidden-entry output, rendered as -a.
• directories_only: optional directories-only output, rendered as -d.

Examples include tree ., tree -a ., tree -d ~/Downloads, tree -a -d -L 3 ., and tree -ad -L 2 src. Natural-language requests such as show the folder tree for this project, show hidden entries up to three levels deep, and show directories only under ~/Downloads should map to the same typed subset.

Excluded tree features include multiple starting paths, output files, pipes, redirection, pagers, ignore patterns, HTML/XML/JSON or other alternate output formats, color controls, symlink controls, long options such as --help and --version, and arbitrary flag passthrough. Use ls for ordinary directory listings; use tree only for hierarchy overviews.

Project health capability

The project_health capability is a supported curated developer workflow. It uses structured operations only and renders exact project-tooling commands:

• run_tests -> poetry run pytest
• lint_check -> poetry run ruff check .
• format_check -> poetry run ruff format --check .
• build_docs -> npm --prefix website run build
• run_evals -> poetry run oterminus-evals

Clear requests such as run tests, check linting, run format check, build docs, and run evals are natural-language planner requests. They still only produce a proposal: validation, preview, policy checks, and explicit confirmation happen before any execution.

Unsupported requests include dependency/package management (poetry add, poetry install, poetry update, pip install, npm install, brew install), write-formatting (ruff format .), deploy/publish operations, and arbitrary poetry run ... commands.

These operations may execute local project code and tooling. This capability is not arbitrary shell support or arbitrary Poetry command support.

OTerminus also has conservative deterministic shortcuts for a tiny set of fixed utility requests. These can skip Ollama by building structured proposals for:

• show current directory, where am i, print working directory
• clear screen, clear the screen

This optional deterministic_shortcut path only builds structured proposals; it never emits arbitrary shell text and never executes directly. Validation, deterministic preview rendering, policy checks, command-pack availability, platform restrictions, and confirmation policy still apply. Flexible natural-language requests for filesystems, manual pages, text inspection, processes, Git, and project health go to the LLM planner unless they are typed as direct commands such as ls -l, man ls, or git status --short.