Project Pals

A Herdr layout that turns your coding agents into a crew of pals, in the spirit of Grok's bots but for any harness: Claude Code, Antigravity CLI (agy), Codex, Grok CLI, Gemini CLI, opencode, Hermes and more.

Website: project-pals.vercel.app

Linux only for now. The helpers run as a systemd user service, so macOS (and WSL or containers without a systemd user session) aren't supported yet. See docs/mac-support.md.

Each Herdr space is a pal (a project with a brain), and each of its tabs is a topic. Pals can work together in rooms. A head pal (Orchestrator unless you rename it) oversees the rest. The app is terminal-forward: you work in the pals' terminals, and around them are a sidebar, Home, an Inbox and small dialogs. On top of that you get:

• Pocket pets: every pal is a little LED critter whose pose shows what it's doing (working, needs you, done, PR open, merged, stuck, asleep). Pick its species, colour, what it wears and its eyes.
• Terminal-first: a topic is its agent's own terminal. Click a pal and you're in it. Split it right or down, pop it out into a window of its own, and answer the agent's questions right there.
• A sidebar built for scanning: the shown pal up top with its topics and quick actions, then every pal with its state in colour. Group pals into folders ("Personal", "Business"), pin them, and drag them into any order. Pin and reorder topics too.
• Tasks: give a pal a task (with screenshots attached); it lands on its desk as a card. Routines run on a schedule (pal routine).
• Missions and proposals: each pal can have a mission and a brain (decisions, a change log). When a pal proposes a change to its mission or to a project's AGENTS.md, you see it as a diff in a small dialog and accept or decline it.
• Sleep (keep topics, free RAM): a pal's agents stop while its topics' tabs and room seats stay; Wake (resume topics) starts them again where they were, resuming each topic's session. It never stops a pal that's working, asking you something, being typed to, or still running work of its own, and says why. Close pal (end its space) is the other way to rest one: its space closes and it waits under Hidden pals. (pal sleep / pal wake from the command line.)
• Hire pals and add topics on any harness, with a model per pal (cheap helpers on Haiku).
• Memory and shared skills, branch-per-topic review, and an approval gate.

The Desk

Everything sent to a pal (a message, a question, a task, the answer to something it asked) is a card with a status: queued, seen, working, done, held or needs you. You see when a pal actually got it and what it did with it, instead of guessing from its screen.

• Cards that wait on you show on Home and are counted on the Inbox. pal desk ls --all lists every desk: what has no pal yet, what's held and why, each pal and its topics.
• The header's Drop button (or Ctrl+Shift+D) drops a card from anywhere. Pick a pal or topic, or Auto: a quick, cheap model (Claude Haiku) picks one for you, and a card it isn't sure about waits for you to place it.
• Claude Code pals get cards mid-step or when idle without anything typed into their box, so a half-written prompt stays put. Antigravity CLI pals get them between steps through hooks; Codex pals check with a desk_check tool; other brains get them typed in when idle.
• Pals work their desk with pal desk (take, done "result", reply, block, pass). Cards are plain files in ~/.config/herdr-app/data/crew-desk.

Home

Click your head pal (or press Ctrl+Shift+H) for one page to come back to: everything that needs you, oldest first, under one line saying who's working and what shipped today, or "All caught up". While something needs you, Home shows one decision at a time: who's asking, the context, what each option does and the asker's recommendation. Pick with a click or 1-9 (Enter takes the recommendation). T opens your head pal's terminal, and "What happened today" opens a drawer with what finished, got installed or was linked.

Memory

Every awake topic is an agent holding memory, and Herdr keeps all of its terminals in one systemd unit. When memory ran out, systemd-oomd killed that unit, and with it every pal. So:

• One pal, one scope. With a systemd user session, each pal's agent starts in its own scope (systemd-run --user --scope, unit pal-<pal>-<topic>-….scope), so oomd takes the one hungry pal, not the crew. The agent keeps its pid and shell, so sleep and wake work as before. Only on this machine; without systemd, pals start as before. Off: "pal_scopes": false in data/crew-settings.json.
• Herdr's holder goes last. The installer adds ManagedOOMPreference=avoid for hc-hold-<id>.service (~/.config/systemd/user/hc-hold-.service.d/00-project-pals-oomd.conf), unless a drop-in of yours there already sets it (yours wins either way: ours sorts first). Skip it with --no-oomd-dropin; uninstall takes it out.
• Warned before it runs out. Under the floor (1.5 GB available or 10% of RAM, whichever is larger; "memory_floor_mb" to change it), pal hire, pal topic and pal wake say so, the app's hire and topic paths show a toast, and Home shows a quiet "Memory is low" row with Sleep idle pals.
• Idle topics can sleep by themselves. "sleep_idle_hours": 6 (off by default) has crewd put topics idle that long to sleep, with pal sleep's usual checks (never the head pal, never one that's mid-turn or waiting). pal sleep --idle --older 6 does the same once.
• pal ram lists what each awake topic holds and the machine's free memory.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