# ryanstephen/lil-agents architecture

> Architecture diagram of the GitHub repository ryanstephen/lil-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryanstephen/lil-agents
- Repository: https://github.com/ryanstephen/lil-agents

## Overview

Lil Agents is a macOS menu-bar and Dock companion app: users click an animated character, chat in its themed terminal, and receive responses from a selected local agent CLI or OpenClaw gateway. The graph follows the documented interaction and the source-index references; several UI and controller implementation details are unsampled, so their links are limited to visible references or README statements.

Main entry points: [`LilAgents/AgentSession.swift`](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/AgentSession.swift) (Provider selection), [`LilAgents/WalkerCharacter.swift`](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/WalkerCharacter.swift) (Walking characters), [`LilAgents/ShellEnvironment.swift`](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/ShellEnvironment.swift) (Shell environment), [`LilAgents/LilAgentsApp.swift`](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/LilAgentsApp.swift) (App and menus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Dock"]
  node_app["App and menus<br/>[LilAgentsApp.swift]"]
  node_controller["Character controller"]
  node_dock["Dock visibility"]
  node_walker["Walking characters"]
  node_character_view["Character view"]
end

subgraph group_chat["Chat Experience"]
  node_terminal["Popover terminal<br/>[TerminalView.swift]"]
  node_themes["Visual themes<br/>[PopoverTheme.swift]"]
end

subgraph group_agents["Agent Sessions"]
  node_session_api["Provider selection<br/>[AgentSession.swift]"]
  node_claude["Claude session"]
  node_codex["Codex session<br/>[CodexSession.swift]"]
  node_copilot["Copilot session"]
  node_gemini["Gemini session"]
  node_opencode["OpenCode session"]
  node_openclaw["OpenClaw session"]
end

subgraph group_support["Runtime Support"]
  node_shell["Shell environment"]
end

node_user(("Mac user"))
node_local_cli["Installed agent CLI"]
node_gateway["OpenClaw gateway"]

node_user -->|"uses"| node_app
node_app -->|"starts"| node_controller
node_app -->|"configures"| node_themes
node_app -->|"uses"| node_walker
node_controller -->|"sets up"| node_walker
node_controller -->|"checks visibility"| node_dock
node_walker -->|"opens chat"| node_terminal
node_walker -->|"creates session"| node_session_api
node_walker -->|"styles popover"| node_themes
node_character_view -->|"renders"| node_walker
node_terminal -->|"uses"| node_themes
node_session_api -->|"creates"| node_claude
node_session_api -->|"creates"| node_codex
node_session_api -->|"creates"| node_copilot
node_session_api -->|"creates"| node_gemini
node_session_api -->|"creates"| node_opencode
node_session_api -->|"creates"| node_openclaw
node_claude -->|"resolves environment"| node_shell
node_codex -->|"resolves environment"| node_shell
node_copilot -->|"finds CLI"| node_shell
node_gemini -->|"sets environment"| node_shell
node_opencode -->|"finds CLI"| node_shell
node_claude -->|"runs locally"| node_local_cli
node_codex -->|"runs locally"| node_local_cli
node_copilot -->|"runs locally"| node_local_cli
node_gemini -->|"runs locally"| node_local_cli
node_opencode -.->|"runs locally"| node_local_cli
node_openclaw -->|"connects by WebSocket"| node_gateway

click node_app "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/LilAgentsApp.swift"
click node_controller "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/LilAgentsController.swift"
click node_dock "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/DockVisibility.swift"
click node_walker "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/WalkerCharacter.swift"
click node_character_view "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CharacterContentView.swift"
click node_terminal "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/TerminalView.swift"
click node_themes "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/PopoverTheme.swift"
click node_session_api "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/AgentSession.swift"
click node_claude "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/ClaudeSession.swift"
click node_codex "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CodexSession.swift"
click node_copilot "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CopilotSession.swift"
click node_gemini "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/GeminiSession.swift"
click node_opencode "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/OpenCodeSession.swift"
click node_openclaw "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/OpenClawSession.swift"
click node_shell "https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/ShellEnvironment.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_controller,node_dock,node_walker,node_character_view,node_user toneBlue
class node_terminal,node_themes toneAmber
class node_session_api,node_claude,node_codex,node_copilot,node_gemini,node_opencode,node_openclaw toneMint
class node_shell toneRose
class node_local_cli,node_gateway toneIndigo
```

## Components

### App and Dock

- [App and menus](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/LilAgentsApp.swift): `LilAgents/LilAgentsApp.swift`
- [Character controller](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/LilAgentsController.swift): `LilAgents/LilAgentsController.swift`
- [Dock visibility](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/DockVisibility.swift): `LilAgents/DockVisibility.swift`
- [Walking characters](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/WalkerCharacter.swift): `LilAgents/WalkerCharacter.swift`
- [Character view](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CharacterContentView.swift): `LilAgents/CharacterContentView.swift`

### Chat Experience

- [Popover terminal](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/TerminalView.swift): `LilAgents/TerminalView.swift`
- [Visual themes](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/PopoverTheme.swift): `LilAgents/PopoverTheme.swift`

### Agent Sessions

- [Provider selection](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/AgentSession.swift): `LilAgents/AgentSession.swift`
- [Claude session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/ClaudeSession.swift): `LilAgents/ClaudeSession.swift`
- [Codex session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CodexSession.swift): `LilAgents/CodexSession.swift`
- [Copilot session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/CopilotSession.swift): `LilAgents/CopilotSession.swift`
- [Gemini session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/GeminiSession.swift): `LilAgents/GeminiSession.swift`
- [OpenCode session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/OpenCodeSession.swift): `LilAgents/OpenCodeSession.swift`
- [OpenClaw session](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/OpenClawSession.swift): `LilAgents/OpenClawSession.swift`

### Runtime Support

- [Shell environment](https://github.com/ryanstephen/lil-agents/blob/main/LilAgents/ShellEnvironment.swift): `LilAgents/ShellEnvironment.swift`

### Other components

- **Mac user**
- **Installed agent CLI**
- **OpenClaw gateway**

## Connections

- Mac user → App and menus: uses (evidence: `README.md`)
- App and menus → Character controller: starts (evidence: `LilAgents/LilAgentsApp.swift`)
- App and menus → Visual themes: configures (evidence: `LilAgents/LilAgentsApp.swift`)
- App and menus → Walking characters: uses (evidence: `LilAgents/LilAgentsApp.swift`)
- Character controller → Walking characters: sets up (evidence: `LilAgents/LilAgentsController.swift`)
- Character controller → Dock visibility: checks visibility (evidence: `LilAgents/LilAgentsController.swift`)
- Walking characters → Popover terminal: opens chat (evidence: `LilAgents/WalkerCharacter.swift`)
- Walking characters → Provider selection: creates session (evidence: `LilAgents/WalkerCharacter.swift`)
- Walking characters → Visual themes: styles popover (evidence: `LilAgents/WalkerCharacter.swift`)
- Character view → Walking characters: renders (evidence: `LilAgents/CharacterContentView.swift`)
- Popover terminal → Visual themes: uses (evidence: `LilAgents/TerminalView.swift`)
- Provider selection → Claude session: creates (evidence: `LilAgents/AgentSession.swift`)
- Provider selection → Codex session: creates (evidence: `LilAgents/AgentSession.swift`)
- Provider selection → Copilot session: creates (evidence: `LilAgents/AgentSession.swift`)
- Provider selection → Gemini session: creates (evidence: `LilAgents/AgentSession.swift`)
- Provider selection → OpenCode session: creates (evidence: `LilAgents/AgentSession.swift`)
- Provider selection → OpenClaw session: creates (evidence: `LilAgents/AgentSession.swift`)
- Claude session → Shell environment: resolves environment (evidence: `LilAgents/ClaudeSession.swift`)
- Codex session → Shell environment: resolves environment (evidence: `LilAgents/CodexSession.swift`)
- Copilot session → Shell environment: finds CLI (evidence: `LilAgents/CopilotSession.swift`)
- Gemini session → Shell environment: sets environment (evidence: `LilAgents/GeminiSession.swift`)
- OpenCode session → Shell environment: finds CLI (evidence: `LilAgents/OpenCodeSession.swift`)
- Claude session → Installed agent CLI: runs locally (evidence: `README.md`)
- Codex session → Installed agent CLI: runs locally (evidence: `README.md`)
- Copilot session → Installed agent CLI: runs locally (evidence: `README.md`)
- Gemini session → Installed agent CLI: runs locally (evidence: `README.md`)
- OpenCode session → Installed agent CLI: runs locally
- OpenClaw session → OpenClaw gateway: connects by WebSocket (evidence: `LilAgents/OpenClawSession.swift`)
