claw-shell

name	claw-shell
description	Use this skill whenever any NeuroClaw skill, sub-agent, or model needs to execute shell commands safely (e.g. source environment scripts, run recon-all, git operations, conda commands, ls, cat logs, etc.). Triggers include: 'run shell', 'execute command', 'shell command', 'tmux claw', 'run in claw session', 'safe shell execution', or any request that requires running terminal commands. This skill is the mandatory gatekeeper for all shell execution in NeuroClaw: it ALWAYS routes commands through the dedicated tmux session `claw`, never touches other sessions, and returns captured output to the calling agent.
license	MIT License (NeuroClaw core skill – freely modifiable within the project)
layer	base
skill_type	tool
dependencies	[]

Claw Shell

Overview

claw-shell is the central, safe shell execution layer for the entire NeuroClaw system. All long-running or system-level commands (FreeSurfer recon-all, dependency installation steps, git operations, conda commands, file operations, etc.) are routed through this skill.

Core principles:

• Always uses the dedicated tmux session named claw (creates it automatically if missing).
• Never touches any other tmux session or runs commands directly in the main shell.
• Captures the latest pane output and returns it to the calling skill/agent.
• Enforces strict safety rules: dangerous commands (sudo, rm, reboot, etc.) trigger an explicit user confirmation step before execution.

This design solves the problems of the main agent not proactively installing dependencies and handling long-running commands, as identified in the MedicalClaw evaluation, by providing centralized logging, detachment support, and safe execution.

Quick Reference

Type	Example Commands	Behavior
Safe (direct run)	ls -la, cat log.txt, git status	Executes immediately in claw session
Environment setup	source $FREESURFER_HOME/SetUpFreeSurfer.sh	Executes and returns output
Long-running pipeline	recon-all -subjid sub-001 -all -parallel	Runs in background-capable tmux pane
Dangerous (requires confirmation)	rm -rf ..., sudo apt install ..., docker system prune -a	Asks user “YES” before proceeding

Tool Interface
Tool name: claw_shell_run
Input:

• command (string, required): the full shell command to run inside the claw tmux session.

Installation

This is a core NeuroClaw skill and requires no external packages beyond tmux.

One-time setup (run once via dependency-planner or manually):

# Ensure tmux session exists
tmux new -s claw -d || true

To register in NeuroClaw:

# Place files in: skills/claw-shell/
# Update SOUL.md and/or USER.md to register as the default shell executor

Usage Examples

Example 1: Simple command

# Skill call:
claw_shell_run with command="ls -la /data"

# Returns captured tmux pane output directly to the agent

Example 2: FreeSurfer environment + recon-all (delegated from freesurfer-tool)

# Internal commands sent to claw-shell:
1. export FREESURFER_HOME=/usr/local/freesurfer
2. source $FREESURFER_HOME/SetUpFreeSurfer.sh
3. recon-all -subjid sub-001 -i ./T1.nii.gz -all -parallel -openmp 8

Example 3: Dangerous command (safety trigger)

# User requests: rm -rf /tmp/old_data
# claw-shell automatically responds:
"Warning: This command contains 'rm'. Do you confirm execution? Reply YES to proceed."

NeuroClaw recommended wrapper script

# claw_shell.py
import argparse
import sys

# In real NeuroClaw this is implemented as a tool call, not direct Python execution
def claw_shell_run(command: str):
    print(f"[claw-shell] Sending to tmux session 'claw':")
    print(f"  {command}")
    print("\n[Simulation] Command executed. Output would be captured here.")
    # Real implementation:
    # return agent.tool_call("claw_shell_run", {"command": command})

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="NeuroClaw Claw-Shell Wrapper")
    parser.add_argument("--command", required=True, help="Shell command to run in tmux session 'claw'")
    args = parser.parse_args()
    claw_shell_run(args.command)

Important Notes & Limitations

• Always runs inside tmux session claw — never in the main shell or any other session.
• Safety enforcement:
  • Commands containing sudo, rm -rf, reboot, shutdown, docker system prune, destructive chmod, etc. must receive explicit user “YES” confirmation.
  • Long-running commands (e.g. recon-all) are safe because they run detached in tmux.
• Output is always captured and returned to the calling skill.
• Session is persistent across NeuroClaw runs (ideal for monitoring long pipelines).

When to Call This Skill

• Any skill (freesurfer-tool, dependency-planner, git-essentials, etc.) needs to run shell commands.
• Post-installation environment variable setup.
• File operations, log checking, or any terminal action inside NeuroClaw.

Complementary / Related Skills

• dependency-planner → delegates installation and environment variable commands here

Reference

Custom core skill designed for NeuroClaw to provide safe, tmux-based shell execution while solving the dependency and long-running command issues from the MedicalClaw evaluation.

---

Created At: 2026-03-19 20:00 HKT
Last Updated At: 2026-03-25 16:22 HKT
Author: chengwang96