---
title: "shell mode"
description: "Shell Mode (CLI TUI)"
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/shell-mode
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:46:45.446Z
license: CC-BY-4.0
attribution: "shell mode — Claudary (https://claudary.paisolsolutions.com/skills/shell-mode)"
---

# shell mode
Shell Mode (CLI TUI)

## Overview

Shell Mode (CLI TUI)

Overview

- Shell mode lets users run shell commands directly from the chat input by starting their input with an exclamation mark (!).
- It is intended for quick terminal command execution without leaving the TUI.

Activation

- Shell mode is activated when the current input (trimmed) starts with !
  - Example: "!git status" or " !ls -la" both activate Shell mode.
- Visual indicator:
  - Input border color changes to yellow.
  - The input prompt indicator changes to a yellow "$".
  - The input placeholder includes "! for shell mode".

Deactivation / Exiting Shell Mode

- Pressing Enter to submit the input exits shell mode immediately after submission, regardless of the command result.
- Pressing Esc when the input (trimmed) is exactly ! clears the input and exits shell mode.
- Editing the input so it no longer starts with ! also exits shell mode and restores normal input behavior.

Interaction with other input helpers

- When in shell mode (input starts with !):
  - "@" file search suggestions are disabled.
  - "/" slash command UI is disabled.
- When in slash command mode (input starts with /):
  - "@" file search suggestions are disabled.
  - Enter submits the highlighted slash command directly (except /title, which requires Tab to select first).
  - Tab selects the highlighted command without submitting.

Submission behavior

- On submit (Enter) with a shell-mode input:
  - The leading ! is removed and the remainder is treated as the shell command to run.
  - The TUI immediately appends an assistant message representing a Shell tool call, with status set to calling, so users can see that the command is in progress.
  - The shell command is executed asynchronously; when it completes, the tool call status is updated to done (or error) and the output is populated.

Execution semantics

- The command is executed in the same way as terminal tool commands, minus permissions, and inserted into the chat history the same.

Output handling

- Stdout is streamed into memory; Stderr is captured and appended as a trailing "Stderr: ..." section on success.
- If the process exits non-zero and Stderr contains content, the tool call is marked as error and the error text is shown.
- Output is truncated to the first 5000 lines if exceeded.
- Timeout behavior: If no output is received for 120 seconds (configurable in tests), the process is terminated and the result includes a note like:
  "[Command timed out after 120 seconds of no output]".

Keyboard behaviors (summary)

- Enter: submit input. If in shell mode, exits shell mode after submission and shows the pending Shell tool call immediately.
- Shift+Enter: new line.
- Backslash (\\) at end-of-line: inserts a new line (line continuation) as usual.
- Esc: if only ! (trimmed) is present, clears input and exits shell mode; otherwise cancels streaming or closes suggestions depending on context.

Scope / Modes

- Shell mode applies to interactive (TUI/standard) CLI usage. It is not part of headless (-p/--print) processing.

Error handling

- Command execution errors are captured and surfaced in the tool call as status error with human-readable error text (including Stderr when available).

Examples

- "!git status" → shows a Shell tool call immediately, then populates with the git status output.
- "!echo hello" → shows a Shell tool call immediately, then output "hello".
- "!some-unknown-cmd" → shows a Shell tool call immediately, then sets status to error with an error message.

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/shell-mode) · https://claudary.paisolsolutions.com