llmist

Streaming-first multi-provider LLM client in TypeScript with home-made tool calling

The flexible agent and tool layer for any LLM.

---

Installation

npm install llmist

Packages

Package	Description
llmist	Core library - agents, gadgets, providers
@llmist/cli	Command-line interface
@llmist/testing	Testing utilities and mocks

Core Capabilities

Gadget System (Home-Made Tool Calling)

llmist implements its own tool calling syntax called "gadgets" - no native function calling or structured output required.

• LLM- and streaming-friendly block format — Tools execute the moment their block is parsed, not after the response completes
• Built-in dependencies — DAG execution with parallel independent gadgets and sequential dependent ones
• Works with any model — Any LLM that can follow instructions can use gadgets
• Configurable syntax markers — Customize the block delimiters to fit your needs

Agent API

Low-boilerplate, TypeScript-first API for building agents and subagents.

• Fluent builder pattern — Chainable .withModel(), .withGadgets(), .withHooks() configuration
• Full TypeScript inference — Gadget parameters are typed from Zod schemas, no assertions needed
• Class & function gadgets — Classes for complex tools, simple functions for quick ones
• Subagent spawning — Nested agents for complex multi-step tasks

Hook System

Three-layer architecture for deep integration with agent execution. Learn more →

• Observers — Read-only monitoring for logging and analytics
• Interceptors — Synchronous transforms for modifying messages
• Controllers — Async lifecycle control for flow management

Use cases: observability, flow control, benchmarking, human-in-the-loop, deep app/UI integration.

Multi-Provider Support

First-class support for multiple LLM providers with unified API. Learn more →

• OpenAI, Anthropic, Gemini, HuggingFace — Auto-discovery from environment variables
• Caching-aware — Tracks cached vs. uncached tokens for accurate metrics
• Built-in cost calculation — Real-time token counting and cost estimation
• Multimodal — Vision and image input support
• Extensible — Add custom providers or models

CLI & TUI

Developer-first command-line experience for running and building agents. Learn more →

• Config-driven — TOML configuration for reusable profiles and templates
• 3rd party gadget system — Load gadgets from local files, git URLs, or npm packages
• Publish your own — Write and easily share your gadgetry
• Raw LLM access — Control over logging and direct access to request/response content
• Interactive TUI — Browse execution history, inspect raw payloads

Testing Infrastructure

Full mocking for deterministic, LLM-free testing. Learn more →

• MockBuilder — Fluent API for scripting mock responses
• Gadget testing — testGadget() utility for isolated gadget tests
• Agent mocking — Test full agent flows without API calls

Quick Start

Library

npm install llmist
export OPENAI_API_KEY="sk-..."  # or ANTHROPIC_API_KEY, GEMINI_API_KEY, HF_TOKEN

import { LLMist, Gadget, z } from 'llmist';

class DialUp extends Gadget({
  description: 'Simulates connecting to the internet via 56k modem',
  schema: z.object({
    phoneNumber: z.string().describe('ISP dial-up number'),
    baud: z.enum(['14400', '28800', '33600', '56000']).default('56000'),
  }),
}) {
  execute(params: this['params']): string {
    return `ATDT ${params.phoneNumber}... CONNECT ${params.baud}. You've got mail!`;
  }
}

const answer = await LLMist.createAgent()
  .withModel('sonnet')
  .withGadgets(DialUp)
  .askAndCollect('Connect me to AOL');

CLI

npm install -g @llmist/cli

# Quick completion
llmist complete "Explain TypeScript generics"

# Run agent with local gadgets
llmist agent "Search for files" --gadgets ./my-gadgets/

# Use BrowseWeb subagent from Dhalsim for web automation
llmist agent "Find the iPhone 16 Pro price on apple.com" --gadgets dhalsim/BrowseWeb

See Dhalsim for browser automation gadgets.

Testing

npm install -D @llmist/testing

import { testGadget, mockLLM, createMockClient } from '@llmist/testing';

// Test gadgets in isolation
const result = await testGadget(new Calculator(), { a: 5, b: 3 });
expect(result.result).toBe('8');

// Mock LLM responses for agent tests
mockLLM()
  .whenMessageContains('hello')
  .returns('Hi there! How can I help?')
  .register();

const agent = LLMist.createAgent()
  .withClient(createMockClient());

const response = await agent.askAndCollect('hello');
// Deterministic result, no API calls

Documentation

Browse documentation at llmist.dev.

Examples

All examples are in the examples/ directory:

npx tsx examples/01-basic-usage.ts

See examples/README.md for the full list.

Development

npm install
npm run build     # Build all packages
npm run test      # Test all packages
npm run lint      # Lint and format

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE

---

npm • GitHub • Issues