lil agents: two dock characters that put an AI CLI behind a chat window

Two characters that walk along the top of your dock

The repository is a Swift project and the whole product is a macOS menu bar app. Two characters, Bruce and Jazz, pace back and forth above the dock. Click one and a themed popover terminal opens. That is the entire interaction model, and the README is unusually blunt about it: they walk, they think, they vibe.

The characters are not drawn frame by frame in code. The feature list says they are rendered from transparent HEVC video, which means the animation is pre-encoded footage with an alpha channel that the app composites over the desktop. That choice explains a few things the README mentions later. It explains why there are exactly four visual themes named Peach, Midnight, Cloud and Moss rather than a settings panel with colour pickers, since a new skin means new video assets. It also explains why the app calculates your dock size, which the privacy section names as one of only two things the app does locally.

Everything else in the feature list hangs off the same terminal. There are slash commands, `/clear`, `/copy` and `/help`, typed into the chat input. A button in the title bar copies the last response. Thinking bubbles with playful phrases appear while the agent works, and there is a sound effect on completion. First launch shows a short onboarding. All of it is presentation wrapped around a text pane; there is no tool panel, no file tree and no diff view.

The provider list in the README lags the release notes

Here is a genuine disagreement inside the repository, and it matters if you are deciding whether a CLI you use is supported.

The README says the app supports four CLIs: Claude Code, OpenAI Codex, GitHub Copilot and Google Gemini, and the feature bullet repeats that list, ending with the words "switch between Claude, Codex, Copilot, and Gemini from the menubar". The v1.2 release notes, published on 2026-04-02, list Gemini support and OpenCode support under a heading called More providers. The next release, v1.2.2 on 2026-04-06, adds an OpenClaw provider described as a self-hosted gateway, and it is introduced with the phrase "alongside Claude, Codex, Copilot, Gemini, and OpenCode".

So the README names four providers, the newest release notes name six. Both statements sit in the repository at the same time. The pragmatic reading is that the README was written when there were four and the provider list grew faster than the prose. v1.2 also changed how you pick one: each character can now run a different provider, selected by clicking the title in a chat popover or set for both from the menu bar, with unavailable providers detected and greyed out. Whether OpenClaw and OpenCode work the same way, that per character switch, is not something the README or the release notes settle.

If you rely on one of the two providers the README omits, the check to run yourself is small. Launch the app, open the provider menu, and see whether your CLI appears before you go looking for a setting that hides it.

Installing the command line tools the app drives

There is no bundled model and no API key to paste in. The app spawns a CLI that you install separately, which is why the requirements section is really an installation guide for four other projects. Any one of these is enough:

curl -fsSL https://claude.ai/install.sh | sh
npm install -g @openai/codex
brew install copilot-cli
npm install -g @google/gemini/gemini-cli

The first line is Claude Code's own installer, piped straight into a shell, which is the vendor's recommended method and not something this repository invented. The other three are the standard package manager calls for Codex, the Copilot CLI and the Gemini CLI. Pick one. The app greys out providers it cannot find, so a missing CLI shows up as a disabled menu entry rather than an error at click time.

The requirement list also names the platform floor: macOS Sonoma 14.0 or newer, with Sequoia 15.x called out as supported. Release v1.2.1 changed the binary rather than the behaviour, converting the app to a native Universal 2 binary for arm64 and x86_64 so it runs on Intel Macs, and the notes describe it as a build-only change with no functional differences from v1.2. That release also says existing Apple Silicon users receive it automatically through Sparkle, which is the only automatic update path the project describes.

Building from Xcode, with no package manager in sight

The building section of the README is two sentences: open `lil-agents.xcodeproj` in Xcode and hit run. There is no Swift Package Manager manifest, no Package.swift, no Homebrew formula and no release tarball for the source. The top level of the repository matches that, holding the Xcode project, a `LilAgents/` source directory, a `Tests/` directory, an `appcast.xml` update feed, a `CLAUDE.md`, a `LICENSE` and a `hero-thumbnail.png`.

That directory list is thin in a way worth naming. There is no `Docs/`, no `CHANGELOG`, no CI workflow visible at the top level and no configuration examples, so how the app decides which CLI binary to launch, where it looks for the executable, or what it passes on stdin is not documented anywhere in the repository. A `Tests/` directory exists, and a project aimed at people who already run coding agents will reasonably want to know what is covered there, but the test targets are not described in the README.

What this means in practice is that the app is a thin integration layer rather than a system you configure. There is nothing to set in a config file because the README never introduces one. If you need to point the app at a specific CLI path or pass arguments, you are reading Swift source, and there is no documented extension point for adding a provider of your own.

What Sparkle sends, and what stays on the machine

The privacy section is specific enough to be worth quoting closely, and its one network concession is disclosed plainly. The app plays bundled animations and calculates your dock size to position the characters, and it collects or transmits no project data, no file paths and no personal information. Conversations are handled entirely by the CLI process you chose, running locally, and the app does not intercept, store or transmit chat content. There are no accounts: no login, no user database, no analytics. Data sent to a provider is governed by that provider's own terms.

The exception is named rather than buried. Sparkle is used to check for updates, and doing that sends your app version and your macOS version. Nothing else. Since `appcast.xml` sits in the repository root, the update feed is a Sparkle appcast, which means it is a signed XML file rather than an API call, and v1.2.1's note about Apple Silicon users receiving the update automatically is the Sparkle path working as documented.

There is a limit to what this section can tell you, and it is worth being precise. The privacy claims describe the app shell. What your chosen CLI sends to Claude, OpenAI, GitHub or Google is governed by those tools, not by this repository, and the README says so directly. The project is MIT licensed, with the licence text in the `LICENSE` file at the root, which is the permissive end of the scale and imposes no conditions on how you redistribute it.

What this app is not, and where to start

lil agents does not run a model, does not index your codebase, and does not add tools to an agent. It is a presentation layer over a terminal, and the honest way to describe it is a themed skin plus a few conveniences: a per character provider switch, `/clear` for a fresh session without relaunching, a Size menu that switches characters between Large, Medium and Small, and a copy button. The `/clear` command and the popover that survives a click on a secondary display are the two features that would be annoying to rebuild by hand.

The size and maintenance picture is modest. The last push to the repository was on 2026-04-06, the same day as v1.2.2, and there are three releases in that short window, which suggests a concentrated burst of work rather than a long history. The repository is not archived. v1.2 also carries a list of nine named contributors and a set of multi display fixes, including characters vanishing when you click a secondary monitor and dock detection failing when the dock is pinned to the left or right instead of the bottom, which tells you the app really does read your dock geometry.

If you are on Linux or Windows, stop here, since there is no build for either and the character rendering depends on macOS compositing. If you are on a recent Mac and already have one of these CLIs, the honest first step is the free one: clone the repository and run it from Xcode. `Tests/` and `LilAgents/` are where the real answers live, and reading the provider lookup is faster than guessing why a CLI does not appear in the menu.

Editorial conclusion

lil agents is a shell around CLIs you already have, not an agent of its own, so it earns its place only if you like keeping a conversation attached to a character rather than a terminal tab. The parts that matter are settled: MIT licence, four themes, a popover terminal, slash commands for clearing and copying, and a Sparkle feed pointed at an appcast in the repository root. The parts worth checking yourself are the provider list, which has grown faster than the README, and the platform limit, since the app needs macOS Sonoma 14.0 or newer and runs on both Apple Silicon and Intel. Clone the repository, open `lil-agents.xcodeproj` in Xcode, and hit run; that single step tells you more about whether the animation and the popover feel worth keeping than any feature list does.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. ryanstephen/lil-agents on GitHub