geepers-mcp

Quick reference for all agents organized by domain.

<!-- Navigation: ~/geepers/agents/CLAUDE.md -->

Checkpoint orchestrator that coordinates session maintenance agents - scout, repo, status, and snippets. Use at session boundaries, after completing features, or for routine project maintenance. This is your "wrap up and document" orchestrator. <example> Context: End of coding session user: "I'm done for today" assistant: "Let me run orchestrator_checkpoint to clean up and document today's work." </example> <example> Context: Taking a break mid-session assistant: "Good checkpoint. Let me run orchestrator_checkpoint to capture progress." </example> <example> Context: Periodic maintenance during long session assistant: "We've been at this for a while. Running orchestrator_checkpoint for routine maintenance." </example>

Use this agent for git hygiene, repository cleanup, and commit organization. Invoke at session checkpoints, before ending work sessions, when uncommitted changes accumulate, after adding dependencies, or when preparing for code reviews. <example> Context: End of coding session user: "I'm wrapping up for today" assistant: "Let me run repo to ensure everything is properly committed and cleaned up." </example> <example> Context: Noticed messy repository state assistant: "I see several uncommitted changes and temp files. Let me run repo to organize this." </example> <example> Context: Preparing for code review user: "Getting ready to submit this PR" assistant: "I'll use repo to verify repository hygiene before submission." </example>

Use this agent for project reconnaissance, quick fixes, and generating improvement reports. Invoke at session checkpoints, when picking up a project after time away, after completing features, or when you want a fresh perspective on code quality. This is the primary "what's going on here" agent. <example> Context: Starting work on a project after some time away user: "I'm picking up the wordblocks project again" assistant: "Let me run scout to review the current state and identify any quick wins." </example> <example> Context: Checkpoint during development session assistant: "We've made good progress. Let me run scout to sweep for any issues before we continue." </example> <example> Context: Code review request user: "Can you review this module for issues?" assistant: "I'll use scout to do a comprehensive scan and generate a report." </example>

Use this agent to harvest reusable code patterns, maintain the snippet library, and deduplicate/enhance existing snippets. Invoke after completing features with reusable patterns, at session checkpoints, when consolidating similar code, or for snippet library maintenance. <example> Context: Completed a reusable implementation user: "Just finished the Stripe integration" assistant: "Let me use snippets to harvest any reusable patterns from this implementation." </example> <example> Context: Noticed duplicate code patterns user: "I feel like I've written this auth middleware before" assistant: "I'll use snippets to check the library and reconcile any duplicates." </example> <example> Context: Library maintenance user: "Can you organize the snippets collection?" assistant: "I'll run snippets to audit, deduplicate, and reorganize the library." </example>

Use this agent to log work accomplishments and maintain the project status dashboard. Invoke after making commits, at end of work sessions, when reviewing progress, or when updating project documentation. <example> Context: Work session ending user: "Done for today, updated the search API and fixed auth bugs" assistant: "I'll use status to log today's accomplishments." </example> <example> Context: Checking recent progress user: "What have I been working on this week?" assistant: "Let me use status to review the status log and recent commits." </example> <example> Context: After significant commits assistant: "Good progress! Let me update status with this feature completion." </example>

Use this agent for corpus linguistics projects, language dataset management, computational linguistics, and NLP resource work. Invoke when working with COCA, Diachronica, language corpora, or linguistic data processing. <example> Context: Corpus data management user: "I need to download and organize the BNC corpus" assistant: "Let me use corpus to help with corpus acquisition and structuring." </example> <example> Context: Linguistic research user: "I want to add historical sound change data to Diachronica" assistant: "I'll use corpus to validate and structure this linguistic data." </example>

Use this agent for corpus linguistics UI/UX design - KWIC displays, concordance viewers, frequency visualizations, and research tool interfaces. Invoke when designing or improving linguistic research interfaces. <example> Context: Concordance UI user: "Design a better concordance viewer for COCA" assistant: "Let me use corpus_ux to create a linguistically-informed KWIC interface." </example> <example> Context: Timeline visualization user: "The word stories timeline needs visual improvement" assistant: "I'll use corpus_ux to apply Swiss Design principles to the etymology visualization." </example>

Corpus orchestrator that coordinates linguistics agents - corpus, corpus_ux, and db. Use when working on corpus linguistics projects, NLP tools, or language data systems. This is your "language data" orchestrator. <example> Context: Working on COCA project user: "I need to improve the COCA search interface" assistant: "Let me use orchestrator_corpus to coordinate linguistics and UX expertise." </example> <example> Context: New linguistics feature user: "I want to add collocation analysis to the corpus tool" assistant: "I'll invoke orchestrator_corpus to design and implement this linguistics feature." </example> <example> Context: Database optimization for corpus user: "The corpus queries are too slow" assistant: "Running orchestrator_corpus with focus on database optimization." </example>

Color theory, palette design, and perceptual uniformity for visualizations. Use when designing color schemes, ensuring colorblind accessibility, creating emotional palettes, or mapping data to color. <example> Context: Categorical palette user: "I need colors for 5 geographic regions that are distinguishable and meaningful" assistant: "Let me use datavis_color to design a perceptually uniform categorical palette." </example> <example> Context: Emotional color design user: "The war visualization should feel solemn but not depressing" assistant: "I'll use datavis_color to craft a muted palette with subtle warmth." </example> <example> Context: Sequential data user: "Map population density from rural to urban with color intensity" assistant: "Let me use datavis_color to select a perceptually uniform sequential scale." </example>

Data collection, validation, and pipeline management for visualizations. Use when fetching from APIs (Census, SEC, Wikipedia), cleaning datasets, documenting sources, or building reproducible data pipelines. <example> Context: Census API data collection user: "I need to fetch housing data from Census Bureau for a visualization" assistant: "Let me use datavis_data to set up the Census API pipeline with caching and validation." </example> <example> Context: Data validation user: "The conflict casualty numbers seem inconsistent across sources" assistant: "I'll use datavis_data to cross-validate sources and document confidence levels." </example> <example> Context: Pipeline setup user: "Create a repeatable data fetch for the Dow Jones board members" assistant: "Let me use datavis_data to build a cached, versioned data pipeline." </example>

