ryanstephen/lil-agents: Animated AI Companions for Your macOS Dock

ryanstephen/lil-agents: Animated AI Companions for Your macOS Dock

Developers increasingly live between their IDE and terminal, context-switching between AI assistants that demand full-screen attention or browser tabs. The friction of invoking AI help—opening a new window, waiting for a web app to load, losing your visual context—adds up across hundreds of daily interactions. ryanstephen/lil-agents solves this with a deliberately different approach: tiny animated AI companions that live directly on your macOS dock, ready when you need them and unobtrusive when you don't.

This open-source Swift app, created by Ryan Stephen and distributed under the MIT License, has accumulated 1,428 GitHub stars and 280 forks as of its last commit on April 6, 2026. It represents a niche but growing category of local-first, UI-integrated AI tooling that prioritizes developer workflow ergonomics over feature breadth.

What is ryanstephen/lil-agents?

ryanstephen/lil-agents is a macOS application written in Swift that renders animated characters—Bruce and Jazz—above your dock. These characters walk back and forth, display thinking bubbles while processing, and open themed popover terminals when clicked. The app functions as a lightweight frontend for multiple AI CLI tools rather than implementing its own language model or API client.

The project's 1,428 stars and active fork community suggest genuine developer interest in ambient AI interfaces. Its MIT License permits commercial use, modification, and redistribution. The codebase is open and buildable from an Xcode project, which matters for developers who audit their tooling or need to customize behavior.

What distinguishes ryanstephen/lil-agents from generic "AI wrapper" apps is its specific architectural choice: it does not handle AI inference itself. Instead, it launches and manages external CLI processes—Claude Code, OpenAI Codex, GitHub Copilot CLI, and Google Gemini CLI—displaying their output in a styled terminal overlay. This design keeps the app small, keeps your API credentials and conversations within your existing CLI tooling, and avoids duplicating functionality better handled by specialized clients.

The animated characters serve a genuine UX purpose beyond novelty. They provide ambient status indication (walking when idle, thinking bubbles during processing) and reduce the cognitive load of checking whether your last prompt is still running. For developers who find traditional notification systems too interruptive, this peripheral awareness model aligns with research on calm technology.

Key Features

Animated Character System: Bruce and Jazz are rendered from transparent HEVC video, not sprite sheets or CSS animations. This technical choice enables smooth, high-quality transparency against the variable macOS desktop background without the compositing artifacts common in GIF or PNG-based approaches. The characters automatically position themselves based on your dock size.

Multi-Provider AI Support: The app supports switching between four CLI tools from the menubar: Claude Code (Anthropic), OpenAI Codex, GitHub Copilot CLI, and Google Gemini CLI. This is not a simple API key swap—the app launches the actual CLI binaries and pipes their I/O through its terminal interface. You use the same CLIs you would in Terminal.app or iTerm2, just with faster visual access.

Themed Terminal Interface: Four visual themes—Peach, Midnight, Cloud, and Moss—style the popover terminal. The terminal supports slash commands (/clear, /copy, /help) and includes a copy-last-response button in the title bar for quickly grabbing AI output.

Thinking Bubbles & Sound Effects: While the underlying CLI processes your request, the character displays playful thinking phrases. Sound effects on completion provide optional audio feedback for long-running operations.

Auto-Updates via Sparkle: The app uses the established Sparkle framework for update distribution, checking version compatibility against your installed macOS version.

Universal Binary: Runs natively on both Apple Silicon and Intel Macs without Rosetta translation, ensuring optimal performance regardless of hardware generation.

Privacy-First Architecture: No accounts, no analytics, no data collection. The app calculates dock dimensions for positioning and plays bundled animations—nothing else leaves your machine. [INTERNAL_LINK: macos-privacy-tools]

Use Cases

Ambient Coding Companion: Keep Claude Code or Codex accessible without a dedicated terminal window. Click Jazz when you need to refactor a function, then continue reading documentation while the thinking bubble indicates processing. The popover disappears when you click elsewhere, preserving screen real estate.

