🐚 Autonomous Shell Plugin

An unofficial, community-driven shell plugin for Eaze Editor that gives AI agents direct, secure access to your system's shell.

Features • MCP Tools • Installation • Configuration • Security • Building • Contributing

---

📖 Overview

The Autonomous Shell Plugin empowers AI agents inside Eaze Editor with the ability to create persistent shell sessions, execute commands synchronously or asynchronously, interact with programs that prompt for user input, and monitor long-running processes — all governed by a robust security layer.

It exposes its capabilities as MCP (Model Context Protocol) tools using the @Tool annotation, making them automatically discoverable by any AI model connected to the editor.

Why This Plugin?

Problem	Solution
AI agents can't run shell commands	Provides execute_command_sync and execute_command_async tools
No way to interact with prompts	send_shell_input sends keystrokes to interactive sessions
Long-running processes block the AI	Async execution + get_command_result polling pattern
Repeated output wastes tokens	Token Optimization returns only new (delta) output
Dangerous commands could be run	Configurable Blacklist / Whitelist safety filter
AI doesn't know system specs	get_system_info reports real RAM, CPU, GPU, and OS details

---

✨ Features

• Persistent Shell Sessions — Create isolated shell environments that maintain state (environment variables, working directory) across multiple commands.
• Synchronous Execution — Run short-lived commands and get the result immediately, with configurable timeout (hours / minutes / seconds).
• Asynchronous Execution — Launch long-running tasks (servers, builds, scripts) in the background and poll for output.
• Interactive Input — Send text input to interactive programs (e.g., answering y/n prompts, typing into a REPL).
• Token Optimization — When enabled, get_command_result only returns new output since the last call, dramatically reducing token consumption for log-heavy processes.
• Command Safety Filter — Blacklist or whitelist mode to prevent dangerous commands from being executed.
• System Information — Reports accurate physical RAM, CPU count, GPU name + VRAM (via nvidia-smi), JVM memory, and OS details.
• Settings UI — A beautiful, tabbed settings page (General / Security / Advanced) served directly inside the editor.

---

🔧 MCP Tools Reference

The plugin registers the following tools that are automatically discoverable by AI models:

Session Management

Tool	Description
create_shell_session	Creates a new persistent shell session. Returns a unique sessionId required by all other tools.
list_shell_sessions	Lists all active sessions with their IDs and creation timestamps.
terminate_shell_session	Terminates and cleans up a specific session by ID. Always call this when done.
clear_all_shell_sessions	Force-terminates all active sessions. Use with caution.

Command Execution

Tool	Parameters	Description
execute_command_sync	sessionId, command	Runs a command and blocks until completion or timeout. Best for quick commands like ls, pwd, cat.
execute_command_async	sessionId, command, interactive	Starts a background command. Set interactive=true for programs requiring user input. Returns a commandId.
get_command_result	sessionId, commandId	Retrieves output from an async command. Supports Token Optimization (delta-only output).
send_shell_input	sessionId, input	Sends text input to an interactive command. Append \n to simulate pressing Enter.

System

Tool	Description
get_system_info	Returns OS name/version/arch, physical RAM, GPU info, CPU count, JVM memory, and working directory.

Typical Workflow

1. create_shell_session          → sessionId = "sess-abc123"
2. execute_command_sync           → "ls -la" (quick)
3. execute_command_async          → "npm start" → commandId = "cmd-xyz"
4. get_command_result (poll)      → new output since last call
5. send_shell_input               → "y\n" (respond to prompt)
6. terminate_shell_session        → clean up

---

📦 Installation

From Pre-built JAR

1. Download the latest autonomous-shell-eaze-editor-plugin-1.0.0.jar from the Releases page.
2. Place the JAR in your Eaze Editor's plugin directory.
3. Restart the editor — the plugin registers itself automatically via annotations.

From Source

See Building from Source below.

---

⚙️ Configuration

The plugin provides a built-in settings UI accessible from the editor's plugin settings panel. Settings are organized into three tabs:

General Settings

Setting	Default	Description
Command Safety Filter	Off	Master toggle for command filtering.
Global Timeout	0h 1m 0s	Maximum execution time for synchronous commands. Configurable in hours, minutes, and seconds.

Security

Setting	Default	Description
Filter Mode	Blacklist	Blacklist — block listed commands; Whitelist — allow only listed commands.
Command List	(empty)	Comma-separated base commands to filter (e.g., rm, mkfs, dd, shutdown).

Filter Logic

if mode == "whitelist":
    command is ALLOWED only if it is IN the list
elif mode == "blacklist":
    command is BLOCKED only if it is IN the list

# If the list is empty:
#   Blacklist → all commands allowed
#   Whitelist → all commands blocked

Advanced

Setting	Default	Description
Token Optimization	On	When enabled, get_command_result returns only new output since the last query (delta mode). When disabled, returns the complete accumulated output every time.

Token Optimization — How It Works

Call 1:  full output = "line 1\nline 2"     → returns "line 1\nline 2"
Call 2:  full output = "line 1\nline 2\nline 3" → returns "line 3" (delta only)
Call 3:  (command finished)                  → tracking data is cleaned up

This significantly reduces token consumption when polling long-running server logs or build output.

---

🛡️ Security

⚠️ This plugin grants AI agents direct access to your system's shell.

Recommendations

1. Never run the editor as root/admin unless absolutely necessary.
2. Enable the Safety Filter and use Whitelist mode in production or shared environments.
3. Review the command list — pre-populate it with dangerous commands like rm -rf, mkfs, dd, format, shutdown, reboot.
4. Monitor session activity — use list_shell_sessions to audit active environments.
5. Terminate sessions when done to prevent orphaned processes consuming system resources.