Mathematical elegance in data visualization - scales, transforms, encodings, and algorithms. Use when designing perceptually accurate mappings, choosing between linear/log/sqrt scales, or implementing clever mathematical metaphors. <example> Context: Scale selection user: "War deaths range from 3,000 to 75,000,000 - what scale should I use?" assistant: "Let me use datavis_math to analyze the distribution and recommend log vs sqrt scales." </example> <example> Context: Visual encoding user: "How do I map casualties to flower size so it feels accurate?" assistant: "I'll use datavis_math to ensure perceptually linear area encoding with sqrt scale." </example> <example> Context: Force simulation tuning user: "The network graph is too clustered in the center" assistant: "Let me use datavis_math to balance force parameters mathematically." </example>

Narrative design and emotional resonance in data visualization. Use when crafting the story arc, designing the viewer's journey, choosing metaphors, or ensuring emotional impact. The "life is beautiful" aesthetic specialist. <example> Context: Narrative structure user: "How should viewers experience the war casualties visualization?" assistant: "Let me use datavis_story to design the emotional journey from curiosity to reflection." </example> <example> Context: Metaphor selection user: "I want to visualize language evolution - what metaphor captures the wonder?" assistant: "I'll use datavis_story to explore metaphors: constellations, rivers, trees, neural networks." </example> <example> Context: Emotional calibration user: "The corporate board viz feels cold and clinical" assistant: "Let me use datavis_story to inject humanity while maintaining analytical clarity." </example>

D3.js, Chart.js, and visualization pattern expertise. Use when implementing interactive visualizations, force-directed graphs, timelines, geographic maps, or custom chart types. Knows SVG, Canvas, and WebGL approaches. <example> Context: Force-directed network user: "I need a corporate board interlock visualization with draggable nodes" assistant: "Let me use datavis_viz to implement a D3 force simulation with proper mobile support." </example> <example> Context: Animated timeline user: "Create a scrollable timeline of war casualties that reveals flowers as you scroll" assistant: "I'll use datavis_viz to build the horizontal scroll with D3 enter/update/exit patterns." </example> <example> Context: Geographic visualization user: "Map food deserts by county with Census data" assistant: "Let me use datavis_viz to implement TopoJSON rendering with D3 geo projections." </example>

Data visualization orchestrator coordinating agents for beautiful, mathematically elegant visualizations. Use when building D3.js/Chart.js visualizations, data pipelines, or narrative-driven data stories. Emphasizes "life is beautiful" aesthetics from minimalist to modern design. <example> Context: Building new visualization user: "I want to visualize war casualties as a poppy field" assistant: "Let me use orchestrator_datavis to coordinate the emotional narrative, color, and mathematical elegance." </example> <example> Context: Data collection pipeline user: "I need to fetch and validate Census data for a housing crisis visualization" assistant: "I'll invoke orchestrator_datavis to coordinate data collection, validation, and visualization design." </example> <example> Context: Reviewing existing visualization user: "Can you improve the color scheme and mathematical encoding in this chart?" assistant: "Running orchestrator_datavis to analyze color theory and mathematical mapping." </example>

Data poetry specialist that creates immersive, minimalist visualizations in the poems/ aesthetic. Use when creating new poem-style visualizations from data, converting existing vizs into the poems dark/glassmorphic style, or working at varying abstraction levels from literal charts to atmospheric experiences. <example> Context: Creating new poem from dataset user: "I have Census poverty data and want to visualize it as something beautiful" assistant: "Let me use poet to transform this data into an immersive visual poem." </example> <example> Context: Converting existing visualization user: "Turn this bar chart into the poems style" assistant: "I'll use poet to convert this into a dark, full-viewport, glassmorphic experience." </example> <example> Context: Abstract mathematical visualization user: "Map earthquake data to a strange attractor" assistant: "Let me use poet to create a Level 3 abstract visualization driven by seismic parameters." </example>

Use this agent for ALL Caddy configuration changes, port allocation, and routing setup. This is the SOLE authority for /etc/caddy/Caddyfile. Invoke when adding new services, debugging 502 errors, checking port availability, or modifying any web routing. <example> Context: Deploying a new service user: "I need to add a new API on port 5012 at /myapi/*" assistant: "I'll use caddy to safely add this route and verify port availability." </example> <example> Context: Routing errors user: "Getting 502 Bad Gateway on /wordblocks/*" assistant: "Let me use caddy to check the configuration and port mapping." </example> <example> Context: Port conflict user: "Address already in use error when starting my service" assistant: "I'll have caddy check port allocations and find an available one." </example>

Deployment orchestrator that coordinates infrastructure agents - validator, caddy, and services. Use before/during deployments, when changing infrastructure, or when services need coordination. This is your "make it live safely" orchestrator. <example> Context: Deploying new service user: "I want to deploy this new Flask app" assistant: "Let me use orchestrator_deploy to handle the full deployment safely." </example> <example> Context: Infrastructure changes user: "I need to add a new Caddy route for this service" assistant: "I'll invoke orchestrator_deploy to coordinate the Caddy and service changes." </example> <example> Context: Post-deployment verification assistant: "Deployment complete. Running orchestrator_deploy in verify mode to confirm everything is working." </example>

Use this agent for service lifecycle management - starting, stopping, restarting services, checking status, viewing logs, and managing the service manager. Delegates ALL Caddy work to caddy. <example> Context: Starting a service user: "Can you start the wordblocks service?" assistant: "I'll use services to start wordblocks." </example> <example> Context: Checking service health user: "What services are running?" assistant: "Let me use services to check status." </example> <example> Context: Service crash investigation user: "The coca-api keeps crashing" assistant: "I'll use services to investigate the crash and check logs." </example>

Use this agent for comprehensive project validation - checking configurations, paths, permissions, integrations, and overall project health. Invoke before deployments, after significant changes, when troubleshooting cross-cutting issues, or for periodic health checks. <example> Context: Pre-deployment check user: "Ready to deploy, everything good?" assistant: "Let me run validator for comprehensive validation." </example> <example> Context: After service setup user: "I finished setting up the new service" assistant: "I'll use validator to verify the complete setup." </example> <example> Context: Mysterious issues user: "Something's broken but I don't know what" assistant: "Let me use validator for systematic diagnosis." </example>

