Open Source Project of the Day (Part 63): lil agents - Tiny AI Companions Living Above Your macOS Dock

Introduction

"Tiny AI companions that live on your macOS dock."

This is Part 63 of the "Open Source Project of the Day" series. Today we explore lil agents (GitHub).

Most developers put AI coding assistants inside an IDE (Cursor / VSCode extensions) or inside a terminal (Claude Code / Codex / Gemini CLI). But sometimes you just want a “one-click ask” experience — without switching windows, opening a new tab, or remembering the right command. lil agents keeps it simple: two tiny characters (Bruce and Jazz) walk back and forth above your macOS Dock. Click one, and you get a themed popover AI terminal. From the menubar, you can switch between multiple AI CLIs — Claude, Codex, Copilot, and Gemini.

It’s not trying to replace your existing CLI workflows. It’s making them feel more “ambient” and instantly accessible.

What You'll Learn

• lil agents' positioning: making AI CLI access lightweight via a Dock-level popover UI
• Supported CLIs: Claude Code, OpenAI Codex, GitHub Copilot CLI, Google Gemini CLI — and how switching works
• UX details: themes, slash commands, copy-last-response, thinking bubbles, sound effects, onboarding
• Privacy boundaries: local app behavior vs. provider CLIs, and what update checks send
• How to build it locally with Xcode

Prerequisites

• You use at least one AI CLI on macOS (Claude Code / Codex / Copilot / Gemini)
• Basic terminal familiarity (npm / brew / curl scripts)
• Xcode basics if you want to build from source (optional)

Project Background

Project Overview

lil agents is a macOS app that renders two tiny companions above your Dock and provides a popover “AI terminal” when you click them. It doesn’t ship its own model backend. Instead, it treats your locally-installed AI CLIs (Claude Code, Codex, Copilot CLI, Gemini CLI) as the capability layer, and focuses on delivering a more playful and low-friction desktop interaction.

Author/Team

• Author: Ryan Stephen (repository maintainer)

Project Stats

• ⭐ GitHub Stars: 909
• 🍴 Forks: 0 (as shown on the GitHub page at time of writing)
• 📦 Releases: See GitHub Releases for version history
• 📄 License: MIT
• 🌐 Website / download: https://lilagents.xyz

Main Features

Core Purpose

Turn “terminal-first AI CLIs” into a desktop-native, one-click experience:

• Always there: animated companions above the Dock
• Click to chat: a themed popover terminal
• Provider switching: switch Claude / Codex / Copilot / Gemini from the menubar
• Polish: slash commands, copy button, thinking bubbles, completion sounds, onboarding

Use Cases

1. Quick questions without context switching

   • Ask a short question while coding, without bringing a full chat window to the foreground.

2. Compare outputs across CLIs

   • Run the same prompt through Claude Code vs. Codex vs. Gemini and compare tone/results.

3. Make work feel “visible”

   • Thinking bubbles and completion sounds provide extra feedback while you wait.

4. Minimal desktop workflow

   • If you don’t want AI inside your IDE and you don’t want terminal windows everywhere, a popover is a sweet spot.

Quick Start

Install at least one supported CLI (commands below are from the project README):

# Claude Code
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

Then download the macOS app from https://lilagents.xyz and run it.

Key Features

1. Animated companions

   • Characters rendered from transparent HEVC video.

2. Popover AI terminal

   • Click a character to open a themed terminal popover.

3. Menubar provider switch

   • Switch between Claude, Codex, Copilot, and Gemini.

4. Visual themes

   • Peach, Midnight, Cloud, Moss.

5. Slash commands

   • /clear, /copy, /help in the chat input.

6. Copy last response

   • A dedicated button in the title bar.

7. Feedback and delight

   • Thinking bubbles and completion sound effects, plus a friendly onboarding flow.

8. Auto-updates

   • Uses Sparkle for update checks and installations.

Advantages

Detailed Project Analysis

Interaction design: Dock as the “ambient AI entry point”

The core idea isn’t a new agent framework. It’s placing AI access where macOS users naturally glance:

• Dock is frequently visible
• Characters provide subtle presence and “activity”
• A popover keeps your main workspace intact

Dependency strategy: CLIs as the capability layer

lil agents is “provider-agnostic” at the UI layer by delegating actual conversations to your selected CLI process:

• Claude Code
• OpenAI Codex
• GitHub Copilot CLI
• Google Gemini CLI

This keeps the app lightweight, while also making your provider terms, auth flows, and data handling primarily a CLI/provider concern.

Privacy boundaries

The README states:

• The app runs locally and does not collect or transmit project data, file paths, personal info, or chat content
• Conversations are handled by the CLI you choose, and any data sent follows that provider’s policies
• Sparkle update checks send app version and macOS version (and nothing else)

Building from source

Open lil-agents.xcodeproj in Xcode and hit Run.

Project Links & Resources

Official Resources

• 🌟 GitHub: https://github.com/ryanstephen/lil-agents
• 🌐 Website / download: https://lilagents.xyz
• 🐛 Issue Tracker: https://github.com/ryanstephen/lil-agents/issues

Related Resources

• Claude Code: https://claude.ai/download
• OpenAI Codex: https://github.com/openai/codex
• GitHub Copilot CLI: https://github.com/github/copilot-cli
• Google Gemini CLI: https://github.com/google-gemini/gemini-cli

Who It’s For

• macOS developers who already use AI CLIs and want a lightweight one-click UI
• People who like desktop widgets, presence, and playful feedback loops
• Power users who compare multiple AI CLIs/providers frequently

Visit my personal homepage to find more useful knowledge and interesting products