How to Use the !command Bang Bash Feature in Claudian

Type ! followed by any shell command in the chat input and press Enter to execute it directly within your vault's working directory.

The bang bash feature in the Claudian plugin (YishenTu/claudian) lets you run shell commands without leaving the chat interface. By prefixing your input with the ! character, you can list files, check git status, or run custom scripts while the results stream directly into the Status Panel.

Enabling the Bang Bash Feature

Before using the feature, you must enable it in the plugin settings.

1. Open Settings → Claudian Settings.
2. Locate the toggle labeled "Enable ! bash mode for direct command execution" (settings.enableBangBash).
3. Ensure Node.js is available in your environment, as the feature relies on child_process.exec.

The setting is stored in core/types/settings.ts and validated in src/features/settings/ClaudianSettings.ts (lines 590–608).

How the Bang Bash Feature Works

When enabled, the feature intercepts your keystrokes in the chat input and switches the UI into a dedicated execution mode.

Triggering Bang Bash Mode

The BangBashModeManager class in src/features/chat/ui/BangBashModeManager.ts monitors every keydown event. When the input box is empty and you press !, the manager calls enterMode(), which:

• Adds the CSS class claudian-input-bang-bash-mode to the input wrapper (styled in src/style/components/input.css lines 194–200).
• Changes the placeholder text to "> Run a bash command…" (defined in src/i18n/locales/en.json).

Executing the Command

After typing your command (e.g., ls -la), press Enter (without Shift). The manager invokes submit(), which triggers the onSubmit callback wired in src/features/chat/tabs/Tab.ts (lines 389–415).

The callback flow is:

1. Status update – A temporary "running" entry appears in the StatusPanel (src/features/chat/ui/StatusPanel.ts lines 560–635).
2. Execution – BangBashService.execute() spawns child_process.exec with:
   • cwd set to your vault’s root directory.
   • env enhanced with enhancedPath (custom binaries available to the plugin).
   • timeout defaulting to 30 seconds.
   • maxBuffer limiting output size.
3. Result handling – The service returns a BangBashResult containing exitCode, stdout, stderr, and an optional error message. The StatusPanel updates the entry with the final status (checkmark for success, cross for error) and renders the output in an expandable section.

Core Source Files

File	Purpose
src/features/chat/ui/BangBashModeManager.ts	Detects the ! trigger, manages UI state, and forwards commands to the service.
src/features/chat/services/BangBashService.ts	Executes commands with timeout, buffer limits, and environment preparation.
src/features/chat/tabs/Tab.ts (lines 389–415)	Instantiates the manager and service per tab.
src/features/chat/ui/StatusPanel.ts (lines 560–635)	Renders the collapsible command output panel.
src/features/settings/ClaudianSettings.ts (lines 590–608)	UI toggle for enabling the feature.
src/i18n/locales/en.json	Localization strings for placeholders and labels.
src/style/components/input.css (lines 194–200)	Styling for the bang-bash input mode.

Practical Usage Examples

List Directory Contents

!ls -la

Press ! to enter mode, type ls -la, then press Enter. The Status Panel displays the file listing with a green checkmark upon completion.

Check Git Status

!git status

Run this to see uncommitted changes directly in the chat context. The command executes in your vault’s root directory, so it reflects the current repository state.

Handle Command Timeouts

!sleep 40

Because the default timeout is 30 seconds, this command will abort and return exit code 124 with an error message stating "Command timed out after 30s". The Status Panel shows a red error icon and the stderr output.

Summary

• Enable first: Toggle enableBangBash in Claudian Settings before using the feature.
• Trigger with !: Press ! in an empty chat input to enter bang bash mode.
• Execute safely: Commands run with a 30‑second timeout and output buffer limits via BangBashService.
• View results: Output appears in the Status Panel’s collapsible command section with copy and clear actions.
• Vault context: All commands execute relative to your vault’s root directory with an enhanced PATH environment.

Frequently Asked Questions

Is the bang bash feature enabled by default?

No. You must explicitly enable it in Settings → Claudian Settings by toggling "Enable ! bash mode for direct command execution". The setting is stored as enableBangBash and validated to ensure Node.js is available in your environment.

What happens if a command times out?

If a command exceeds the default 30‑second timeout, BangBashService aborts the process and returns a result with exitCode: 124 and an error message stating "Command timed out after 30s". The Status Panel displays a red error icon and the stderr output.

Can I run interactive commands that require user input?

No. The bang bash feature uses child_process.exec, which does not support interactive TTY sessions. Commands requiring stdin input (such as nano, vim, or interactive prompts) will hang until the timeout expires and then fail.

Where are command outputs displayed?

Results appear in the Status Panel on the right side of the chat interface. The panel shows a collapsible entry for each command with the command text, status icon (running, completed, or error), and expandable stdout/stderr sections. You can copy the output to the clipboard or clear the history using the panel’s action buttons.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}