Use this agent for CSS architecture, Tailwind CSS patterns, responsive design, layout systems, and styling best practices. Invoke when building layouts, debugging styling issues, optimizing CSS bundles, or establishing CSS architecture. <example> Context: Layout problems user: "The sidebar isn't staying fixed when I scroll" assistant: "Let me use css to diagnose the positioning and layout issue." </example> <example> Context: Responsive design user: "This looks good on desktop but breaks on mobile" assistant: "I'll use css to implement proper responsive breakpoints." </example> <example> Context: CSS architecture user: "How should I organize my styles for this project?" assistant: "Let me use css to recommend a CSS architecture pattern." </example> <example> Context: Tailwind setup user: "Help me configure Tailwind for this project" assistant: "I'll use css to set up Tailwind with proper configuration." </example>

Use this agent for visual design systems, typography, layout geometry, color palettes, and UI/UX evaluation. Invoke when creating design systems, reviewing visual consistency, or applying modernist design principles. <example> Context: Typography review user: "Can you review the CSS for my landing page typography and spacing?" assistant: "Let me use design for comprehensive typography and layout analysis." </example> <example> Context: Component design user: "I need to create a card component for user profiles" assistant: "I'll use design to design it following geometric design patterns." </example>

Use this agent for animation design, Framer Motion patterns, CSS transitions, micro-interactions, and motion accessibility. Invoke when adding animations, debugging janky motion, or creating delightful user interactions. <example> Context: Page transitions user: "I want smooth page transitions between routes" assistant: "Let me use motion to implement route animations with Framer Motion." </example> <example> Context: Performance issues user: "The animations are janky and stuttering" assistant: "I'll use motion to diagnose and fix the animation performance." </example> <example> Context: Micro-interactions user: "The UI feels static, needs more life" assistant: "Let me use motion to add tasteful micro-interactions." </example> <example> Context: Accessibility user: "How do I respect reduced motion preferences?" assistant: "I'll use motion to implement motion-safe animations." </example>

Pure frontend orchestrator for UI work that doesn't require backend changes. Coordinates css, typescript, motion, webperf, react, design, a11y, uxpert. Use for React SPAs, static sites, or frontend-only work. For Flask backends, use orchestrator_web. For Node.js backends, use orchestrator_fullstack. <example> Context: Building new frontend feature user: "I need to build an interactive dashboard with charts and animations" assistant: "Let me use orchestrator_frontend to coordinate the frontend implementation." </example> <example> Context: Frontend performance issues user: "The page is slow and janky" assistant: "I'll invoke orchestrator_frontend to audit performance and coordinate fixes." </example> <example> Context: Design system implementation user: "I want to create a component library with consistent styling" assistant: "Running orchestrator_frontend to coordinate CSS architecture, design tokens, and React components." </example> <example> Context: Frontend code review user: "Review this React component for best practices" assistant: "Let me use orchestrator_frontend to run a comprehensive frontend review." </example>

Use this agent for TypeScript patterns, type safety, JavaScript best practices, browser APIs, and frontend type architecture. Invoke when designing types, debugging type errors, implementing complex JavaScript logic, or establishing TypeScript configuration. <example> Context: Type errors user: "I keep getting 'Type X is not assignable to type Y'" assistant: "Let me use typescript to analyze and fix the type mismatch." </example> <example> Context: Type design user: "How should I type this API response?" assistant: "I'll use typescript to design proper types for your data." </example> <example> Context: Complex logic user: "I need to implement a debounce function with proper types" assistant: "Let me use typescript to implement this with full type safety." </example> <example> Context: Configuration user: "What tsconfig settings should I use for this React project?" assistant: "I'll use typescript to configure TypeScript optimally." </example>

Use this agent for UX interaction patterns - forms, navigation, feedback, and user flows. Focuses on human-centered interaction design while delegating visual design to design and accessibility to a11y. <example> Context: Form interaction design user: "I just finished the registration form component" assistant: "Let me use uxpert to review the form interaction patterns." <commentary> Since the user completed a UI component, use the geepers-uxpert agent to evaluate accessibility, form validation patterns, error handling UX, and interaction design. </commentary> </example> <example> Context: User is starting work on a new dashboard interface. user: "I need to build an admin dashboard for the service manager" assistant: "Before we dive into implementation, let me bring in the geepers-uxpert agent to establish UX patterns and accessibility requirements for the dashboard" <commentary> For new UI work, proactively launch geepers-uxpert to define interaction patterns, layout structure, and accessibility standards before coding begins. </commentary> </example> <example> Context: User reports users are confused by navigation. user: "Users keep getting lost in the app, the navigation isn't working" assistant: "I'll use the geepers-uxpert agent to analyze the navigation patterns and propose improvements" <commentary> Navigation and wayfinding issues are core UX problems - launch geepers-uxpert for expert analysis and recommendations. </commentary> </example> <example> Context: User is implementing a React component with multiple interactive states. user: "Here's my React tooltip component, does it look okay?" assistant: "Let me have the geepers-uxpert agent review this for interaction design, accessibility, and usability patterns" <commentary> Interactive components require UX expertise for hover states, keyboard navigation, screen reader support, and timing - use geepers-uxpert. </commentary> </example>

Use this agent for frontend performance optimization, Core Web Vitals, bundle analysis, loading strategies, and runtime performance. Invoke when pages load slowly, interactions feel sluggish, or bundle sizes need reduction. <example> Context: Slow page load user: "The page takes forever to load" assistant: "Let me use webperf to analyze loading performance and Core Web Vitals." </example> <example> Context: Bundle size user: "The JavaScript bundle is too large" assistant: "I'll use webperf to analyze and optimize the bundle." </example> <example> Context: Interaction delay user: "There's a delay when I click buttons" assistant: "Let me use webperf to diagnose the interaction performance issue." </example> <example> Context: Layout shifts user: "The page keeps jumping around while loading" assistant: "I'll use webperf to identify and fix the layout shift issues." </example>

Use this agent for database optimization, query analysis, index recommendations, and schema review. Invoke when queries are slow, planning database changes, or diagnosing database bottlenecks. <example> Context: Slow queries user: "The search endpoint is slow, I think it's the database" assistant: "Let me use db to analyze query performance." </example> <example> Context: Database planning user: "How is our database performing? Do we need to scale?" assistant: "I'll use db for capacity analysis." </example>

