AgentShell

A robust command execution wrapper that handles both interactive and non-interactive commands gracefully, returning structured JSON output.

Quick Installation

# Clone and install
git clone https://github.com/mohsen1/agentshell.git
cd agentshell

# Copy to PATH
sudo cp agentshell.sh /usr/local/bin/agentshell
sudo chmod +x /usr/local/bin/agentshell

# Test it
agentshell echo "Hello World"

Cursor AI Integration

Add this rule to your Cursor settings to prevent hangs on interactive commands:

Always use agentshell to run commands and scripts. Instead of running commands directly, prefix them with agentshell. For example, use "agentshell python script.py" instead of "python script.py".

To add: Settings → Rules → Add the above rule

Overview

AgentShell executes commands and reports their state in JSON format. It automatically detects if a command is interactive, completed, or encountered an error.

Key Features:

Detects interactive vs non-interactive commands
Configurable timeout (default: 5 seconds)
Clean JSON output with status, exit code, stdout, and stderr
Automatic process cleanup
Works on Linux and macOS

Usage

# Basic usage
agentshell <command> [args...]

# With custom timeout
agentshell -t 10 <command> [args...]
agentshell --timeout 10 <command> [args...]

Examples

Simple command:

$ agentshell echo "Hello"
{
  "status": "COMPLETED",
  "exit_code": 0,
  "stdout": "Hello\n",
  "stderr": "",
  "message": "Command completed within the timeout."
}

Interactive command (terminates after timeout):

$ agentshell python
{
  "status": "INTERACTIVE",
  "exit_code": null,
  "stdout": "Python 3.9.0 ...",
  "stderr": "",
  "message": "Command did not exit within 5s. Assumed to be interactive or long-running. Process terminated."
}

Command with error:

$ agentshell ls /nonexistent
{
  "status": "COMPLETED",
  "exit_code": 1,
  "stdout": "",
  "stderr": "ls: /nonexistent: No such file or directory\n",
  "message": "Command completed within the timeout."
}

Status Types

COMPLETED: Command finished within timeout
INTERACTIVE: Still running after timeout (likely waiting for input)
ERROR: AgentShell itself encountered an error

Requirements

Bash 4.0+
Standard Unix utilities (mktemp, kill, cat)
Optional: perl (for JSON escaping), stdbuf (for unbuffered output)

Test/Development

The repository includes calculator.js - a simple interactive Node.js calculator used for testing how agentshell handles interactive commands. It's not part of the main tool.

License

MIT

Author

Mohsen Azimi