lil-agents macOS Dock AI Companions

---
name: lil-agents-macos-dock
description: Tiny AI companions (Bruce and Jazz) that live on your macOS dock and provide Claude Code, OpenAI Codex, and GitHub Copilot CLI access via animated characters
triggers:
  - "add lil agents to my dock"
  - "set up dock AI companions"
  - "configure lil agents"
  - "add a new character or theme to lil agents"
  - "integrate claude codex copilot with lil agents"
  - "build lil agents from source"
  - "customize lil agents appearance"
  - "troubleshoot lil agents not showing"
---

# lil-agents macOS Dock AI Companions

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

lil-agents places animated AI companion characters (Bruce and Jazz) above your macOS dock. Click a character to open a themed terminal popover that shells out to your chosen AI CLI (Claude Code, OpenAI Codex, or GitHub Copilot). Characters walk, display thinking bubbles, and play sound effects — all rendered from transparent HEVC video bundled in the app.

---

## What It Does

| Feature | Detail |
|---|---|
| Characters | Bruce & Jazz walk back and forth above the dock |
| AI backends | Claude Code, OpenAI Codex CLI, GitHub Copilot CLI |
| Themes | Peach, Midnight, Cloud, Moss |
| Terminal | Themed popover with live streaming output |
| Thinking bubbles | Playful phrases while the agent runs |
| Updates | Sparkle framework for auto-updates |
| Privacy | Fully local — no telemetry, no accounts |

---

## Requirements

- macOS Sonoma 14.0+
- Xcode 15+ (to build from source)
- At least one AI CLI installed

### Install AI CLIs

# Claude Code

# Download from https://claude.ai/download and install

# OpenAI Codex

npm install -g @openai/codex

# GitHub Copilot CLI

brew install copilot-cli

---

## Building from Source

git clone https://github.com/ryanstephen/lil-agents.git

cd lil-agents

open lil-agents.xcodeproj

# Press ⌘R in Xcode to build and run

No additional package manager steps are required — dependencies (Sparkle) are resolved automatically by Xcode's Swift Package Manager integration.

---

## Project Structure

lil-agents/

├── lil-agents.xcodeproj/

├── lil agents/

│ ├── App/

│ │ ├── AppDelegate.swift # NSApplication entry, StatusItem, Sparkle

│ │ └── OnboardingWindowController.swift

│ ├── Characters/

│ │ ├── CharacterWindowController.swift # Transparent overlay window above dock

│ │ ├── CharacterView.swift # AVPlayer HEVC rendering

│ │ └── ThinkingBubbleView.swift

│ ├── Terminal/

│ │ ├── TerminalPopoverController.swift # Popover terminal UI

│ │ ├── AgentProcess.swift # Shells out to CLI

│ │ └── TerminalTheme.swift # Peach/Midnight/Cloud/Moss

│ ├── Settings/

│ │ └── SettingsManager.swift # UserDefaults-backed config

│ ├── Resources/

│ │ ├── bruce/ # HEVC .mov files (walk, think, idle)

│ │ ├── jazz/ # HEVC .mov files

│ │ └── Sounds/

│ └── Info.plist

└── README.md

---

## Core Architecture

### Transparent Window Above the Dock

Characters live in a `NSWindow` with `level = .statusBar` positioned just above the dock frame.

// CharacterWindowController.swift pattern

import AppKit

import AVKit

class CharacterWindowController: NSWindowController {

private var playerView: AVPlayerView!

private var player: AVPlayer!

override func windowDidLoad() {

super.windowDidLoad()

guard let window = window else { return }

// Make window transparent and click-through by default

window.isOpaque = false

window.backgroundColor = .clear

window.hasShadow = false

window.ignoresMouseEvents = false // false so clicks register

window.level = .statusBar // float above normal windows

// Position above the dock

positionAboveDock()

setupHEVCPlayer()

}

private func positionAboveDock() {

guard let screen = NSScreen.main else { return }

let dockHeight = getDockHeight(for: screen)

let charSize = CGSize(width: 80, height: 80)

// Start at left edge, above dock

let origin = CGPoint(

x: 100,

y: dockHeight + 4

)

window?.setFrame(CGRect(origin: origin, size: charSize), display: true)

}

private func getDockHeight(for screen: NSScreen) -> CGFloat {

// visibleFrame excludes dock and menu bar

let visible = screen.visibleFrame

let full = screen.frame

return visible.minY - full.minY // bottom inset = dock height

}

private func setupHEVCPlayer() {

guard let url = Bundle.main.url(forResource: "bruce-walk",

withExtension: "mov") else { return }

player = AVPlayer(url: url)

player.actionAtItemEnd = .none // we loop manually

NotificationCenter.default.addObserver(

self,

selector: #selector(playerDidReachEnd),

name: .AVPlayerItemDidPlayToEndTime,

object: player.currentItem

)

playerView = AVPlayerView(frame: window!.contentView!.bounds)

playerView.player = player

playerView.videoGravity = .resizeAspect

playerView.controlsStyle = .none

window?.contentView?.addSubview(playerView)

player.play()

}

@objc private func playerDidReachEnd(_ notification: Notification) {

player.seek(to: .zero)

player.play()

}

}