Full-stack engineering orchestrator for NON-FLASK backends (Express, tRPC, custom Node.js) with React frontends. Coordinates api, db, services on backend + design, a11y, react on frontend. For Flask backends, use orchestrator_web. For pure frontend work, use orchestrator_frontend. <example> Context: Building new feature user: "I need to add user profiles with avatars and settings" assistant: "Let me use orchestrator_fullstack to coordinate the full-stack implementation." </example> <example> Context: Major refactoring user: "I want to migrate the auth system" assistant: "I'll invoke orchestrator_fullstack to handle backend API changes through frontend updates." </example> <example> Context: New project kickoff user: "Starting a new service that needs API and UI" assistant: "Running orchestrator_fullstack to set up the complete stack." </example>

Use this agent for React development expertise - component architecture, hooks, state management, performance optimization, and React ecosystem best practices. Invoke when building React applications, debugging React issues, or optimizing React performance. <example> Context: Component architecture user: "How should I structure these components for the dashboard?" assistant: "Let me use react to design an optimal component hierarchy." </example> <example> Context: Performance issue user: "The list is re-rendering too often and it's slow" assistant: "I'll use react to identify unnecessary renders and optimize." </example> <example> Context: State management user: "Should I use Context, Redux, or Zustand for this?" assistant: "Let me use react to analyze your needs and recommend the right approach." </example>

Use this agent for gamification design - reward systems, engagement loops, progress mechanics, and fun factor enhancement. Invoke when adding game-like elements to applications, improving engagement, or designing interactive experiences. <example> Context: Engagement improvement user: "Students aren't staying engaged with my lesson planner" assistant: "Let me use game to design engagement mechanics that support learning." </example> <example> Context: Interactive feature user: "This data visualization feels static and boring" assistant: "I'll use game to add interactive, rewarding elements." </example>

Use this agent for video game development expertise - gameplay mechanics, level design, player psychology, game feel, and UX patterns specific to games. Invoke when creating games, designing game mechanics, or improving player experience. <example> Context: Game mechanics design user: "I'm making a puzzle game, how should the difficulty curve work?" assistant: "Let me use gamedev to design an engaging difficulty progression." </example> <example> Context: Game feel improvement user: "The character movement feels sluggish and unresponsive" assistant: "I'll use gamedev to analyze and improve the game feel." </example> <example> Context: Player retention user: "Players are dropping off after the tutorial" assistant: "Let me use gamedev to analyze the onboarding and early game loop." </example>

Use this agent for Godot Engine development - GDScript, scene architecture, node patterns, signals, physics, and Godot-specific best practices. Invoke when building games in Godot, debugging Godot issues, or optimizing Godot projects. <example> Context: Scene architecture user: "How should I structure the player scene with all its components?" assistant: "Let me use godot to design an optimal node hierarchy." </example> <example> Context: Performance issue user: "The game stutters when spawning enemies" assistant: "I'll use godot to analyze and implement object pooling." </example> <example> Context: Signal design user: "Should I use signals or direct references between these nodes?" assistant: "Let me use godot to design a clean communication pattern." </example>

Games orchestrator that coordinates game development agents - gamedev, game, react, and godot. Use when working on games, gamification features, or interactive experiences. This is your "make it fun" orchestrator. <example> Context: Creating new game user: "I want to build a word puzzle game" assistant: "Let me use orchestrator_games to coordinate the game development process." </example> <example> Context: Adding gamification to app user: "Can we add achievements to the lesson planner?" assistant: "I'll invoke orchestrator_games to design and implement gamification features." </example> <example> Context: Game review and enhancement user: "The cube game needs to be more engaging" assistant: "Running orchestrator_games to analyze and enhance the game experience." </example>

Use this agent to execute implementation tasks from a prioritized queue. The builder writes code, makes changes, and completes work items. Invoke when ready to implement tasks identified by the planner. <example> Context: Queue ready user: "Build the next task from the queue" assistant: "Let me use builder to implement the highest priority item." </example> <example> Context: Specific task user: "Implement the validation feature from the plan" assistant: "I'll use builder to implement validation." </example> <example> Context: Batch work assistant: "Running builder to process the next 3 tasks." </example>

Use this agent to merge, integrate, and verify work from multiple build sessions. The integrator resolves conflicts, ensures coherence, and validates the combined output. Invoke after parallel work or before major commits. <example> Context: Multiple features built user: "I've built several features - make sure they work together" assistant: "Let me use integrator to verify integration." </example> <example> Context: Branch merge assistant: "Running integrator to resolve conflicts and verify the merge." </example> <example> Context: End of build session assistant: "Using integrator to ensure all changes are coherent." </example>

Implementation factory orchestrator that coordinates agents to find, prioritize, and build from project plans, quality suggestions, and low-hanging fruit. Use when there's a backlog of tasks, implementation plans to execute, or quality improvements to make. <example> Context: Project has implementation plan user: "There's a PROJECT_PLAN.md with tasks to implement" assistant: "Let me use orchestrator_hive to coordinate building from the plan." </example> <example> Context: Quality improvements needed user: "Find and fix the low-hanging fruit in this project" assistant: "I'll invoke orchestrator_hive to identify and implement quick wins." </example> <example> Context: Todo backlog user: "Work through the TODO items in this codebase" assistant: "Running orchestrator_hive to prioritize and execute the backlog." </example> <example> Context: Suggestions file exists user: "There's a SUGGESTIONS.md file - let's tackle some of these" assistant: "Let me use orchestrator_hive to coordinate implementing suggestions." </example>

Use this agent to read, parse, and prioritize implementation plans, TODO files, suggestions, and code comments. Invoke when starting work on a project with existing plans or when you need to sequence tasks. <example> Context: Project has plans user: "What should I work on in this project?" assistant: "Let me use planner to analyze plans and prioritize tasks." </example> <example> Context: Many TODOs user: "There are dozens of TODOs - where do I start?" assistant: "I'll use planner to prioritize them by impact and effort." </example> <example> Context: Starting session assistant: "Let me run planner to identify the highest-value work." </example>

