Quick Start
Installation
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.