What the Filter Catches

The filter extracts the base command (first word) from the input and checks it against the configured list:

Input: "rm -rf /important/data"  →  Base command: "rm"
Input: "sudo apt install foo"    →  Base command: "sudo"

For detailed security information, see SECURITY.md.

---

🏗️ Building from Source

Prerequisites

• Java 25 (JDK)
• Gradle 9.3.1+ (or use the included Gradle wrapper)

Build

# Clone the repository
git clone https://github.com/nurujjamanpollob/autonomous-shell-eaze-editor-plugin.git
cd autonomous-shell-eaze-editor-plugin

# Build the plugin JAR
./gradlew jar         # Linux / macOS
gradlew.bat jar       # Windows

The output JAR is generated at:

build/libs/autonomous-shell-eaze-editor-plugin-1.0.0.jar

Run Tests

./gradlew test

Project Structure

autonomous-shell-eaze-editor-plugin/
├── build.gradle                          # Build configuration
├── sdks/                                 # Compile-time & runtime SDK dependencies
│   ├── eaze_editor_code_sdk.jar          # Host SDK (compile-only, provided at runtime)
│   ├── autonomous-shell-executor-1.0.0.jar  # Shell execution engine (bundled)
│   └── plugin_library-1.0-SNAPSHOT.jar      # Plugin framework library (bundled)
├── src/
│   ├── main/
│   │   ├── java/com/pollob/eazeeditor/plugin/shell/
│   │   │   ├── Main.java                        # Entry point
│   │   │   ├── mcp/
│   │   │   │   └── ShellMCP.java                # MCP tool definitions (AI tools)
│   │   │   ├── pluginlifecycle/
│   │   │   │   └── PlugInLifeCycleObserver.java  # Plugin lifecycle hooks
│   │   │   ├── setting/
│   │   │   │   ├── ShellSettingDiscovery.java    # Annotation-based settings registration
│   │   │   │   └── ShellSettingsHandler.java     # Settings HTTP handler & API
│   │   │   └── util/
│   │   │       └── Vars.java                     # Constants, setting keys, defaults
│   │   └── resources/autonomous-shell-plugin/
│   │       ├── settings.html             # Settings UI (tabbed, Tailwind CSS)
│   │       ├── about.html                # Documentation / About page
│   │       ├── script.js                 # Settings frontend logic
│   │       └── tailwind.cdn.js           # Tailwind CSS (offline CDN)
│   └── test/
│       └── java/.../InteractiveMCPTest.java  # Interactive integration test

SDK Dependencies

Dependency	Scope	Bundled?	Purpose
eaze_editor_code_sdk.jar	compileOnly	No — provided by host	Editor core APIs, Plugin APIs, Settings SDK
autonomous-shell-executor-1.0.0.jar	implementation	Yes	Shell process management engine
plugin_library-1.0-SNAPSHOT.jar	implementation	Yes	Plugin framework utilities

---

🏛️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     Eaze Editor Host                     │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │  AI Model   │  │  Plugin API  │  │  Settings API  │ │
│  └──────┬──────┘  └──────┬───────┘  └───────┬────────┘ │
│         │                │                   │          │
└─────────┼────────────────┼───────────────────┼──────────┘
          │                │                   │
┌─────────┼────────────────┼───────────────────┼──────────┐
│         ▼                ▼                   ▼          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │  ShellMCP   │  │  Lifecycle   │  │   Settings     │ │
│  │  (@Tool)    │  │  Observer    │  │   Handler      │ │
│  └──────┬──────┘  └──────────────┘  └────────────────┘ │
│         │                                               │
│         ▼                                               │
│  ┌──────────────────┐                                   │
│  │  ShellExecutor   │    Autonomous Shell Plugin        │
│  │  (Session Mgmt,  │                                   │
│  │   Process I/O)   │                                   │
│  └──────────────────┘                                   │
└─────────────────────────────────────────────────────────┘

Key Components

Component	Class	Responsibility
MCP Tools	ShellMCP	Annotated with @EazeAiComponent and @Tool — exposes shell capabilities to AI models.
Lifecycle	PlugInLifeCycleObserver	Handles ON_LOAD, ON_CLOSE, ON_ERROR lifecycle phases. Initializes the settings handler on load.
Settings Discovery	ShellSettingDiscovery	Annotation-based (@PluginSettingsDiscovery) auto-registration with the editor's settings system.
Settings Handler	ShellSettingsHandler	Extends BaseSettingsHandler to serve the settings UI and handle GET/POST API routes.
Constants	Vars	Centralized plugin name, setting keys, and default values.

---

🧪 Testing

The project includes an interactive integration test (InteractiveMCPTest.java) that exercises the full tool chain:

1. Retrieves system information
2. Creates a shell session
3. Executes a synchronous command (java -version)
4. Compiles and runs an interactive Java program asynchronously
5. Polls output and sends user input via sendShellInput
6. Verifies the complete output and cleans up

Run it directly:

./gradlew test
# Or run the main method in InteractiveMCPTest for the full interactive demo

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: ./gradlew test
5. Submit a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

👤 Author

Nurujjaman Pollob

• GitHub: @nurujjamanpollob

---

🙏 Acknowledgments

• Eaze Editor for the plugin SDK and platform
• Tailwind CSS for the settings UI styling

---

_{Made with ❤️ for the Eaze Editor community}