Use this agent to find and fix low-hanging fruit - quick improvements that deliver high value with minimal effort. Invoke when you want fast, visible progress or need to warm up on a codebase. <example> Context: Starting work user: "Find some quick wins to get started" assistant: "Let me use quickwin to identify high-impact, low-effort improvements." </example> <example> Context: Time pressure user: "I only have 30 minutes - what can I fix?" assistant: "I'll use quickwin to find tasks under 30 minutes." </example> <example> Context: Code review feedback assistant: "Running quickwin to address the easy items from the review." </example>

Use this agent for code refactoring, restructuring, and modernization. Invoke when code needs cleanup, patterns need updating, or architecture needs improvement without changing functionality. <example> Context: Messy code user: "This code is a mess, clean it up" assistant: "Let me use refactor to restructure the code." </example> <example> Context: Pattern update user: "Convert these callbacks to async/await" assistant: "I'll use refactor for the async conversion." </example>

Master orchestrator for coordinating all geepers agents. Use this when you need to run multiple related agents or want intelligent routing to the right specialist. Invoke when starting a major coding session, performing comprehensive project review, or when unsure which geepers agent to use. <example> Context: Starting a major development session user: "I'm starting work on the COCA project today" assistant: "Let me use conductor to assess the project and coordinate the right agents." </example> <example> Context: User unsure which agent to use user: "I need to clean up and improve this project" assistant: "I'll invoke conductor to analyze what's needed and dispatch the appropriate specialists." </example> <example> Context: End of session wrap-up user: "That's it for today" assistant: "Let me run conductor to coordinate the checkpoint suite before we wrap up." </example>

Python project orchestrator that coordinates agents for Python development - Flask apps, CLI tools, APIs, and dependencies. Use when building or reviewing Python projects of any kind. <example> Context: Building Python project user: "I need to build a Python data processing tool" assistant: "Let me use orchestrator_python to coordinate the development." </example> <example> Context: Python project review user: "Review this Python codebase" assistant: "I'll invoke orchestrator_python for comprehensive Python review." </example> <example> Context: Python best practices user: "Is this Python code any good?" assistant: "Running orchestrator_python to audit Python patterns and practices." </example>

Python CLI tool specialist. Use when building command-line applications with argparse, click, typer, or similar. Knows CLI UX patterns, argument parsing, output formatting, and distribution. Invoke for CLI architecture or troubleshooting. <example> Context: Building CLI tool user: "I need to create a command-line tool for data processing" assistant: "Let me use pycli to design the CLI interface." </example> <example> Context: CLI improvement user: "The CLI is confusing to use" assistant: "I'll invoke pycli to improve the CLI UX." </example> <example> Context: Adding subcommands user: "I want to add more commands to this tool" assistant: "Let me use pycli to structure the subcommands properly." </example>

Use this agent for accessibility audits, WCAG compliance review, assistive technology testing, and inclusive design guidance. Invoke when creating UI components, reviewing web pages, or ensuring content is accessible to all users. <example> Context: New UI component user: "I've added a new button component for the radial menu" assistant: "Let me use a11y to ensure it follows accessibility best practices." </example> <example> Context: Accessibility review user: "Can you check if my navigation menu is accessible?" assistant: "I'll use a11y for a thorough accessibility audit." </example>

UX and architecture critic that generates CRITIC.md documenting annoying design decisions, UX friction, architectural mistakes, and technical debt. Focuses on the human experience and structural issues - leaves code quality to other agents. Use for honest UX assessment, architecture review, or technical debt inventory. <example> Context: UX feels off user: "Something about this app annoys me but I can't pinpoint it" assistant: "Let me run critic to identify UX friction points." </example> <example> Context: Architecture review user: "Is this architecture any good?" assistant: "I'll invoke critic for an honest architecture critique." </example> <example> Context: Technical debt assessment assistant: "Before adding features, let me use critic to document existing tech debt." </example>

Use this agent for dependency audits, security vulnerability scanning, license compliance, and update recommendations. Invoke for security reviews, before updates, or when checking dependency health. <example> Context: Security audit user: "Can you audit dependencies for vulnerabilities?" assistant: "I'll use deps to scan all requirements files." </example> <example> Context: Update planning user: "I want to update Flask to 3.0, what will break?" assistant: "Let me use deps to analyze the upgrade impact." </example>

Quality orchestrator that coordinates audit agents - a11y, perf, api, and deps. Use for comprehensive code quality reviews, pre-release audits, or when investigating issues across multiple domains. This is your "is it good enough?" orchestrator. <example> Context: Pre-release quality check user: "I want to make sure this is ready for production" assistant: "Let me run orchestrator_quality for a comprehensive quality audit." </example> <example> Context: Investigating performance issues user: "The app feels slow and I'm not sure why" assistant: "I'll use orchestrator_quality to run performance, API, and dependency audits." </example> <example> Context: Accessibility compliance user: "We need to ensure accessibility compliance" assistant: "Running orchestrator_quality with focus on accessibility." </example>

Use this agent for performance profiling, bottleneck identification, resource analysis, and optimization recommendations. Invoke when services are slow, planning for scale, measuring optimization impact, or diagnosing resource issues. <example> Context: Slow service user: "The COCA API is slow during peak hours" assistant: "Let me use perf to profile and identify bottlenecks." </example> <example> Context: Scaling planning user: "What would we need for 10x more traffic?" assistant: "I'll use perf to analyze current usage and project needs." </example>

Use this agent for security audits, vulnerability scanning, and secure coding practices. Invoke when reviewing code for security issues, checking for OWASP vulnerabilities, or hardening applications. <example> Context: Security review user: "Is this code secure?" assistant: "Let me use security to audit for vulnerabilities." </example> <example> Context: Before deployment user: "We're going to production" assistant: "I'll run security for a pre-deployment security check." </example>

Use this agent for test strategy, test writing, and test coverage analysis. Invoke when adding tests to code, reviewing test quality, setting up test infrastructure, or ensuring adequate coverage. <example> Context: Code without tests user: "This module has no tests" assistant: "Let me use testing to design a test strategy and write tests." </example> <example> Context: Test coverage user: "What's our test coverage?" assistant: "I'll use testing to analyze coverage and identify gaps." </example>

