Skip to content
llmist llmist

CLI Gadgets

Write gadgets (tools) for use with llmist agent.

Quick Start

Section titled “Quick Start”

Create a file with a gadget class:

floppy.ts
import { Gadget, z } from 'llmist';


export class FloppyDisk extends Gadget({
  description: 'Calculate how many 1.44MB floppy disks are needed',
  schema: z.object({
    filename: z.string(),
    megabytes: z.number().positive(),
  }),
}) {
  execute(params: this['params']): string {
    const { filename, megabytes } = params;
    const disks = Math.ceil(megabytes / 1.44);
    return `${filename} requires ${disks} floppy disk(s). Label them 1/${disks}, 2/${disks}...`;
  }
}

Use it:

Terminal window
bunx @llmist/cli agent "How many floppies for DOOM.ZIP at 50MB?" --gadget ./floppy.ts

File Requirements

Section titled “File Requirements”

Gadget files must:

  1. Export one or more gadget classes
  2. Use TypeScript or JavaScript
  3. Be a valid ES module
// Multiple exports work
export class FloppyDisk extends Gadget({ ... }) { ... }
export class DialUpModem extends Gadget({ ... }) { ... }


// Default exports work too
export default class ArcadeHighScore extends Gadget({ ... }) { ... }

Loading Multiple Gadgets

Section titled “Loading Multiple Gadgets”
Terminal window
# Multiple files
bunx @llmist/cli agent "Calculate floppies and connect to BBS" \
  --gadget ./floppy.ts \
  --gadget ./dialup.ts


# Single file with multiple exports
bunx @llmist/cli agent "Calculate floppies and dial up" --gadget ./retro-tools.ts

Loading Specific Gadgets

Section titled “Loading Specific Gadgets”

Load a specific gadget from a file or package using the appropriate suffix:

Terminal window
# Load only FloppyDisk from a file with multiple exports (colon separator)
bunx @llmist/cli agent "Calculate floppies" --gadget ./retro-tools.ts:FloppyDisk


# Load BrowseWeb subagent from npm package (slash separator)
bunx @llmist/cli agent "Browse apple.com" -g dhalsim/BrowseWeb


# Load from scoped npm package
bunx @llmist/cli agent "task" -g @myorg/my-gadgets/MyGadget


# Load from git URL (slash separator)
bunx @llmist/cli agent "task" -g git+https://github.com/user/repo#main/MyGadget

External Gadgets

Section titled “External Gadgets”

Load gadgets from npm packages or git repositories:

Terminal window
# npm package (Dhalsim browser automation)
bunx @llmist/cli agent "Navigate to apple.com" -g dhalsim


# Use a preset
bunx @llmist/cli agent "Browse the web" -g dhalsim:minimal


# Load specific gadget from package
bunx @llmist/cli agent "Browse the web" -g dhalsim/BrowseWeb


# git URL
bunx @llmist/cli agent "task" -g git+https://github.com/user/repo.git


# git URL with specific gadget
bunx @llmist/cli agent "task" -g git+https://github.com/user/repo.git#main/MyGadget


# Combine sources
bunx @llmist/cli agent "Complex task" \
  -g ./local-gadget.ts \
  -g dhalsim/BrowseWeb \
  -g builtin:ReadFile

See Gadget Ecosystem for detailed documentation on Dhalsim, presets, and creating your own packages.

Testing Gadgets

Section titled “Testing Gadgets”

Use the gadget command to test in isolation:

Terminal window
# Run interactively
bunx @llmist/cli gadget run ./floppy.ts


# View gadget info
bunx @llmist/cli gadget info ./floppy.ts


# Validate structure
bunx @llmist/cli gadget validate ./floppy.ts


# Pipe JSON input
echo '{"filename": "DOOM.ZIP", "megabytes": 50}' | bunx @llmist/cli gadget run ./floppy.ts

Creating External Packages

Section titled “Creating External Packages”

Add an llmist field to package.json:

{
  "name": "my-gadgets",
  "llmist": {
    "gadgets": "./dist/index.js",
    "presets": {
      "all": "*",
      "minimal": ["GadgetA", "GadgetB"]
    }
  }
}

See Also

Section titled “See Also”