Multi-Provider Workflow Testing: Switch between Claude and Gemini from the menubar to compare responses on the same prompt. This is particularly useful when evaluating model performance for specific code generation tasks without managing multiple terminal sessions or browser tabs.

Minimalist Setup for New Team Members: The onboarding flow and single-app installation reduce friction for developers new to AI-assisted coding. Install lil-agents, ensure one supported CLI is present, and you have a consistent interface regardless of which provider your organization standardizes on.

Presentation & Screen Sharing: The themed terminal and character animations create a more visually engaging demo environment than raw terminal output. The transparent HEVC rendering ensures the interface looks polished against varied desktop backgrounds during live coding sessions or tutorials.

Accessibility-Friendly Quick Access: For users who find menubar icons faster to target than dock icons or Spotlight search, the persistent dock-adjacent positioning provides a large, predictable hit target. The sound effects on completion benefit developers who work with audio feedback enabled.

Installation & Setup

System Requirements

• macOS Sonoma (14.0) or later, including Sequoia (15.x)
• Apple Silicon or Intel Mac (Universal binary)
• At least one supported AI CLI installed

Install a Supported AI CLI

Choose and install at least one of the following:

# Claude Code (Anthropic)
curl -fsSL https://claude.ai/install.sh | sh

# OpenAI Codex
npm install -g @openai/codex

# GitHub Copilot CLI
brew install copilot-cli

# Google Gemini CLI
npm install -g @google/gemini-cli

Each command installs the respective CLI to your PATH. Verify installation by running the CLI name in Terminal—claude, codex, copilot, or gemini—before proceeding.

Install lil-agents

Download the latest release from https://lilagents.xyz. The website provides a signed macOS application bundle. After download:

1. Open the .dmg or extracted .app (exact distribution format depends on release)
2. Drag lil agents to Applications
3. Launch from Applications or Spotlight
4. Complete the first-run onboarding

Build from Source

For developers who prefer to compile:

# Clone the repository
git clone https://github.com/ryanstephen/lil-agents.git
cd lil-agents

# Open in Xcode
open lil-agents.xcodeproj

Click Run in Xcode. The project builds without external dependencies beyond standard macOS frameworks and Sparkle.

Initial Configuration

On first launch, the app detects installed CLIs and prompts you to select a default. Switch providers anytime from the menubar icon. The character appears above your dock automatically—no manual positioning required.

Real Code Examples

The README does not contain traditional "code examples" in the sense of API calls or configuration files. Instead, the tool's interface is the code you write within it. Here are the documented interaction patterns:

Slash Commands in Chat Input

/clear    # Clear the terminal conversation history
/copy     # Copy the last AI response to clipboard
/help     # Display available commands and shortcuts

These commands execute within lil-agents' terminal overlay, not in your shell. They control the presentation layer while the underlying CLI handles actual AI communication. Use /clear when context window limits approach, /copy to grab a code block without manual selection, and /help when you forget the available shortcuts.

CLI Installation Commands (Reproduced from README)

# Claude Code - official install script
curl -fsSL https://claude.ai/install.sh | sh

# OpenAI Codex - global npm install
npm install -g @openai/codex

# GitHub Copilot - Homebrew package
brew install copilot-cli

# Google Gemini - global npm install
npm install -g @google/gemini-cli

These are not "examples" in a tutorial sense but prerequisites the app requires. The curl | sh pattern for Claude Code follows common CLI distribution practices; verify the script contents if your security policy requires it. The npm global installs assume a functional Node.js environment; use a version manager like nvm if you avoid global packages.

Building from Source

# Standard Xcode project workflow
git clone https://github.com/ryanstephen/lil-agents.git
cd lil-agents
open lil-agents.xcodeproj
# Press Cmd+R or click Run in Xcode