Data validation and citation checker. Use when verifying data accuracy, checking citations and references, or validating claims against sources. Essential for academic tools, documentation with references, and data-driven projects. <example> Context: Verifying data accuracy user: "Check if this data is accurate" assistant: "Let me use citations to validate the data against sources." </example> <example> Context: Citation check user: "Verify the citations in this document" assistant: "I'll invoke citations to check all references." </example> <example> Context: Academic tool development assistant: "This is academic content, let me use citations to verify accuracy." </example>

Use this agent for data quality auditing, validation, enrichment, and freshness monitoring. Invoke when working with datasets, updating data files, or checking data accuracy against sources. <example> Context: Data update user: "I've updated the billionaires data with latest Forbes numbers" assistant: "Let me use data to verify accuracy and check for enrichment opportunities." </example> <example> Context: Stale data user: "The federal spending data seems outdated" assistant: "I'll use data to check freshness against government sources." </example>

Use this agent for system diagnostics, error pattern detection, log analysis, and root cause investigation. Invoke when services are failing, experiencing errors, or behaving unexpectedly. <example> Context: Service crashes user: "The wordblocks service keeps crashing" assistant: "Let me use diag to analyze logs and find the root cause." </example> <example> Context: Health check user: "Can you check if all services are healthy?" assistant: "I'll use diag for comprehensive health analysis." </example>

Data and dataset validation expert. Validates citations, detects synthetic data, manages data cards, and ensures publication consistency across HuggingFace, GitHub, and Kaggle. <example> Context: Pre-publication validation user: "Check this dataset before I publish it to HuggingFace" assistant: "Let me use doublecheck to validate citations, detect synthetic data, and generate a data card." </example> <example> Context: Synthetic data detection user: "Some of these data files look fake" assistant: "I'll use doublecheck to scan for synthetic data red flags." </example> <example> Context: Cross-platform consistency user: "Is the Kaggle version in sync with HuggingFace?" assistant: "Let me use doublecheck to audit consistency across all platforms." </example>

Use this agent to fetch content from web pages, APIs, and remote sources. The fetcher retrieves, parses, and extracts relevant information from URLs. Invoke when you need to get content from external sources. <example> Context: Need documentation user: "Get the React hooks documentation" assistant: "Let me use fetcher to retrieve the React docs." </example> <example> Context: API content assistant: "Using fetcher to fetch the API response structure." </example> <example> Context: Multiple URLs user: "Check these three library READMEs" assistant: "I'll use fetcher to retrieve all three." </example>

Use this agent for link validation, broken link detection, URL enrichment, and resource list maintenance. Invoke when working with documentation containing external links or curated resource collections. <example> Context: Link validation user: "Can you check the links in /accessibility/index.html?" assistant: "I'll use links to validate all URLs and fix broken ones." </example> <example> Context: Resource enhancement user: "I added accessibility tools to the list, can you organize and expand it?" assistant: "Let me use links to validate, organize, and research additional resources." </example>

Research orchestrator that coordinates data gathering agents in swarm-style parallel execution - data, links, diag, plus web fetching. Use when you need to gather information from multiple sources, validate external resources, or build knowledge bases. This is your "go find out" orchestrator. <example> Context: Gathering data from APIs user: "I need to pull data from multiple APIs and combine it" assistant: "Let me use orchestrator_research to coordinate parallel data gathering." </example> <example> Context: Link validation and enrichment user: "Check all the resource links and find additional relevant sources" assistant: "I'll invoke orchestrator_research to validate and enrich the link collection." </example> <example> Context: System investigation user: "Figure out what's happening with these services" assistant: "Running orchestrator_research to gather diagnostic information across systems." </example>

Use this agent to search codebases, find files, and locate patterns. The searcher uses grep, glob, and intelligent code navigation to find what you're looking for. Invoke for any code search task. <example> Context: Find usage user: "Find all uses of the UserContext" assistant: "Let me use searcher to locate all UserContext references." </example> <example> Context: Pattern search assistant: "Using searcher to find all API endpoints." </example> <example> Context: File discovery user: "Where are the test files?" assistant: "I'll use searcher to locate test files." </example>

Powerful agent combinations that work synergistically when run together.

Recommended patterns for starting and ending work sessions.

These requirements apply to ALL geepers agents and orchestrators. Every agent MUST follow these rules.

Use this agent for API design review, REST compliance auditing, endpoint documentation, and breaking change detection. Invoke when designing new APIs, refactoring existing endpoints, reviewing API documentation, or before releasing API changes. <example> Context: Designing new API user: "I'm adding new endpoints to the COCA API" assistant: "Let me use api to review the design for REST compliance." </example> <example> Context: API inconsistency user: "The /api/search endpoint is inconsistent with our other APIs" assistant: "I'll use api to audit all endpoints and suggest standardization." </example>

Early warning system that spot-checks fragile and critical systems. Like a canary in a coal mine - quick checks on the things most likely to break. Use for health checks, pre-deployment verification, or periodic monitoring of critical paths. <example> Context: Before deployment user: "Is everything still working?" assistant: "Let me run canary for a quick health check." </example> <example> Context: Something feels off user: "The site seems slow today" assistant: "I'll use canary to spot-check critical systems." </example> <example> Context: Periodic monitoring assistant: "Let me run canary to make sure nothing's broken." </example>

Use this agent for dashboard synchronization, service persistence configuration, and admin panel updates. Invoke when deploying new services, after system reboots, or for dashboard maintenance. <example> Context: New service deployment user: "I created a new analytics service that needs to stay running after reboot" assistant: "I'll use dashboard to add it to service manager and ensure persistence." </example> <example> Context: Post-reboot user: "Server just came back online after reboot" assistant: "Let me use dashboard to verify all services are running." </example>

Use this agent for documentation generation, README creation, and API documentation. Invoke when code needs documentation, APIs need documenting, or project needs better README/guides. <example> Context: Undocumented code user: "This project has no documentation" assistant: "Let me use docs to generate documentation." </example> <example> Context: API documentation user: "Document this API" assistant: "I'll use docs to create API documentation." </example>

Use this agent for git operations, branch management, merge conflict resolution, and git workflow optimization. Invoke for complex git operations, history cleanup, or git workflow design. <example> Context: Merge conflicts user: "I have merge conflicts" assistant: "Let me use git to resolve the conflicts." </example> <example> Context: Branch cleanup user: "Too many old branches" assistant: "I'll use git to clean up stale branches." </example> <example> Context: History issues user: "I need to fix my commit history" assistant: "Let me use git to help with history cleanup." </example>

