Built-in Gadgets

The CLI includes 5 built-in gadgets for filesystem operations and command execution. You can import these gadgets directly into your projects.

Installation

npm install @llmist/cli

Usage

import { ReadFile, WriteFile, RunCommand, ListDirectory, EditFile } from '@llmist/cli/gadgets';
import { AgentBuilder } from 'llmist';

const agent = new AgentBuilder()
  .withModel('sonnet')
  .withGadgets(ReadFile, WriteFile, ListDirectory, RunCommand)
  .ask('Read package.json and list the dependencies');

for await (const event of agent.run()) {
  if (event.type === 'text') {
    process.stdout.write(event.text);
  }
}

Available Gadgets

Filesystem Gadgets

Gadget	Description
`ListDirectory`	List files and directories with metadata (size, age)
`ReadFile`	Read the entire content of a file
`WriteFile`	Write content to a file (creates directories if needed)
`EditFile`	Edit files using search/replace with intelligent matching

System Gadgets

Gadget	Description
`RunCommand`	Execute a command with arguments and return output

Gadget Details

ListDirectory

Lists files and directories with metadata in a compact format.

import { ListDirectory } from '@llmist/cli/gadgets';

// Schema: { directoryPath: string, maxDepth: number (1-10) }

ReadFile

Reads the entire content of a file.

import { ReadFile } from '@llmist/cli/gadgets';

// Schema: { filePath: string }

WriteFile

Writes content to a file, creating parent directories if needed.

import { WriteFile } from '@llmist/cli/gadgets';

// Schema: { filePath: string, content: string }

EditFile

Edits files using search/replace with intelligent layered matching. This approach reduces edit errors by ~9x compared to naive text replacement.

Matching strategies (tried in order):

Exact - byte-for-byte comparison
Whitespace-insensitive - ignores differences in spaces/tabs
Indentation-preserving - matches structure ignoring leading whitespace
Fuzzy - similarity-based matching (80% threshold)

import { EditFile } from '@llmist/cli/gadgets';

// Schema: { filePath: string, search: string, replace: string }

RunCommand

Executes system commands with arguments (bypasses shell interpretation).

import { RunCommand } from '@llmist/cli/gadgets';

// Schema: { argv: string[], cwd?: string, timeout?: number }

Utilities

For building custom filesystem gadgets with the same sandboxing behavior:

import { validatePathIsWithinCwd, PathSandboxException } from '@llmist/cli/gadgets';

try {
  const safePath = validatePathIsWithinCwd(userInput);
  // safePath is guaranteed to be within cwd
} catch (error) {
  if (error instanceof PathSandboxException) {
    console.error('Access denied:', error.message);
  }
}

Complete Example

import { AgentBuilder } from 'llmist';
import { ReadFile, WriteFile, ListDirectory, RunCommand } from '@llmist/cli/gadgets';

async function main() {
  const agent = new AgentBuilder()
    .withModel('sonnet')
    .withGadgets(ReadFile, WriteFile, ListDirectory, RunCommand)
    .withSystemPrompt('You are a helpful coding assistant.')
    .ask('Find all TypeScript files and count the lines of code');

  for await (const event of agent.run()) {
    if (event.type === 'text') {
      process.stdout.write(event.text);
    }
  }
}

main();

Naming Conventions

Each gadget is exported with two names for convenience:

// PascalCase (matches gadget name - recommended)
import { ReadFile, WriteFile } from '@llmist/cli/gadgets';

// camelCase (internal convention)
import { readFile, writeFile } from '@llmist/cli/gadgets';