# badlogic/lemmy architecture

> Architecture diagram of the GitHub repository badlogic/lemmy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/badlogic/lemmy
- Repository: https://github.com/badlogic/lemmy

## Overview

##### Project type and purpose
- This is a TypeScript monorepo focused on AI applications.
- Core libraries: “@mariozechner/lemmy” (LLM abstraction and tool execution) and “@mariozechner/lemmy-tui” (terminal UI).
- Multiple CLI apps under /apps (e.g., claude-bridge, claude-trace, lemmy-chat, snap-happy) that demonstrate or extend the core libraries.

##### File structure
- Top level:
- packages/lemmy – LLM client abstractions, tool registry, conversational context management
- packages/lemmy-tui – TUI framework components (renderers, editors, markdown)
- packages/lemmy-cli-args, lemmy-tools, lemmy-tui – utility and example packages for CLI arg parsing and tool handling
- apps/… – standalone applications using core libraries, each with its own src/, test/, build configs
- .github, .husky, tsconfig.json, workspace package.json – monorepo tooling, CI, hooks, TypeScript references
- Each app has:
- src/ folder with CLI entrypoints, interceptors, transformers, HTML or TUI generators
- test/ folder for unit or integration tests
- package.json and build configs (tsup, tsconfig)
- Patterns:
- Modular layered design—core libraries in packages, apps import and extend them
- CLI layer → business logic layer → provider abstractions → external LLM services

##### README for additional insights
- Monorepo uses workspaces and incremental TypeScript builds.
- Core design: unified LLM interface supporting multiple providers, manual tool execution, streaming, context serialization.
- TUI designed with differential rendering, composable components.
- Apps demonstrate interception (claude-bridge), conversation tracing (claude-trace), chat UI (lemmy-chat), native integrations (snap-happy).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Monorepo Management
    subgraph "Monorepo Management"
        WorkspaceManager["Workspace Manager"]:::infra
        CI["CI/CD Pipeline"]:::infra
        Husky["Pre-commit Hooks"]:::infra
    end

    %% Core Libraries
    subgraph "Core Libraries"
        Lemmy["Lemmy<br/>(LLM Abstraction & Tools)"]:::core
        LemmyTUI["Lemmy-TUI<br/>(Differential TUI Components)"]:::core
    end

    %% Utility Packages
    subgraph "Utility Packages"
        CLIArgs["Lemmy-CLI-Args<br/>(CLI Arg Parsing)"]:::util
        Tools["Lemmy-Tools<br/>(Tool Registry & Built-ins)"]:::util
    end

    %% Applications
    subgraph "Applications"
        CB["claude-bridge"]:::app
        CT["claude-trace"]:::app
        LC["lemmy-chat"]:::app
        subgraph "snap-happy"
            SHNode["Node IPC Wrapper"]:::app
            SHSwift["Swift Binary"]:::app
            SHNode -->|"stdio/IPC"| SHSwift
        end
        RT["red-teaming"]:::app
    end

    %% External Services
    subgraph "External Services"
        Anthropic["Anthropic Claude"]:::external
        OpenAI["OpenAI"]:::external
        Gemini["Google Gemini"]:::external
        MCP["MCP Server"]:::external
    end

    %% Build-time Dependencies (dashed)
    WorkspaceManager -.-> Lemmy
    WorkspaceManager -.-> LemmyTUI
    WorkspaceManager -.-> CLIArgs
    WorkspaceManager -.-> Tools
    WorkspaceManager -.-> CB
    WorkspaceManager -.-> CT
    WorkspaceManager -.-> LC
    WorkspaceManager -.-> SHNode
    WorkspaceManager -.-> RT

    CI -.-> Lemmy
    CI -.-> LemmyTUI
    CI -.-> CLIArgs
    CI -.-> Tools
    CI -.-> CB
    CI -.-> CT
    CI -.-> LC
    CI -.-> SHNode
    CI -.-> RT

    Husky -.-> CB
    Husky -.-> CT
    Husky -.-> LC
    Husky -.-> SHNode
    Husky -.-> RT

    %% Runtime Data Flows (solid)
    CB -->|"uses"| Lemmy
    CB -->|"uses"| Tools

    CT -->|"uses"| Lemmy
    CT -->|"renders via"| LemmyTUI

    LC -->|"chat UI via"| LemmyTUI
    LC -->|"logic via"| Lemmy

    SHNode -->|"tools via"| Tools
    SHNode -->|"captures via"| MCP
    SHNode -->|"LLM via"| Lemmy

    RT -->|"uses"| Lemmy

    %% Core to Utilities
    Lemmy -->|"tool registry"| Tools
    Lemmy -->|"cli args via"| CLIArgs
    LemmyTUI -->|"renders for"| LC
    LemmyTUI -->|"renders for"| CT

    %% Providers from Lemmy to External
    Lemmy -->|"Anthropic API"| Anthropic
    Lemmy -->|"OpenAI API"| OpenAI
    Lemmy -->|"Google Gemini API"| Gemini

    %% Snap-happy Native
    SHSwift -->|"sends screenshots"| SHNode

    %% Click Events
    click WorkspaceManager "https://github.com/badlogic/lemmy/blob/main/package.json"
    click WorkspaceManager "https://github.com/badlogic/lemmy/blob/main/tsconfig.json"
    click CI "https://github.com/badlogic/lemmy/blob/main/.github/workflows/ci.yml"
    click Husky "https://github.com/badlogic/lemmy/tree/main/.husky/pre-commit"
    click Lemmy "https://github.com/badlogic/lemmy/tree/main/packages/lemmy/"
    click LemmyTUI "https://github.com/badlogic/lemmy/tree/main/packages/lemmy-tui/"
    click CLIArgs "https://github.com/badlogic/lemmy/tree/main/packages/lemmy-cli-args/"
    click Tools "https://github.com/badlogic/lemmy/tree/main/packages/lemmy-tools/"
    click CB "https://github.com/badlogic/lemmy/tree/main/apps/claude-bridge/"
    click CT "https://github.com/badlogic/lemmy/tree/main/apps/claude-trace/"
    click LC "https://github.com/badlogic/lemmy/tree/main/apps/lemmy-chat/"
    click SHNode "https://github.com/badlogic/lemmy/tree/main/apps/snap-happy/"
    click RT "https://github.com/badlogic/lemmy/tree/main/apps/red-teaming/"

    %% Styles
    classDef core fill:#D6E5FF,stroke:#1E3A8A,color:#1E3A8A;
    classDef util fill:#E6F4EA,stroke:#065F46,color:#065F46;
    classDef app fill:#FEF3C7,stroke:#92400E,color:#92400E;
    classDef external fill:#F3F4F6,stroke:#374151,color:#374151;
    classDef infra fill:#FDEFEE,stroke:#9D174D,color:#9D174D;
```