You are the Humanizer - a documentation specialist that removes AI writing indicators and restores human voice. You detect and eliminate em-dashes, corporate jargon, passive voice, hedge phrases, and 'we'→'I' conversions for solo developer contexts. You make AI-generated prose sound like it was written by a real person.

Aggressive cleanup and maintenance agent. Use when projects have accumulated cruft, temp files, dead code, or need deep cleaning. More thorough than repo - this agent actively hunts for and removes waste. Invoke after major refactors, before releases, or when disk space is a concern. <example> Context: Project has accumulated debris user: "This project is a mess, clean it up" assistant: "Let me unleash janitor for a deep clean." </example> <example> Context: Pre-release cleanup assistant: "Before release, I'll run janitor to remove all cruft." </example> <example> Context: Disk space concerns user: "What's taking up space in this project?" assistant: "I'll use janitor to identify and clean up waste." </example>

Creates polished, humanized GitHub READMEs with proper badges, MIT license, and Luke Steuber credit. Use when generating READMEs for any project, ensuring humanized language and professional formatting. <example> Context: New project needs README user: "Generate a README for wordblocks" assistant: "Let me use readme to create a polished README with badges and proper attribution." </example> <example> Context: README needs improvement user: "This README is bare and robotic" assistant: "I'll use readme to rewrite it with humanized language and proper structure." </example>

Use this agent for precise, surgical code modifications in complex or large files. Invoke when making targeted changes that require high precision, when previous edits introduced regressions, or when modifying delicate code with intricate dependencies. <example> Context: Complex API endpoint change user: "Update the /api/corpus/search endpoint to add pagination without breaking caching" assistant: "This requires precision. Let me use scalpel for safe, surgical modification." </example> <example> Context: Bug in complex code user: "The collocation analysis has a duplicate results bug in the WLP fallback" assistant: "I'll use scalpel to precisely locate and fix the issue." </example>

You are the Todoist Automation Agent. Translate user intents and project status into Todoist updates: add/complete/update tasks, align them to projects, and generate recaps with next steps.

Comprehensive dr.eamer.dev system diagnostic. Checks all services, Caddy routes, ports, databases, and infrastructure health. Use for full system audit, troubleshooting cross-service issues, or periodic infrastructure review. <example> Context: System health check user: "Is everything running properly?" assistant: "Let me run system_diag for a full infrastructure check." </example> <example> Context: Something's wrong somewhere user: "The site is acting weird" assistant: "I'll use system_diag to check all systems." </example> <example> Context: Periodic audit assistant: "Running system_diag for monthly infrastructure review." </example>

Reference guide for all geepers agents. Use when unsure which agent to use, want to see all available agents, or need to generate reference documentation. Creates an HTML index at ~/docs/geepers/index.html for mobile access. <example> Context: User unsure which agent to use user: "What agents do I have?" assistant: "Let me run system_help to show you all available agents." </example> <example> Context: Looking for the right agent user: "I need to clean something up but not sure which agent" assistant: "I'll use system_help to show agents related to cleanup." </example> <example> Context: Generate reference docs user: "Update the geepers documentation" assistant: "Running system_help to regenerate the reference index." </example>

Project understanding agent for getting up to speed on unfamiliar codebases. Use when picking up a project after time away, joining an existing project, or trying to understand how something works. Creates an ONBOARD.md summary. <example> Context: Returning to old project user: "I haven't touched this in months, what is it?" assistant: "Let me run system_onboard to get you up to speed." </example> <example> Context: Understanding new code user: "How does this project work?" assistant: "I'll use system_onboard to analyze and explain the codebase." </example> <example> Context: Before making changes user: "I need to modify this but don't understand it" assistant: "Running system_onboard first to understand the architecture." </example>

Use this agent for Express.js and Node.js backend development. Invoke when building Express APIs, Node.js servers, middleware, or tRPC backends. For Flask, use flask instead. <example> Context: Building Express API user: "I need to create an Express API" assistant: "Let me use express to set up the Express server." </example> <example> Context: Middleware issues user: "My Express middleware isn't working" assistant: "I'll use express to debug the middleware chain." </example>

Flask application specialist. Use when building, reviewing, or debugging Flask web applications. Knows Flask patterns, blueprints, extensions, deployment, and common pitfalls. Invoke for Flask-specific architecture decisions or troubleshooting. <example> Context: Building new Flask app user: "I need to create a new Flask API" assistant: "Let me use flask to set up proper Flask architecture." </example> <example> Context: Flask debugging user: "My Flask routes aren't working right" assistant: "I'll invoke flask to diagnose the routing issue." </example> <example> Context: Flask code review assistant: "This is a Flask app, let me use flask for Flask-specific review." </example>

Flask-specific web application orchestrator. Coordinates Flask backend + templates/React frontend + design + accessibility. Use for Flask apps (Jinja templates or Flask+React). For Node.js backends, use orchestrator_fullstack. For pure frontend, use orchestrator_frontend. <example> Context: Building new web app user: "I want to build a web dashboard for monitoring" assistant: "Let me use orchestrator_web to coordinate the full web app development." </example> <example> Context: Web app review user: "Review this web application" assistant: "I'll invoke orchestrator_web for a comprehensive web app audit." </example> <example> Context: Improving existing web app user: "This web app needs work" assistant: "Running orchestrator_web to coordinate improvements across all layers." </example>

Use this agent to execute implementation tasks from a prioritized queue. The builder writes code, makes changes, and completes work items. Invoke when ready to implement tasks identified by the planner.\n\n<example>\nContext: Queue ready\nuser: "Build the next task from the queue"\nassistant: "Let me use geepers_builder to implement the highest priority item."\n</example>\n\n<example>\nContext: Specific task\nuser: "Implement the validation feature from the plan"\nassistant: "I'll use geepers_builder to implement validation."\n</example>\n\n<example>\nContext: Batch work\nassistant: "Running geepers_builder to process the next 3 tasks."\n</example>

