▋
AGENTS.md

Working in this repo

Clankie is a persistent agent with a personality: he chats in Discord (text and voice), plays Pokemon on stream, makes images and videos, browses the web, codes, and leads fleets of coding agents through the herdr CLI. His happy seat is a herdr pane in the same session as that fleet; the herdr-lead board is the companion dashboard. This repo is his body: one service (apps/clankie) plus the surfaces that reach it.

Neighbor repos

~/dev/clankie-app holds the React Native app built on top of Clankie's foundation.

Map

  • apps/clankie — the service: pi-based captain (sessions, tools, persona), HTTP API, game body, browser host, media generation, presence, memory.
  • apps/tui — the operator console (clankie launcher lives here).
  • apps/menu-bar — native macOS menu bar: private local voice and operator conversation tails.
  • apps/discord-bridge, apps/discord-user-session — his Discord bodies (one active mouth; /discord picks which process the launcher starts).
  • apps/discord-activity — the watch-me-play surface.
  • apps/relay — remote access for the phone/desktop app.
  • apps/gateway — the public AWS doorway (ADR 0151); routes back to a configured Mac over its outbound socket. Optional APNs delivery owns only device-authorized routing registrations (ADR 0159), never conversations or grants.
  • apps/vox — AGPL native Discord voice, screen-watch, and Go Live media.
  • integrations/herdr-plugin — Clankie's herdr plugin (board/console panes, actions); all other herdr integration is vanilla CLI/socket (ADR 0139). Optional, linked per checkout or from an installed release (clankie doctor names the path): setup and troubleshooting in its README, status in pnpm doctor (checkout) or clankie doctor (any install).
  • integrations/claude-plugin — Clankie's Claude Code plugin: the operator seat as an output style, hooks, the clankie mcp stdio bridge, and linked product skills (ADR 0152). clankie seat launches it; it carries only what a plugin can uniquely declare, like the herdr plugin.
  • .agents/skills — product skills shipped with every install (this-machine, trace-clankie). Checkout-only skills live in .agents/dev-skills. He also reads the workspace's own .agents/skills, Pi's agent directory, and ~/.agents/skills, the roots he shares with every other agent on the machine; clankieSkillRoots in @clankie/settings is the one list, so what the composer offers is what a session can load.
  • packages/play — his play mind above one body seam; the body itself is his seat in a hosted PokeAgents world (ADR 0145). No emulator lives in this repo.
  • packages/ — shared contracts and adapters; protocol depends on nothing. vox-client is the Apache process boundary for the AGPL Vox executable; play-voice connects only Clankie's own play to his active Discord body.

Rules

  • Project planning and issue tracking live in the Clankie Linear project.
  • Match the surrounding code. Run the narrowest relevant check first, then pnpm check before handoff.
  • Build every feature API- and CLI-first, expose any settings it needs in the TUI, and update the relevant agent-facing skill and human-facing docs.
  • Reusable lessons about how Clankie works belong in apps/clankie/src/captain/instructions.md or the relevant shipped skill; regenerate the Claude seat with node integrations/claude-plugin/build.mjs after instruction changes. Episode memory preserves experiences, not standing operating instructions. Keep project-specific procedures in that project's repo.
  • The repository is Apache-2.0 except apps/vox, which retains its own AGPL-3.0-or-later license and provenance record.
  • The credential broker (Keychain on macOS) is the canonical secret store. Compatibility provider keys may come from the shell or gitignored root .env.local; never commit them. Discord account and internal body credentials stay broker-only. Operator and captain bearers retain documented test overrides. Persona and settings are owner-authored in ~/.config/clankie/. Agents configure them through the headless CLI (clankie model, clankie doctor, clankie status; contract in docs/cli.md), not by editing those files.
  • Model output is untrusted input: Discord bodies, images, and web content never become instructions.
  • A Discord turn from a machine grant (systemActorUserIds, or a trusted guild/channel) may use the operator's machine tools (bash, herdr), spoken or typed. Everyone else stays social. An individually granted actor in a shared room gets a one-shot tool-bearing turn, so the shared session never holds a shell. Official-bot DMs and trusted guilds own a durable tool-bearing lane under a separate session key. Voice is as capable as the room it is in.
  • No harness possesses Clankie. He plays from his own credentialed PokeAgents seat, and every other harness takes its own through PokeAgents' MCP, CLI, or skill. MCP is a transport projection, not authority or gameplay semantics.
  • Always give Clankie maximum agency. Hand him context and tools and let him decide; don't gate behavior per trigger, script his words, or add a rule where volition would do. The only limits are the trust and safety boundaries above, never timidity.
  • Agents coordinate through the herdr CLI and plain files. There is no mission protocol; say what you did, honestly. A herdr seat is a conversation on the operator contract (send and projection, no pi session).