Skip to content

Quick Start

Installation

npm install @johannes.latzel/llm-chat-shell

Quick setup

import { ShellPackage } from '@johannes.latzel/llm-chat-shell';

const pkg = new ShellPackage();
service.tools().add(pkg);

Permission configuration

Example: Allow git commands and ls, deny rm, and deny everything else:

import {
    ShellPackage,
    ShellConfiguration,
    PermissionAction
} from '@johannes.latzel/llm-chat-shell';

const config = new ShellConfiguration();
config.defaultPermission = PermissionAction.Deny;
config.permissionRules = [
    { pattern: 'git *', action: PermissionAction.Allow },
    { pattern: 'ls *', action: PermissionAction.Allow },
    { pattern: 'rm *', action: PermissionAction.Deny }
];

const pkg = new ShellPackage(config);
service.tools().add(pkg);

Session management

The package manages sessions automatically. For explicit lifecycle control:

The workspace is provided by the @johannes.latzel/llm-chat-workspace package:

import {
    ShellPackage,
    ShellConfiguration,
    ShellSessionManager,
    BashShellExecutor
} from '@johannes.latzel/llm-chat-shell';
import { Workspace, DirectoryConfiguration } from '@johannes.latzel/llm-chat-workspace';

const config = new ShellConfiguration();
config.maxSessions = 5;
config.sessionTimeout = 1800000; // 30 minutes

const workspace = new Workspace(new DirectoryConfiguration());
const manager = new ShellSessionManager(
    { create: (cwd?) => Promise.resolve(new BashShellExecutor(cwd ? { ...config, cwd } : config)) },
    config,
    workspace
);
const pkg = new ShellPackage(config, manager);
service.tools().add(pkg);

// ... later:
await manager.close();

MCP server usage

When using with an MCP server, the client can pass a cwd to shell_create to run commands in a specific directory:

import { ShellPackage, ShellConfiguration } from '@johannes.latzel/llm-chat-shell';
import { StdioMcpServer } from '@johannes.latzel/llm-chat-mcp';

const config = new ShellConfiguration();

const pkg = new ShellPackage(config);

const mcpServer = new StdioMcpServer({ name: 'shell', version: '0.1.0' });
mcpServer.registerTool(pkg);
await mcpServer.start();

// MCP client calls: shell_create({ cwd: "/path/to/project" })
// Sessions are scoped to that directory

The cwd parameter is validated to ensure it resolves within the workspace's accessible directories. Relative paths are resolved against the current workspace.

Next steps

See the API Reference for full tool documentation and Architecture for design details.