No Package.swift, CocoaPods, or Carthage dependencies are mentioned. This simplicity reduces build friction but also means you manage Sparkle and any other frameworks as Git-tracked binaries or Xcode-integrated packages.

The README's brevity here reflects the app's focused scope: it does not expose a programmable API or configuration file format. What you see—animated characters, themed terminal, menubar switching—is the complete feature surface.

Advanced Usage & Best Practices

CLI Version Management: Since lil-agents launches your installed CLIs directly, updating the underlying tool (e.g., npm update -g @openai/codex) immediately benefits the app. No separate update channel for AI functionality. Conversely, breaking CLI changes require manual verification.

Theme Selection by Context: Match themes to your working environment. Midnight reduces eye strain in dark rooms; Peach or Cloud maintain visibility against dark desktop wallpapers; Moss provides low-saturation calm for extended sessions.

Dock Positioning Awareness: The app calculates dock size for character placement. If you frequently change dock magnification or position (left/bottom/right screen edge), expect occasional repositioning delays. The HEVC video rendering is efficient but not free—battery-conscious users on Intel Macs may notice higher energy use than static menubar alternatives.

Multiple CLI Coexistence: Install multiple supported CLIs to enable rapid provider comparison. The menubar switch takes effect for new conversations; ongoing sessions complete in their original CLI process. This is a feature, not a bug—it prevents interrupting long-running code generation.

Privacy Verification: The app's claims of local-only operation are verifiable. Since it's open source, inspect lil-agents.xcodeproj source for network calls beyond Sparkle update checks. No entitlements for network access should appear outside the Sparkle framework.

Comparison with Alternatives

Raycast AI offers deeper system integration and extensibility but requires a subscription for full AI features and lacks the ambient, always-visible character model. Warp provides superior terminal functionality with AI inline but demands a full terminal window replacement, not quick popover access. Fig (now Amazon CodeWhisperer) targets IDE autocomplete rather than conversational AI interaction.

ryanstephen/lil-agents trades feature breadth for workflow specificity: it is the right tool when you want immediate, visually pleasant access to existing CLI AI tools without changing your terminal or learning a new command palette. The trade-off is macOS exclusivity and dependence on separately maintained CLIs.

FAQ

Does lil-agents work on Windows or Linux? No. macOS Sonoma (14.0+) is required. The Swift codebase and dock-integration APIs are macOS-specific.

Do I need API keys for all four AI providers? No. Install and configure only the CLI(s) you want to use. The app detects available options at launch.

Is my conversation data sent to lil-agents servers? No servers exist. Conversations flow through your chosen CLI directly to that provider's API. The app does not intercept or store content.

Why HEVC video instead of simpler animation formats? Transparent HEVC enables efficient, high-quality alpha channel compositing over arbitrary desktop backgrounds without the file size of frame sequences.

Can I add custom characters or themes? The README does not document customization APIs. Since the project is open source, modification requires editing the Xcode project and rebuilding.

How do I uninstall? Remove the app from Applications. Uninstall associated CLIs separately via their respective package managers.

Is this actively maintained? The last commit was April 6, 2026. The Sparkle auto-update mechanism provides the primary channel for ongoing maintenance verification.

Conclusion

ryanstephen/lil-agents occupies a deliberate niche: developers who already use AI CLIs and want faster, more pleasant access without workflow disruption. It does not replace your terminal, IDE, or browser-based AI interfaces. It augments them with ambient availability and visual personality that reduces activation energy for quick queries.

The tool suits macOS developers invested in Claude Code, Codex, Copilot CLI, or Gemini CLI who value local-first operation and open-source verifiability. It is less appropriate for users needing deep terminal features, cross-platform consistency, or AI access without CLI setup.

With 1,428 stars and growing community contributions, the project demonstrates that even narrowly scoped developer tools can attract sustained interest when they solve real interaction friction. Download from lilagents.xyz or explore the source at https://github.com/ryanstephen/lil-agents.