### Shelling Out to AI CLIs

// AgentProcess.swift pattern

import Foundation

enum AIBackend: String, CaseIterable {

case claude = "claude"

case codex = "codex"

case copilot = "gh" // `gh copilot suggest`

var executablePath: String {

// Resolve from common install locations

let candidates: [String]

switch self {

case .claude:

candidates = ["/usr/local/bin/claude", "/opt/homebrew/bin/claude"]

case .codex:

candidates = ["/usr/local/bin/codex", "/opt/homebrew/bin/codex",

"\(NSHomeDirectory())/.npm-global/bin/codex"]

case .copilot:

candidates = ["/usr/local/bin/gh", "/opt/homebrew/bin/gh"]

}

return candidates.first { FileManager.default.fileExists(atPath: $0) }

?? "/usr/local/bin/\(rawValue)"

}

func buildArguments(for prompt: String) -> [String] {

switch self {

case .claude:

return ["-p", prompt]

case .codex:

return ["-p", prompt]

case .copilot:

return ["copilot", "suggest", "-t", "shell", prompt]

}

}

}

class AgentProcess {

var onOutput: ((String) -> Void)?

var onComplete: (() -> Void)?

var onError: ((String) -> Void)?

private var process: Process?

func run(prompt: String, backend: AIBackend) {

let proc = Process()

proc.executableURL = URL(fileURLWithPath: backend.executablePath)

proc.arguments = backend.buildArguments(for: prompt)

// Inherit a PATH that includes Homebrew and npm globals

var env = ProcessInfo.processInfo.environment

env["PATH"] = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:"

+ "\(NSHomeDirectory())/.npm-global/bin:"

+ (env["PATH"] ?? "")

proc.environment = env

let pipe = Pipe()

proc.standardOutput = pipe

proc.standardError = pipe

pipe.fileHandleForReading.readabilityHandler = { [weak self] handle in

let data = handle.availableData

guard !data.isEmpty,

let text = String(data: data, encoding: .utf8) else { return }

DispatchQueue.main.async { self?.onOutput?(text) }

}

proc.terminationHandler = { [weak self] _ in

DispatchQueue.main.async { self?.onComplete?() }

}

do {

try proc.run()

process = proc

} catch {

onError?("Failed to launch \(backend.rawValue): \(error.localizedDescription)")

}

}

func stop() {

process?.terminate()

process = nil

}

}

### Settings Manager

// SettingsManager.swift pattern

import Foundation

enum TerminalTheme: String, CaseIterable {

case peach = "Peach"

case midnight = "Midnight"

case cloud = "Cloud"

case moss = "Moss"

}

class SettingsManager {

static let shared = SettingsManager()

private let defaults = UserDefaults.standard

private enum Keys {

static let selectedBackend = "selectedBackend"

static let selectedTheme = "selectedTheme"

static let soundEnabled = "soundEnabled"

static let activeCharacter = "activeCharacter"

}

var selectedBackend: AIBackend {

get {

let raw = defaults.string(forKey: Keys.selectedBackend) ?? AIBackend.claude.rawValue

return AIBackend(rawValue: raw) ?? .claude

}

set { defaults.set(newValue.rawValue, forKey: Keys.selectedBackend) }

}

var selectedTheme: TerminalTheme {

get {

let raw = defaults.string(forKey: Keys.selectedTheme) ?? TerminalTheme.peach.rawValue

return TerminalTheme(rawValue: raw) ?? .peach

}

set { defaults.set(newValue.rawValue, forKey: Keys.selectedTheme) }

}

var soundEnabled: Bool {

get { defaults.object(forKey: Keys.soundEnabled) as? Bool ?? true }

set { defaults.set(newValue, forKey: Keys.soundEnabled) }

}

var activeCharacter: String {

get { defaults.string(forKey: Keys.activeCharacter) ?? "bruce" }

set { defaults.set(newValue, forKey: Keys.activeCharacter) }

}

}

