Common problems

Start with the affected terminal and its current state. Most issues can be resolved by checking its saved definition, live shell, and the scope of the action you are using.

Commands will not start #

If Run is disabled, finish the current managed or manual command, or stop visible running work with Cmd+.. The floating Run pill is hidden during manual work; Cmd+R still opens the disabled selector. A terminal cannot replace one managed run with another. Confirm that the selector has a highlighted result; Enter with no active row does not execute the filter text.

For missing sidebar Start, startup, or tag Start all behavior, count the terminal's attached commands: those paths require exactly one. Global commands do not count. App startup initializes at most ten profiles, so not every profile is guaranteed to autostart. Check the detailed rules.

If a selected command changed while the selector was open, close and reopen it to refresh. Read any directory or required-variable error before retrying. Directory validation happens before foreground replacement; required-value checks run in the shell before the selected script.

Command Assistant #

Command Assistant requires Terminalis 3.4.0 or later. Open it with Cmd+I or Action → Generate command… in the main terminal window.

For Return to the shell prompt to generate a command, finish or stop foreground work and leave any full-screen terminal app. Wait for a Bash, Zsh, or Fish prompt to finish initializing. If the message persists at an idle prompt, check the shell integration.

For connection or model errors, use Open AI settings. Connect a provider or choose Reconnect when sign-in needs renewing. Wait for model loading to finish, use Refresh models if needed, and select a model available to that account. A model saved in settings may no longer be available.

For a timeout, unreachable service, rate limit, or invalid response, the request stays in the assistant. Check your connection and retry; follow any retry delay shown. If another request is still running, wait for it or cancel it first.

Terminal changed while generating means the result could not be inserted into its original context. Use Copy, Regenerate, or Dismiss when offered. If the message says delivery could not be confirmed, inspect the prompt before retrying. See Terminal changes for details.

Directories and variables #

Use pwd at the prompt to see the live directory. A remembered directory can differ from the configured one, and global commands use that live location. On an idle shell, Cmd+/ returns to the configured directory. Attached commands may have their own override.

Create a missing project folder or correct the saved mapping. For imported setups, check the selected project root and the portable path rules. Import does not install or create the project itself.

For missing environment values, edit the profile or attached-command environment and apply the required shell reinitialization. Avoid dependency cycles and reserved TERMINALIS_ names. A requirement imported as Name only needs a local value. The Hide checkbox changes storage visibility, not runtime availability.

After upgrading to 3.7.0, remove extra wrapping shell quotes from saved environment fields. Values preserve spaces and quotes automatically, while $NAME and ${NAME} references still expand. Move $(...) and other shell evaluation into the command script; see Variable references.

Shell integration #

If a command's state sticks, remembered directories stop updating, or the notification helper is absent, first check which shell the terminal actually starts. Bash, Zsh, and Fish have bundled integration; other shells provide less complete tracking.

Review shell startup customizations that replace the shell with exec, exit early, or overwrite prompt/history hooks. Let the prompt finish initializing before running saved commands. After correcting startup configuration, use Re-Initialize when it is safe to stop the old shell. That menu action clears output, so copy useful error text first.

Do not treat a missing red indicator in an unsupported shell as proof that a command succeeded. Read its output and exit status. Lifecycle explains when shells are created and replaced.

Notifications #

Success and failure alerts are for eligible work that completes while another terminal is selected or the app is unfocused. A quick manually typed command or an explicit interrupt stays quiet. Test with sleep 2 and switch away before it finishes.

Enable alerts and choose Persistent in macOS System Settings → Notifications → Terminalis for command failures, harness alerts, and persistent script requests. Check Focus settings and the notice in Settings → AI Harnesses, then return to Settings to refresh. Ordinary successful-command and script alerts disappear after five seconds, including from history. For standalone scripts, use the raw notification sequence: the interactive helper function may not exist in a child script. Ensure its output reaches the terminal rather than a redirected file.

For a missing agent indicator or alert, check the integration's help tip and use Harness diagnostics. Notification preferences and an acknowledged request can explain a quiet alert without implying that the agent stopped.

Unexpected exits #

After an unexpected exit, reopen Terminalis and choose Help → Open Diagnostics Folder…. Inspect the relevant run's app.log, any panic-*.txt reports, and its session.json. An interrupted marker means normal shutdown was not recorded; it does not identify the cause by itself. macOS may also have a report in ~/Library/Logs/DiagnosticReports/.

These records stay on your Mac and are not uploaded automatically. Read them before sharing because error messages can contain paths or application data. See Local diagnostics for locations and retention.

Imports #

For a parse error, verify the file has one supported YAML document, the right kind, no unknown fields or duplicate keys, and string environment values. Review the displayed error and the file reference.

For duplicate local profiles, check whether you chose a new import instead of Update previous import. Stable terminal IDs let an update reuse existing local profiles; changing an ID creates a new identity. Removed source entries intentionally remain local and can be deleted separately after review.

If source changes do not appear, re-import explicitly: there is no watcher or live synchronization. If a transaction recovery warning appears, preserve its files and the source; do not delete the journal to force progress. Resolve the reported conflict before retrying.

MCP #

Check that Terminalis is running, Settings → AI → MCP access → MCP terminal access is enabled, and Node/npx are available to the client. Reconnect the client after editing its configuration.

If you use TERMINALIS_CONFIG_DIR, the app and wrapper must use the same directory. A stale mcp-port can refer to a closed listener; relaunch the intended app instance to refresh discovery. Disabled access reports an access error rather than an empty list.

Empty output can mean the terminal has no live session or no recent bytes in its bounded buffer. Select the terminal in the app to initialize it if needed. MCP does not read the complete persisted UI scrollback and cannot start commands to produce output. See MCP access.