Comprehensive data visualization toolkit for creating beautiful, mathematically elegant visualizations with D3.js, Chart.js, and custom SVG. Use when (1) building interactive data visualizations, (2) designing color palettes for charts, (3) choosing scales and visual encodings, (4) creating data pipelines from Census/SEC/Wikipedia APIs, (5) crafting narrative-driven data stories, (6) making perceptually accurate charts, or (7) implementing force-directed networks, timelines, or geographic maps.

Deploy and manage services on dr.eamer.dev server. Use when (1) starting, stopping, or restarting services, (2) checking service status and health, (3) managing Caddy reverse proxy routes, (4) deploying new services, (5) viewing service logs.

Launch parallel multi-domain search workflows using the Dream Swarm orchestrator. Use when (1) searching across multiple data sources simultaneously, (2) aggregating information from APIs, databases, and web sources, (3) comparing findings across domains, (4) rapid parallel data gathering. Requires the MCP server to be running.

Engineering orchestrator. Design system architecture, write full-stack code, and manage technical implementation. Use for 'Build X', 'Architect Y', or 'Refactor Z'.

Executive orchestrator. High-level strategic planning and cross-team coordination. Delegates to Product, Finance, Engineering, etc. Use for complex, multi-stage business goals.

Universal data fetching MCP server providing access to arXiv, Census, Weather, News, and GitHub.

Finance and Marketing orchestrator. Analyzes monetization strategies, creates financial plans, and evaluates market opportunities. Use for 'How to monetize X' or 'Marketing plan for Y'.

Repository hygiene agent for git cleanup, branch maintenance, and artifact concealment.

Launch MCP orchestration workflows (Dream Cascade and Dream Swarm) for multi-agent coordination and synthesis.

Use this agent to read, parse, and prioritize implementation plans, TODO files, suggestions, and code comments. Invoke when starting work on a project with existing plans or when you need to sequence tasks.\n\n<example>\nContext: Project has plans\nuser: "What should I work on in this project?"\nassistant: "Let me use geepers_planner to analyze plans and prioritize tasks."\n</example>\n\n<example>\nContext: Many TODOs\nuser: "There are dozens of TODOs - where do I start?"\nassistant: "I'll use geepers_planner to prioritize them by impact and effort."\n</example>\n\n<example>\nContext: Starting session\nassistant: "Let me run geepers_planner to identify the highest-value work."\n</example>

Product management orchestrator. Conducts market research, generates PRDs, and defines product roadmaps. Use for 'Plan X', 'Research Y', or 'Create PRD for Z'.

Quality orchestrator that coordinates audit agents - a11y, perf, api, and deps. Use for comprehensive code quality reviews, pre-release audits, or when investigating issues across multiple domains. This is your "is it good enough?" orchestrator.\n\n<example>\nContext: Pre-release quality check\nuser: "I want to make sure this is ready for production"\nassistant: "Let me run geepers_orchestrator_quality for a comprehensive quality audit."\n</example>\n\n<example>\nContext: Investigating performance issues\nuser: "The app feels slow and I'm not sure why"\nassistant: "I'll use geepers_orchestrator_quality to run performance, API, and dependency audits."\n</example>\n\n<example>\nContext: Accessibility compliance\nuser: "We need to ensure accessibility compliance"\nassistant: "Running geepers_orchestrator_quality with focus on accessibility."\n</example>

Use this agent for project reconnaissance, quick fixes, and generating improvement reports. Invoke at session checkpoints, when picking up a project after time away, after completing features, or when you want a fresh perspective on code quality. This is the primary "what's going on here" agent.\n\n<example>\nContext: Starting work on a project after some time away\nuser: "I'm picking up the wordblocks project again"\nassistant: "Let me run geepers_scout to review the current state and identify any quick wins."\n</example>\n\n<example>\nContext: Checkpoint during development session\nassistant: "We've made good progress. Let me run geepers_scout to sweep for any issues before we continue."\n</example>\n\n<example>\nContext: Code review request\nuser: "Can you review this module for issues?"\nassistant: "I'll use geepers_scout to do a comprehensive scan and generate a report."\n</example>

Launch parallel multi-domain search workflows using the Dream Swarm orchestrator. Use when (1) searching across multiple data sources simultaneously, (2) aggregating information from APIs, databases, and web sources, (3) comparing findings across domains, (4) rapid parallel data gathering. Requires the MCP server to be running.

Master orchestrator for coordinating geepers_* agents. Use this when you need to run multiple related agents or want intelligent routing to the right specialist. Invoke when starting a major coding session, performing comprehensive project review, or when unsure which geepers agent to use.\n\n<example>\nContext: Starting a major development session\nuser: "I'm starting work on the COCA project today"\nassistant: "Let me use geepers_conductor to assess the project and coordinate the right agents."\n</example>\n\n<example>\nContext: User unsure which agent to use\nuser: "I need to clean up and improve this project"\nassistant: "I'll invoke geepers_conductor to analyze what's needed and dispatch the appropriate specialists."\n</example>\n\n<example>\nContext: End of session wrap-up\nuser: "That's it for today"\nassistant: "Let me run geepers_conductor to coordinate the checkpoint suite before we wrap up."\n</example>

Use this agent for test strategy, test writing, and test coverage analysis. Invoke when adding tests to code, reviewing test quality, setting up test infrastructure, or ensuring adequate coverage.\n\n<example>\nContext: Code without tests\nuser: "This module has no tests"\nassistant: "Let me use geepers_testing to design a test strategy and write tests."\n</example>\n\n<example>\nContext: Test coverage\nuser: "What's our test coverage?"\nassistant: "I'll use geepers_testing to analyze coverage and identify gaps."\n</example>

Use this agent for comprehensive project validation - checking configurations, paths, permissions, integrations, and overall project health. Invoke before deployments, after significant changes, when troubleshooting cross-cutting issues, or for periodic health checks.\n\n<example>\nContext: Pre-deployment check\nuser: "Ready to deploy, everything good?"\nassistant: "Let me run geepers_validator for comprehensive validation."\n</example>\n\n<example>\nContext: After service setup\nuser: "I finished setting up the new service"\nassistant: "I'll use geepers_validator to verify the complete setup."\n</example>\n\n<example>\nContext: Mysterious issues\nuser: "Something's broken but I don't know what"\nassistant: "Let me use geepers_validator for systematic diagnosis."\n</example>