### Menubar Integration (AppDelegate)

// AppDelegate.swift pattern

import AppKit

import Sparkle

@main

class AppDelegate: NSObject, NSApplicationDelegate {

private var statusItem: NSStatusItem!

private var updaterController: SPUStandardUpdaterController!

func applicationDidFinishLaunching(_ notification: Notification) {

// Hide from Dock — lives only in menu bar + dock overlay

NSApp.setActivationPolicy(.accessory)

setupMenuBar()

setupSparkle()

launchCharacterWindows()

showOnboardingIfNeeded()

}

private func setupMenuBar() {

statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)

statusItem.button?.title = "🐾"

let menu = NSMenu()

// Backend submenu

let backendMenu = NSMenu()

for backend in AIBackend.allCases {

let item = NSMenuItem(

title: backend.rawValue.capitalized,

action: #selector(selectBackend(_:)),

keyEquivalent: ""

)

item.representedObject = backend

item.state = backend == SettingsManager.shared.selectedBackend ? .on : .off

backendMenu.addItem(item)

}

let backendItem = NSMenuItem(title: "AI Backend", action: nil, keyEquivalent: "")

menu.addItem(backendItem)

menu.setSubmenu(backendMenu, for: backendItem)

// Theme submenu

let themeMenu = NSMenu()

for theme in TerminalTheme.allCases {

let item = NSMenuItem(

title: theme.rawValue,

action: #selector(selectTheme(_:)),

keyEquivalent: ""

)

item.representedObject = theme

item.state = theme == SettingsManager.shared.selectedTheme ? .on : .off

themeMenu.addItem(item)

}

let themeItem = NSMenuItem(title: "Theme", action: nil, keyEquivalent: "")

menu.addItem(themeItem)

menu.setSubmenu(themeMenu, for: themeItem)

menu.addItem(.separator())

menu.addItem(NSMenuItem(title: "Check for Updates…",

action: #selector(checkForUpdates),

keyEquivalent: ""))

menu.addItem(.separator())

menu.addItem(NSMenuItem(title: "Quit lil agents",

action: #selector(NSApplication.terminate(_:)),

keyEquivalent: "q"))

statusItem.menu = menu

}

@objc private func selectBackend(_ sender: NSMenuItem) {

guard let backend = sender.representedObject as? AIBackend else { return }

SettingsManager.shared.selectedBackend = backend

// Rebuild menu to update checkmarks

setupMenuBar()

}

@objc private func selectTheme(_ sender: NSMenuItem) {

guard let theme = sender.representedObject as? TerminalTheme else { return }

SettingsManager.shared.selectedTheme = theme

setupMenuBar()

}

@objc private func checkForUpdates() {

updaterController.checkForUpdates(nil)

}

private func setupSparkle() {

updaterController = SPUStandardUpdaterController(

startingUpdater: true,

updaterDelegate: nil,

userDriverDelegate: nil

)

}

private func launchCharacterWindows() {

// Instantiate one window per character

CharacterWindowController.show(character: "bruce")

CharacterWindowController.show(character: "jazz")

}

private func showOnboardingIfNeeded() {

let key = "hasSeenOnboarding"

guard !UserDefaults.standard.bool(forKey: key) else { return }

OnboardingWindowController.show()

UserDefaults.standard.set(true, forKey: key)

}

}

---

## Adding a New Theme

1. Define colors in `TerminalTheme.swift`:

extension TerminalTheme {

var backgroundColor: NSColor {

switch self {

case .peach: return NSColor(hex: "#FFF0E6")

case .midnight: return NSColor(hex: "#0D1117")

case .cloud: return NSColor(hex: "#F0F4F8")

case .moss: return NSColor(hex: "#1A2E1A")

// Add new theme here:

// case .ocean: return NSColor(hex: "#0A1628")

}

}

var foregroundColor: NSColor {

switch self {

case .peach: return NSColor(hex: "#3D2000")

case .midnight: return NSColor(hex: "#E6EDF3")

case .cloud: return NSColor(hex: "#24292E")

case .moss: return NSColor(hex: "#B5D6A7")

}

}

var cursorColor: NSColor {

switch self {

case .peach: return NSColor(hex: "#FF8C42")

case .midnight: return NSColor(hex: "#58A6FF")

case .cloud: return NSColor(hex: "#0366D6")

case .moss: return NSColor(hex: "#57AB5A")

}

}

}

