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