lemmy LLM Client Library and Tools

The Lemmy architecture is built around several key abstractions and principles:

• Provider Abstraction: Uses a ChatClient interface to unify different LLM providers.
• Tool Definitions: Tools are defined using Zod schemas for type-safe validation.
• Streaming Support: Supports streaming responses, including specialized handling for thinking/reasoning blocks.
• Context Management: Built-in mechanisms for managing conversation state.
• Type Safety: The project enforces strict typing throughout to avoid the use of any.

Because Context is provider-agnostic, you can switch between different LLM providers (Anthropic, OpenAI, Google) mid-conversation while maintaining the same conversation history and tool definitions.

// Switch providers mid-conversation
const openai = lemmy.openai({
	apiKey: "sk-...",
	model: "gpt-4o",
});

const google = lemmy.google({
	apiKey: "...",
	model: "gemini-1.5-pro",
});

// Same context works across all providers
await claude.ask("Start a story", { context });
await openai.ask("Continue the story", { context });
await google.ask("End the story", { context });

Differential rendering optimizes performance by only updating parts of the screen that have changed.

Components return a result object: {lines: string[], changed: boolean, keepLines?: number}.

• lines: The full set of lines the component should display.
• changed: A boolean indicating if the content has changed.
• keepLines: (For Containers) The number of lines from the top that remain unchanged.

The TUI calculates the total unchanged lines, moves the cursor up by the difference, clears the remaining area using \x1b[0J, and prints only the new lines. Note: Do not add extra cursor positioning after printing, as it interferes with terminal scrolling.

The monorepo is organized into the following key packages and applications:

• @packages/lemmy: The core LLM wrapper library.
• @packages/lemmy-tui: Terminal UI components.
• @packages/lemmy-tools: A collection of built-in and custom tools.
• @packages/lemmy-cli-args: CLI argument parsing utilities.
• apps/: Contains example applications such as chat, bridge, and trace.

By default, claude-trace filters logs to focus on substantial conversations to reduce file size and noise:

• Default behavior: Only logs requests to /v1/messages with more than 2 messages in the conversation.
• With --include-all-requests: Logs all requests made to api.anthropic.com, including single-message requests and other endpoints.

Use the Context class to maintain conversation history and system messages across multiple turns. The Context object also automatically tracks usage costs, which can be retrieved via .getTotalCost().

// Maintain context across multiple messages
const context = new Context();
context.setSystemMessage("You are a helpful coding assistant.");

await claude.ask("My name is Alice", { context });
const result = await claude.ask("What's my name?", { context });
// "Your name is Alice"

// Track costs automatically
console.log(`Total cost: $${context.getTotalCost()}`);

Claude Code is designed to work only with Anthropic models. claude-bridge enables other models by performing the following steps:

1. Spawn: It starts Claude Code as a subprocess using a custom Node.js loader.
2. Patch: It patches the global fetch() function to intercept requests sent to api.anthropic.com/v1/messages.
3. Transform: It converts Anthropic-formatted requests into a unified lemmy format, then into the specific provider's API format.
4. Stream: It converts the provider's response back into Anthropic's Server-Sent Events (SSE) format and streams it back to Claude Code.

When running Claude with interception or extracting tokens, the claude-trace app uses a specific spawning pattern. Instead of executing the path directly, it uses Node.js to execute the file, which allows it to handle symlinks that point to JavaScript files.

Pattern: spawn("node", ["--require", loaderPath, claudePath, ...claudeArgs])

Warning: This pattern requires claudePath to be a valid JavaScript file (or a symlink to one). If claudePath points to a bash wrapper script, the spawn command will fail with error code -1 because Node.js cannot execute bash scripts.

To develop claude-bridge, clone the lemmy repository and set up the monorepo environment.

Setup

git clone https://github.com/badlogic/lemmy
cd lemmy && npm install && npm run dev

Running npm run dev starts compilation in watch mode for all packages and apps.

Testing

Use the following commands to run specific test suites:

• npm run test:all: All tests.
• npm run test:unit: Unit tests.
• npm run test:core: CLI functionality.
• npm run test:tools: Tool integration.
• npm run test:providers: Multi-provider tests.

Debugging in VS Code

To debug using a JavaScript Debug Terminal, use the --patch-claude flag:

npx tsx src/cli.ts <arguments> --patch-claude