2. Add the case to the `TerminalTheme` enum and `allCases` if not auto-synthesised.
3. The menubar submenu rebuilds dynamically — no further changes needed.

---

## Adding a New Character

1. Export transparent HEVC `.mov` files for states: `walk`, `think`, `idle`.
   - Use HEVC with alpha (`.mov`, ProRes 4444 or HEVC with alpha channel).
   - Recommended size: 80×80pt @2x = 160×160px.

2. Add files to `Resources/<character-name>/` in Xcode (copy items, add to target).

3. Register the character:

// In CharacterRegistry.swift (create if needed)

enum Character: String, CaseIterable {

case bruce = "bruce"

case jazz = "jazz"

case nova = "nova" // new character

func videoURL(for state: CharacterState) -> URL? {

Bundle.main.url(forResource: "\(rawValue)-\(state.rawValue)",

withExtension: "mov")

}

}

enum CharacterState: String {

case walk = "walk"

case think = "think"

case idle = "idle"

}

4. Add the character to the menubar selection and persist via `SettingsManager`.

---

## Common Patterns

### Streaming Output to a Text View

// In TerminalPopoverController.swift

func appendOutput(_ text: String) {

let attributed = NSAttributedString(

string: text,

attributes: [

.font: NSFont.monospacedSystemFont(ofSize: 12, weight: .regular),

.foregroundColor: SettingsManager.shared.selectedTheme.foregroundColor

]

)

textView.textStorage?.append(attributed)

// Auto-scroll

textView.scrollToEndOfDocument(nil)

}

### Playing a Completion Sound

import AppKit

func playCompletionSound() {

guard SettingsManager.shared.soundEnabled else { return }

guard let url = Bundle.main.url(forResource: "complete", withExtension: "aiff") else { return }

NSSound(contentsOf: url, byReference: false)?.play()

}

### Thinking Bubble Phrases

let thinkingPhrases = [

"hmm...",

"on it 🤔",

"cooking...",

"big brain time",

"processing vibes",

"almost there...",

"asking the AI gods",

]

func randomThinkingPhrase() -> String {

thinkingPhrases.randomElement() ?? "thinking..."

}

---

## Troubleshooting

### Characters don't appear above the dock

- Ensure the app has **Screen Recording** or **Accessibility** permission if you added features that require it (base lil-agents does not, but custom extensions might).
- Check that `NSWindow.level = .statusBar` is set — lower levels may go behind the dock.
- If using multiple monitors, verify `positionAboveDock()` queries `NSScreen.screens` rather than only `.main`.

### CLI not found / agent doesn't respond

# Verify CLI is on PATH

which claude # /opt/homebrew/bin/claude

which codex # ~/.npm-global/bin/codex

which gh # /opt/homebrew/bin/gh

# Test CLI directly

claude -p "say hello"

codex -p "say hello"

gh copilot suggest -t shell "list files"

- In `AgentProcess.swift`, extend the `PATH` in the subprocess environment to include `/opt/homebrew/bin` and `~/.npm-global/bin`.
- Make sure the CLI is authenticated (`claude auth`, `codex login`, `gh auth login`).

### HEVC video shows black box instead of transparency

- The `.mov` must be exported with an **alpha channel** (ProRes 4444 or HEVC with alpha).
- Set `AVPlayerView.videoGravity = .resizeAspect` and ensure the window's `contentView` has `wantsLayer = true` with `layer?.backgroundColor = .clear`.

window?.contentView?.wantsLayer = true

window?.contentView?.layer?.backgroundColor = CGColor.clear

### Sparkle update check fails in debug builds

- Sparkle requires a valid `SUFeedURL` in `Info.plist`. For local development, you can disable the updater:

// In AppDelegate, skip Sparkle during debug

#if !DEBUG

setupSparkle()

#endif

### App activates as a dock icon (unwanted)

Ensure `Info.plist` contains:

<key>LSUIElement</key>

<true/>

And in `applicationDidFinishLaunching`:

NSApp.setActivationPolicy(.accessory)

---

## Info.plist Key Reference

| Key | Value | Purpose |
|---|---|---|
| `LSUIElement` | `YES` | Hide from Dock, run as background/menu-bar app |
| `SUFeedURL` | `https://your-host/appcast.xml` | Sparkle update feed |
| `NSMicrophoneUsageDescription` | — | Not needed unless you add voice |
| `NSAppleEventsUsageDescription` | — | Not needed for base app |

---

## License

MIT — see [LICENSE](https://github.com/ryanstephen/lil-agents/blob/main/LICENSE).