Agent-Shell is an innovative framework designed to create AI-first Command Line Interfaces (CLIs) that function as a controllable gateway between Large Language Model (LLM) agents and the execution of commands. This project addresses the scalability challenges faced by AI agents by employing a pattern of 2 tools + vector discovery, maintaining a constant context of approximately 600 tokens, regardless of the number of available commands.

Core Features

Agent-Shell utilizes two essential tools to facilitate user interaction:

Tool 1: cli_help()           → Interaction protocol
Tool 2: cli_exec(cmd: str)   → Execute any command

The framework is structured to allow seamless integration of various commands while ensuring a high degree of reusability and modularity within the code. The following components are fundamental to the architecture of Agent-Shell:

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Server                               │
│                   (JSON-RPC 2.0 / stdio)                        │
├─────────────────────────────────────────────────────────────────┤
│                           Core                                   │
│                    (central orchestrator)                       │
├──────┬──────┬──────┬──────┬──────┬────────┬──────────┬──────────┤
│Parser│Regis-│Execu-│Vector│Contxt│Security│JQ Filter │   CLI    │
│      │ try  │ tor  │Index │Store │        │          │          │
└──────┴──────┴──────┴──────┴──────┴────────┴──────────┴──────────┘

Basic Usage

To get started with Agent-Shell, the following code provides an example of its core functionality:

import { Core } from 'agent-shell';

const core = new Core({
  registry,       // Command registry with registered commands
  vectorIndex,    // Vector index for semantic searching
  contextStore,   // Context store for session state
});

// The LLM agent performs interactions using these 2 calls:
const protocol = core.help();
const response = await core.exec('users:create --name "Juan" --email j@t.com');
// → { code: 0, data: { id: 42, ... }, error: null, meta: { ... } }

Enhanced Command Registration

The Command Registry allows for semantic versioning, ensuring that commands transition smoothly as the application grows. This includes capabilities for undoing operations and the exploration of command options via a defined protocol. Commands can be registered with detailed descriptions and required parameters, making it easy for users to understand their usage.

Security Features

Agent-Shell also integrates robust security mechanisms, including audit logging, Role-Based Access Control (RBAC), and automatic secret detection, ensuring high levels of data integrity and compliance.

Flexibility and Extensibility

Modules within Agent-Shell, such as the JQ Filter for JSON processing and the Context Store for maintaining session history, allow for tailored configurations to adapt to specific user needs. Developers can choose between various database backends for command persistence, including SQLite and custom storage adapters.

Conclusion

Agent-Shell empowers developers to build scalable and efficient AI-first CLIs that can intelligently manage command execution, enhancing workflows and user experiences. With a focus on modularity, security, and extensibility, it provides a comprehensive framework to integrate advanced AI functionalities into command-line interactions.