GitHub Shell Daily Trending Repositories

msitarzewski/agency-agents

A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers. Each agent is a specialized expert with personality, processes, and proven deliverables.

🎭 The Agency: AI Specialists Ready to Transform Your Workflow

A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers. Each agent is a specialized expert with personality, processes, and proven deliverables.

🆕 There's an app now

Agency Agents is a native app for macOS, Linux & Windows that browses the entire roster and installs it into Claude Code, Cursor, Codex, Gemini, Osaurus, and more — with a click. No clone, no scripts, and it auto-updates.

→ Download the latest release · agencyagents.app

🚀 What Is This?

Born from a Reddit thread and months of iteration, The Agency is a growing collection of meticulously crafted AI agent personalities. Each agent is:

🎯 Specialized: Deep expertise in their domain (not generic prompt templates)
🧠 Personality-Driven: Unique voice, communication style, and approach
📋 Deliverable-Focused: Real code, processes, and measurable outcomes
✅ Production-Ready: Battle-tested workflows and success metrics

Think of it as: Assembling your dream team, except they're AI specialists who never sleep, never complain, and always deliver.

⚡ Quick Start

Option 1: Install the app (Recommended)

The fastest way in — no clone, no terminal. Agency Agents is a native desktop app (macOS · Linux · Windows) that browses the whole roster and installs agents into Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Qwen, and Osaurus for you, then keeps them up to date.

⬇ Download the latest release — or on a Mac:

brew install --cask msitarzewski/agency-agents/agency-agents

Prefer the command line? The script-based options below install the same agents.

Option 2: Use with Claude Code

# Install all agents to your Claude Code directory
./scripts/install.sh --tool claude-code

# Or manually copy a category if you only want one division
cp engineering/*.md ~/.claude/agents/

# Then activate any agent in your Claude Code sessions:
# "Hey Claude, activate Frontend Developer mode and help me build a React component"

Option 3: Use as Reference

Each agent file contains:

Identity & personality traits
Core mission & workflows
Technical deliverables with code examples
Success metrics & communication style

Browse the agents below and copy/adapt the ones you need!

Option 4: Use with Other Tools (GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Kimi Code, Codex, Osaurus, Hermes, Mistral Vibe)

# Step 1 -- generate integration files for all supported tools
./scripts/convert.sh

# Step 2 -- install interactively (auto-detects what you have installed)
./scripts/install.sh

# Or target a specific tool directly
./scripts/install.sh --tool antigravity
./scripts/install.sh --tool gemini-cli
./scripts/install.sh --tool opencode
./scripts/install.sh --tool copilot
./scripts/install.sh --tool openclaw
./scripts/install.sh --tool cursor
./scripts/install.sh --tool aider
./scripts/install.sh --tool windsurf
./scripts/install.sh --tool kimi
./scripts/install.sh --tool codex
./scripts/install.sh --tool osaurus
./scripts/install.sh --tool hermes
./scripts/install.sh --tool vibe

Install only the teams you need (not everyone wants every division):

./scripts/install.sh                                    # interactive wizard: pick tools + teams
./scripts/install.sh --tool claude-code --division engineering,security
./scripts/install.sh --tool cursor --agent frontend-developer,ui-designer
./scripts/install.sh --list teams                       # see every team + agent count
./scripts/install.sh --tool opencode --division engineering --dry-run

OpenCode note: OpenCode's runtime currently registers only ~119 agents and silently drops the rest (upstream bug). Installing a subset with --division keeps you under that limit. The installer warns you when a selection would exceed it.

See the Multi-Tool Integrations section below for full details.

🎨 The Agency Roster

💻 Engineering Division

Building the future, one commit at a time.

Agent	Specialty	When to Use
🎨 Frontend Developer	React/Vue/Angular, UI implementation, performance	Modern web apps, pixel-perfect UIs, Core Web Vitals optimization
🏗️ Backend Architect	API design, database architecture, scalability	Server-side systems, microservices, cloud infrastructure
📱 Mobile App Builder	iOS/Android, React Native, Flutter	Native and cross-platform mobile applications
🤖 AI Engineer	ML models, deployment, AI integration	Machine learning features, data pipelines, AI-powered apps
🚀 DevOps Automator	CI/CD, infrastructure automation, cloud ops	Pipeline development, deployment automation, monitoring
🌐 Network Engineer	Cisco IOS/IOS-XE, Juniper Junos, Palo Alto PAN-OS	Router/switch/firewall configuration, BGP/OSPF, ACLs, show-output troubleshooting
⚡ Rapid Prototyper	Fast POC development, MVPs	Quick proof-of-concepts, hackathon projects, fast iteration
💎 Senior Developer	Laravel/Livewire, advanced patterns	Complex implementations, architecture decisions
🔧 Filament Optimization Specialist	Filament PHP admin UX, structural form redesign, resource optimization	Restructuring Filament resources/forms/tables for faster, cleaner admin workflows
⚡ Autonomous Optimization Architect	LLM routing, cost optimization, shadow testing	Autonomous systems needing intelligent API selection and cost guardrails
🔩 Embedded Firmware Engineer	Bare-metal, RTOS, ESP32/STM32/Nordic firmware	Production-grade embedded systems and IoT devices
🚨 Incident Response Commander	Incident management, post-mortems, on-call	Managing production incidents and building incident readiness
⛓️ Solidity Smart Contract Engineer	EVM contracts, gas optimization, DeFi	Secure, gas-optimized smart contracts and DeFi protocols
🧭 Codebase Onboarding Engineer	Fast developer onboarding, read-only codebase exploration, factual explanation	Helping new developers understand unfamiliar repos quickly by reading the code, tracing code paths, and stating facts about structure and behavior
📚 Technical Writer	Developer docs, API reference, tutorials	Clear, accurate technical documentation
💬 WeChat Mini Program Developer	WeChat ecosystem, Mini Programs, payment integration	Building performant apps for the WeChat ecosystem
👁️ Code Reviewer	Constructive code review, security, maintainability	PR reviews, code quality gates, mentoring through review
🗄️ Database Optimizer	Schema design, query optimization, indexing strategies	PostgreSQL/MySQL tuning, slow query debugging, migration planning
🌿 Git Workflow Master	Branching strategies, conventional commits, advanced Git	Git workflow design, history cleanup, CI-friendly branch management
🏛️ Software Architect	System design, DDD, architectural patterns, trade-off analysis	Architecture decisions, domain modeling, system evolution strategy
🛡️ SRE	SLOs, error budgets, observability, chaos engineering	Production reliability, toil reduction, capacity planning
🧬 AI Data Remediation Engineer	Self-healing pipelines, air-gapped SLMs, semantic clustering	Fixing broken data at scale with zero data loss
🔧 Data Engineer	Data pipelines, lakehouse architecture, ETL/ELT	Building reliable data infrastructure and warehousing
🔗 Feishu Integration Developer	Feishu/Lark Open Platform, bots, workflows	Building integrations for the Feishu ecosystem
🧱 CMS Developer	WordPress & Drupal themes, plugins/modules, content architecture	Code-first CMS implementation and customization
📧 Email Intelligence Engineer	Email parsing, MIME extraction, structured data for AI agents	Turning raw email threads into reasoning-ready context
🎙️ Voice AI Integration Engineer	Speech-to-text pipelines, Whisper, ASR, speaker diarization	End-to-end transcription pipelines, audio preprocessing, structured transcript delivery
🖧 IT Service Manager	ITIL 4 service management	Incident/problem/change management, SLAs, CMDB
🪡 Minimal Change Engineer	Minimum-viable diffs	Fixing only what's asked, no scope creep
📜 OrgScript Engineer	OrgScript grammar & AST validation	Designing/parsing OrgScript business-logic definitions
🧬 Prompt Engineer	LLM prompt design & optimization	Turning vague instructions into reliable AI behaviors
🕸️ Multi-Agent Systems Architect	Multi-agent pipeline design & governance	Topology, context, trust, failure recovery for agent systems
🛒 Drupal Shopping Cart Engineer	Drupal Commerce storefronts	Catalog, payments, checkout, orders on Drupal 10/11
🛍️ WordPress Shopping Cart Engineer	WooCommerce storefronts	Catalog, payments, checkout, conversion on WordPress
💳 Payments & Billing Engineer	PSP integration, idempotent payment flows, subscription billing	Stripe/Adyen/Braintree integrations, webhook processing, dunning, reconciliation
🌍 Internationalization Engineer	ICU MessageFormat, RTL/bidi layouts, CLDR formatting, pseudo-localization	Making apps translation-ready, locale-aware formatting, RTL support, i18n audits
⚡ Drupal Performance Engineer	Drupal performance & Core Web Vitals	Caching, DB/query tuning, render pipeline, profiling high-traffic Drupal
⚡ WordPress Performance Engineer	WordPress performance & Core Web Vitals	Caching, query/asset optimization, plugin tuning, profiling high-traffic WP
♿ Section 508 Accessibility Specialist	US federal 508 / WCAG accessibility	ARIA, screen-reader testing, VPAT/ACR authoring, remediation
🏛️ USWDS Developer	US Web Design System (federal)	Accessible gov UI components & design-system patterns
🔎 Search Relevance Engineer	Search ranking & relevance	Query understanding, embeddings, ranking/eval, relevance tuning
🔐 Identity & Access Engineer	AuthN/AuthZ & IAM	OAuth/OIDC/SAML, SSO, RBAC/ABAC, token & session security
🤝 Realtime Collaboration Engineer	Realtime sync & presence	CRDTs/OT, conflict resolution, live cursors, offline sync
💻 Desktop App Engineer	Cross-platform desktop apps	Electron/Tauri, native integration, packaging, auto-update
🚀 Mobile Release Engineer	Mobile release & CI/CD	App Store/Play submission, signing, staged rollout, crash triage
🎬 Video Streaming Engineer	Video streaming & transcoding	HLS/DASH, ABR, codecs, CDN delivery, low-latency streaming
💰 FinOps Engineer	Cloud cost engineering	Cost allocation, rightsizing, unit economics, budget & anomaly control
🧩 WebAssembly Engineer	WebAssembly & WASI	Rust/C++→WASM, sandboxing, host bindings, performance
🔌 API Platform Engineer	API gateways & platforms	Gateway design, versioning, rate limiting, developer portals
🛟 Database Reliability Engineer	Database reliability (DBRE)	HA/replication, automated failover, PITR backups, zero-downtime ops
🛠️ Developer Tooling Engineer	CLI & developer tooling	Command-line tools, internal DX, build/dev workflows
📡 IoT Fleet Engineer	IoT & edge fleet	Device provisioning/identity, MQTT telemetry, OTA updates
🔍 RAG Pipeline Engineer	Production RAG pipelines	Chunking, retrieval quality, hybrid search, re-ranking, eval-driven iteration
🗄️ GaussDB Expert Engineer	Huawei GaussDB OLTP	Enterprise OLTP performance, HA, and migration on Huawei's GaussDB
🕵️ Privacy Engineer	PII discovery, data minimization, consent enforcement, DSAR/deletion pipelines	Implementing privacy in code, right-to-be-forgotten across services, retention automation
🦀 Rust Refactoring Specialist	Behavior-aware Rust refactoring	Reforming crates/traits/modules with evidence-based, behavior-preserving changes
🧪 LLM Post-Training Engineer	Post-training stack (SFT/DPO/GRPO/RLVR)	Evidence-based experiment gating, checkpoint integrity, failure classification
📈 Data Visualization Engineer	Perceptually honest data viz	Chart-type selection, colorblind-safe palettes, performant D3/Vega rendering

🎨 Design Division

Making it beautiful, usable, and delightful.

Agent	Specialty	When to Use
🎯 UI Designer	Visual design, component libraries, design systems	Interface creation, brand consistency, component design
🔍 UX Researcher	User testing, behavior analysis, research	Understanding users, usability testing, design insights
🏛️ UX Architect	Technical architecture, CSS systems, implementation	Developer-friendly foundations, implementation guidance
🎭 Brand Guardian	Brand identity, consistency, positioning	Brand strategy, identity development, guidelines
📖 Visual Storyteller	Visual narratives, multimedia content	Compelling visual stories, brand storytelling
✨ Whimsy Injector	Personality, delight, playful interactions	Adding joy, micro-interactions, Easter eggs, brand personality
📷 Image Prompt Engineer	AI image generation prompts, photography	Photography prompts for Midjourney, DALL-E, Stable Diffusion
🌈 Inclusive Visuals Specialist	Representation, bias mitigation, authentic imagery	Generating culturally accurate AI images and video
🎭 Persona Walkthrough Specialist	Persona-driven cognitive walkthroughs	Simulating user reactions and friction at each scroll position
🧱 UI Finish-Gate Reviewer	Anti-generic UI finish gate	Catching interchangeable UI before ship via evidence + a written design contract

💰 Paid Media Division

Turning ad spend into measurable business outcomes.

Agent	Specialty	When to Use
💰 PPC Campaign Strategist	Google/Microsoft/Amazon Ads, account architecture, bidding	Account buildouts, budget allocation, scaling, performance diagnosis
🔍 Search Query Analyst	Search term analysis, negative keywords, intent mapping	Query audits, wasted spend elimination, keyword discovery
📋 Paid Media Auditor	200+ point account audits, competitive analysis	Account takeovers, quarterly reviews, competitive pitches
📡 Tracking & Measurement Specialist	GTM, GA4, conversion tracking, CAPI	New implementations, tracking audits, platform migrations
✍️ Ad Creative Strategist	RSA copy, Meta creative, Performance Max assets	Creative launches, testing programs, ad fatigue refreshes
📺 Programmatic & Display Buyer	GDN, DSPs, partner media, ABM display	Display planning, partner outreach, ABM programs
📱 Paid Social Strategist	Meta, LinkedIn, TikTok, cross-platform social	Social ad programs, platform selection, audience strategy

💼 Sales Division

Turning pipeline into revenue through craft, not CRM busywork.

Agent	Specialty	When to Use
🎯 Outbound Strategist	Signal-based prospecting, multi-channel sequences, ICP targeting	Building pipeline through research-driven outreach, not volume
🔍 Discovery Coach	SPIN, Gap Selling, Sandler — question design and call structure	Preparing for discovery calls, qualifying opportunities, coaching reps
♟️ Deal Strategist	MEDDPICC qualification, competitive positioning, win planning	Scoring deals, exposing pipeline risk, building win strategies
🛠️ Sales Engineer	Technical demos, POC scoping, competitive battlecards	Pre-sales technical wins, demo prep, competitive positioning
🏹 Proposal Strategist	RFP response, win themes, narrative structure	Writing proposals that persuade, not just comply
📊 Pipeline Analyst	Forecasting, pipeline health, deal velocity, RevOps	Pipeline reviews, forecast accuracy, revenue operations
🗺️ Account Strategist	Land-and-expand, QBRs, stakeholder mapping	Post-sale expansion, account planning, NRR growth
🏋️ Sales Coach	Rep development, call coaching, pipeline review facilitation	Making every rep and every deal better through structured coaching
🎯 Sales Outreach	Cold prospecting, multi-touch cadences, objection handling, proposals	Top-of-funnel B2B outreach — from cold email to booked discovery call
🧲 Offer & Lead Gen Strategist	Offers & lead magnets	Top-of-funnel offer construction and lead gen

📢 Marketing Division

Growing your audience, one authentic interaction at a time.

Agent	Specialty	When to Use
🚀 Growth Hacker	Rapid user acquisition, viral loops, experiments	Explosive growth, user acquisition, conversion optimization
📝 Content Creator	Multi-platform content, editorial calendars	Content strategy, copywriting, brand storytelling
🐦 Twitter Engager	Real-time engagement, thought leadership	Twitter strategy, LinkedIn campaigns, professional social
🛰️ X/Twitter Intelligence Analyst	Social listening, trend detection, account monitoring	Brand risk, competitor, and audience intelligence on X/Twitter
📱 TikTok Strategist	Viral content, algorithm optimization	TikTok growth, viral content, Gen Z/Millennial audience
📸 Instagram Curator	Visual storytelling, community building	Instagram strategy, aesthetic development, visual content
🤝 Reddit Community Builder	Authentic engagement, value-driven content	Reddit strategy, community trust, authentic marketing
📱 App Store Optimizer	ASO, conversion optimization, discoverability	App marketing, store optimization, app growth
🌐 Social Media Strategist	Cross-platform strategy, campaigns	Overall social strategy, multi-platform campaigns
📕 Xiaohongshu Specialist	Lifestyle content, trend-driven strategy	Xiaohongshu growth, aesthetic storytelling, Gen Z audience
💬 WeChat Official Account Manager	Subscriber engagement, content marketing	WeChat OA strategy, community building, conversion optimization
🧠 Zhihu Strategist	Thought leadership, knowledge-driven engagement	Zhihu authority building, Q&A strategy, lead generation
🇨🇳 Baidu SEO Specialist	Baidu optimization, China SEO, ICP compliance	Ranking in Baidu and reaching China's search market
🎬 Bilibili Content Strategist	B站 algorithm, danmaku culture, UP主 growth	Building audiences on Bilibili with community-first content
🎠 Carousel Growth Engine	TikTok/Instagram carousels, autonomous publishing	Generating and publishing viral carousel content
💼 LinkedIn Content Creator	Personal branding, thought leadership, professional content	LinkedIn growth, professional audience building, B2B content
🛒 China E-Commerce Operator	Taobao, Tmall, Pinduoduo, live commerce	Running multi-platform e-commerce in China
🎥 Kuaishou Strategist	Kuaishou, 老铁 community, grassroots growth	Building authentic audiences in lower-tier markets
🔍 SEO Specialist	Technical SEO, content strategy, link building	Driving sustainable organic search growth
📘 Book Co-Author	Thought-leadership books, ghostwriting, publishing	Strategic book collaboration for founders and experts
🌏 Cross-Border E-Commerce Specialist	Amazon, Shopee, Lazada, cross-border fulfillment	Full-funnel cross-border e-commerce strategy
🎵 Douyin Strategist	Douyin platform, short-video marketing, algorithm	Growing audiences on China's leading short-video platform
🎙️ Livestream Commerce Coach	Host training, live room optimization, conversion	Building high-performing livestream e-commerce operations
🎧 Podcast Strategist	Podcast content strategy, platform optimization	Chinese podcast market strategy and operations
🔒 Private Domain Operator	WeCom, private traffic, community operations	Building enterprise WeChat private domain ecosystems
🎬 Short-Video Editing Coach	Post-production, editing workflows, platform specs	Hands-on short-video editing training and optimization
🔥 Weibo Strategist	Sina Weibo, trending topics, fan engagement	Full-spectrum Weibo operations and growth
🎙️ Global Podcast Strategist	Show positioning, audience growth, monetisation	Podcast launch, platform algorithms, sponsorship, community building
🔮 AI Citation Strategist	AEO/GEO, AI recommendation visibility, citation auditing	Improving brand visibility across ChatGPT, Claude, Gemini, Perplexity
🇨🇳 China Market Localization Strategist	Full-stack China market localization, Douyin/Xiaohongshu/WeChat GTM	Turning trend signals into executable China go-to-market strategies
🎬 Video Optimization Specialist	YouTube algorithm strategy, chaptering, thumbnail concepts	YouTube channel growth, video SEO, audience retention optimization
🏗️ AEO Foundations Architect	AI Engine Optimization infrastructure	llms.txt, AI-aware robots.txt, agent discovery files
🤖 Agentic Search Optimizer	WebMCP & agentic task completion	Making sites usable by AI browsing agents
📧 Email Marketing Strategist	Lifecycle email & deliverability	CRM campaigns, automation, segmentation
📡 Multi-Platform Publisher	One-click Chinese multi-platform publishing	Routing one article to 知乎/小红书/CSDN/B站/公众号/掘金
📣 PR & Communications Manager	PR, media relations & crisis comms	Press releases, thought leadership, reputation

📊 Product Division

Building the right thing at the right time.

Agent	Specialty	When to Use
🎯 Sprint Prioritizer	Agile planning, feature prioritization	Sprint planning, resource allocation, backlog management
🔍 Trend Researcher	Market intelligence, competitive analysis	Market research, opportunity assessment, trend identification
💬 Feedback Synthesizer	User feedback analysis, insights extraction	Feedback analysis, user insights, product priorities
🧠 Behavioral Nudge Engine	Behavioral psychology, nudge design, engagement	Maximizing user motivation through behavioral science
🧭 Product Manager	Full lifecycle product ownership	Discovery, PRDs, roadmap planning, GTM, outcome measurement

🎬 Project Management Division

Keeping the trains running on time (and under budget).

Agent	Specialty	When to Use
🎬 Studio Producer	High-level orchestration, portfolio management	Multi-project oversight, strategic alignment, resource allocation
🐑 Project Shepherd	Cross-functional coordination, timeline management	End-to-end project coordination, stakeholder management
⚙️ Studio Operations	Day-to-day efficiency, process optimization	Operational excellence, team support, productivity
🧪 Experiment Tracker	A/B tests, hypothesis validation	Experiment management, data-driven decisions, testing
👔 Senior Project Manager	Realistic scoping, task conversion	Converting specs to tasks, scope management
📋 Jira Workflow Steward	Git workflow, branch strategy, traceability	Enforcing Jira-linked Git discipline and delivery
📋 Meeting Notes Specialist	Structured meeting summaries	Extracting decisions, action items, open questions

🧪 Testing Division

Breaking things so users don't have to.

Agent	Specialty	When to Use
📸 Evidence Collector	Screenshot-based QA, visual proof	UI testing, visual verification, bug documentation
🔍 Reality Checker	Evidence-based certification, quality gates	Production readiness, quality approval, release certification
📊 Test Results Analyzer	Test evaluation, metrics analysis	Test output analysis, quality insights, coverage reporting
⚡ Performance Benchmarker	Performance testing, optimization	Speed testing, load testing, performance tuning
🔌 API Tester	API validation, integration testing	API testing, endpoint verification, integration QA
🛠️ Tool Evaluator	Technology assessment, tool selection	Evaluating tools, software recommendations, tech decisions
🔄 Workflow Optimizer	Process analysis, workflow improvement	Process optimization, efficiency gains, automation opportunities
♿ Accessibility Auditor	WCAG auditing, assistive technology testing	Accessibility compliance, screen reader testing, inclusive design verification
🎭 Test Automation Engineer	Playwright/Cypress E2E, flake elimination, CI parallelization	Browser test suites, deterministic pipelines, trace-driven failure debugging

🔒 Security Division

Defending the stack — from secure-by-design architecture to breach response.

Agent	Specialty	When to Use
🛡️ Security Architect	Threat modeling, secure-by-design, trust boundaries	System security models, architecture reviews, defense-in-depth
🔐 Application Security Engineer	SDLC security, SAST/DAST, secure code review	Securing the dev lifecycle, code-level vulnerabilities
🗡️ Penetration Tester	Authorized pentests, red team ops, exploitation	Finding exploitable weaknesses before attackers do
☁️ Cloud Security Architect	Zero trust, cloud-native defense-in-depth	Securing cloud infrastructure and architectures
🚨 Incident Responder	DFIR, breach investigation, threat containment	Active breaches, forensics, crisis response
🔍 Threat Intelligence Analyst	Adversary tracking, campaign mapping, ATT&CK	Understanding who's attacking and how
🎯 Threat Detection Engineer	SIEM rules, threat hunting, ATT&CK mapping	Building detection layers and threat hunting
🛡️ Senior SecOps Engineer	Secrets scanning, secure-by-default submissions	Defensive code-level security on every change
📋 Compliance Auditor	SOC 2, ISO 27001, HIPAA, PCI-DSS	Guiding organizations through compliance certification
🛡️ Blockchain Security Auditor	Smart contract audits, exploit analysis	Finding vulnerabilities in contracts before deployment
🔎 AI-Generated Code Security Auditor	Security review of AI/vibe-coded apps	Hardcoded secrets, broken RLS, prompt-injection sinks
🔑 Secrets & Credential Hygiene Engineer	Secrets & credential lifecycle	Detection, vaulting, rotation, leak response

🛟 Support Division

The backbone of the operation.

Agent	Specialty	When to Use
💬 Support Responder	Customer service, issue resolution	Customer support, user experience, support operations
📊 Analytics Reporter	Data analysis, dashboards, insights	Business intelligence, KPI tracking, data visualization
💰 Finance Tracker	Financial planning, budget management	Financial analysis, cash flow, business performance
🏗️ Infrastructure Maintainer	System reliability, performance optimization	Infrastructure management, system operations, monitoring
⚖️ Legal Compliance Checker	Compliance, regulations, legal review	Legal compliance, regulatory requirements, risk management
📑 Executive Summary Generator	C-suite communication, strategic summaries	Executive reporting, strategic communication, decision support

🥽 Spatial Computing Division

Building the immersive future.

Agent	Specialty	When to Use
🏗️ XR Interface Architect	Spatial interaction design, immersive UX	AR/VR/XR interface design, spatial computing UX
💻 macOS Spatial/Metal Engineer	Swift, Metal, high-performance 3D	macOS spatial computing, Vision Pro native apps
🌐 XR Immersive Developer	WebXR, browser-based AR/VR	Browser-based immersive experiences, WebXR apps
🎮 XR Cockpit Interaction Specialist	Cockpit-based controls, immersive systems	Cockpit control systems, immersive control interfaces
🍎 visionOS Spatial Engineer	Apple Vision Pro development	Vision Pro apps, spatial computing experiences
🔌 Terminal Integration Specialist	Terminal integration, command-line tools	CLI tools, terminal workflows, developer tools

🎯 Specialized Division

The unique specialists who don't fit in a box.

Agent	Specialty	When to Use
🎭 Agents Orchestrator	Multi-agent coordination, workflow management	Complex projects requiring multiple agent coordination
🔍 LSP/Index Engineer	Language Server Protocol, code intelligence	Code intelligence systems, LSP implementation, semantic indexing
📥 Sales Data Extraction Agent	Excel monitoring, sales metric extraction	Sales data ingestion, MTD/YTD/Year End metrics
📈 Data Consolidation Agent	Sales data aggregation, dashboard reports	Territory summaries, rep performance, pipeline snapshots
📬 Report Distribution Agent	Automated report delivery	Territory-based report distribution, scheduled sends
🔐 Agentic Identity & Trust Architect	Agent identity, authentication, trust verification	Multi-agent identity systems, agent authorization, audit trails
🔗 Identity Graph Operator	Shared identity resolution for multi-agent systems	Entity deduplication, merge proposals, cross-agent identity consistency
💸 Accounts Payable Agent	Payment processing, vendor management, audit	Autonomous payment execution across crypto, fiat, stablecoins
🌍 Cultural Intelligence Strategist	Global UX, representation, cultural exclusion	Ensuring software resonates across cultures
🗣️ Developer Advocate	Community building, DX, developer content	Bridging product and developer community
🔬 Model QA Specialist	ML audits, feature analysis, interpretability	End-to-end QA for machine learning models
🗃️ ZK Steward	Knowledge management, Zettelkasten, notes	Building connected, validated knowledge bases
🔌 MCP Builder	Model Context Protocol servers, AI agent tooling	Building MCP servers that extend AI agent capabilities
📄 Document Generator	PDF, PPTX, DOCX, XLSX generation from code	Professional document creation, reports, data visualization
⚙️ Automation Governance Architect	Automation governance, n8n, workflow auditing	Evaluating and governing business automations at scale
📚 Corporate Training Designer	Enterprise training, curriculum development	Designing training systems and learning programs
🌱 Personal Growth Mentor	Goal clarity, habit systems, accountability, life strategy	Cross-domain personal development without motivational fluff
🏛️ Government Digital Presales Consultant	China ToG presales, digital transformation	Government digital transformation proposals and bids
⚕️ Healthcare Marketing Compliance	China healthcare advertising compliance	Healthcare marketing regulatory compliance
🎯 Recruitment Specialist	Talent acquisition, recruiting operations	Recruitment strategy, sourcing, and hiring processes
🎓 Study Abroad Advisor	International education, application planning	Study abroad planning across US, UK, Canada, Australia
🔗 Supply Chain Strategist	Supply chain management, procurement strategy	Supply chain optimization and procurement planning
🗺️ Workflow Architect	Workflow discovery, mapping, and specification	Mapping every path through a system before code is written
☁️ Salesforce Architect	Multi-cloud Salesforce design, governor limits, integrations	Enterprise Salesforce architecture, org strategy, deployment pipelines
🇫🇷 French Consulting Market Navigator	ESN/SI ecosystem, portage salarial, rate positioning	Freelance consulting in the French IT market
🇰🇷 Korean Business Navigator	Korean business culture, 품의 process, relationship mechanics	Foreign professionals navigating Korean business relationships
🏗️ Civil Engineer	Structural analysis, geotechnical design, global building codes	Multi-standard structural engineering across Eurocode, ACI, AISC, and more
🎧 Customer Service	Omnichannel support, complaint handling, retention, escalation	Any industry customer support — retail, SaaS, hospitality, finance, logistics
🏥 Healthcare Customer Service	HIPAA-aware patient support, billing, insurance, emergency routing	Healthcare organizations needing compliant, empathetic patient support
🏨 Hospitality Guest Services	Reservations, concierge, complaint recovery, loyalty, events	Hotels, resorts, restaurants, and event venues
🤝 HR Onboarding	Pre-boarding, compliance, benefits enrollment, 30-60-90 day plans	Any company onboarding new hires — from startups to enterprise
🌐 Language Translator	Spanish ↔ English translation, dialect awareness, cultural context	Travel, business, medical, and legal translation needs
⏱️ Legal Billing & Time Tracking	Time capture, billing narratives, IOLTA compliance, collections	Law firms maximizing revenue recovery and billing accuracy
📋 Legal Client Intake	Prospect qualification, conflict screening, consultation scheduling	Law firms converting inquiries into retained clients
⚖️ Legal Document Review	Contract review, risk flagging, version comparison, compliance	Attorney-ready first-pass review across any practice area
🏦 Loan Officer Assistant	Borrower intake, TRID compliance, pipeline tracking, closing coordination	Mortgage and consumer lending teams
🏠 Real Estate Buyer & Seller	Buyer/seller representation, offers, transaction coordination	Residential and investment real estate transactions
🛒 Retail Customer Returns	Return processing, fraud prevention, exchanges, vendor returns	Brick-and-mortar, e-commerce, and omnichannel retail
♟️ Business Strategist	Management-consulting strategy	Competitive analysis, market entry, growth planning
🔄 Change Management Consultant	ADKAR/Kotter/Prosci change	Guiding orgs through transformation & adoption
🧭 Chief of Staff	Executive coordination	Filtering noise, owning processes, routing decisions
🌟 Customer Success Manager	Onboarding, health & retention	QBRs, churn prevention, renewals & expansion
📝 Grant Writer	Grant proposals & funding	LOIs, proposals, budgets for nonprofits/research
🏥 Medical Billing & Coding Specialist	ICD-10/CPT/HCPCS & revenue cycle	Claims, denial management, RCM optimization
💰 Pricing Analyst	Pricing models & margin optimization	Competitor/cost analysis, value-based pricing
💼 Chief Financial Officer	Capital allocation & financial strategy	Treasury, FP&A, M&A finance, investor & board reporting
🌱 ESG & Sustainability Officer	ESG programs & disclosure	Sustainability strategy, decarbonization, reporting
🔐 Data Privacy Officer	GDPR/CCPA privacy compliance	Data mapping, DPIAs, consent, breach response
⚙️ Operations Manager	Lean/Six Sigma operations	Process mapping, capacity planning, KPI governance
🤝 M&A Integration Manager	Post-merger integration	Day 1/100-day plans, synergy tracking, TSA management
🧠 Organizational Psychologist	Team dynamics & culture health	Psychological safety, burnout risk, high-performing teams
⚔️ Strategy Duel Agent	Game theory & the 36 stratagems	Turn-based strategy duels, adversarial scenario simulation
🛡️ FedRAMP & RMF Compliance Engineer	Federal cloud authorization (ATO)	NIST 800-53, FedRAMP Rev5/20x, SSP/POA&M, ConMon, OSCAL
🏺 Codebase Archaeologist	Multi-tool codebase drift audits	Detecting silent drift across Claude/Cursor/Copilot/Windsurf edits
🧾 Resume Tailor	Candidate-side resume optimization	JD mapping, ATS keyword alignment, experience-to-requirement matching
🧡 Aging Parent Care Companion	Family caregiver decision-support	Appointment/medication coordination, care-team comms, caregiver wellbeing (HIPAA-aligned)

💵 Finance Division

Accounting, financial analysis, tax strategy, and investment research specialists.

Agent	Specialty	When to Use
📒 Bookkeeper & Controller	Month-end close, reconciliation, GAAP compliance, internal controls	Day-to-day accounting operations, audit readiness, financial record-keeping
📊 Financial Analyst	Financial modeling, forecasting, scenario analysis, decision support	Three-statement models, variance analysis, data-driven business intelligence
📈 FP&A Analyst	Budgeting, rolling forecasts, variance analysis, business reviews	Annual operating plans, monthly business reviews, strategic resource allocation
🔍 Investment Researcher	Due diligence, portfolio analysis, asset valuation, equity research	Investment thesis development, risk assessment, market research
🏛️ Tax Strategist	Tax optimization, multi-jurisdictional compliance, transfer pricing	Entity structuring, ETR analysis, audit defense, strategic tax planning

🎮 Game Development Division

Building worlds, systems, and experiences across every major engine.

Cross-Engine Agents (Engine-Agnostic)

Agent	Specialty	When to Use
🎯 Game Designer	Systems design, GDD authorship, economy balancing, gameplay loops	Designing game mechanics, progression systems, writing design documents
🗺️ Level Designer	Layout theory, pacing, encounter design, environmental storytelling	Building levels, designing encounter flow, spatial narrative
🎨 Technical Artist	Shaders, VFX, LOD pipeline, art-to-engine optimization	Bridging art and engineering, shader authoring, performance-safe asset pipelines
🔊 Game Audio Engineer	FMOD/Wwise, adaptive music, spatial audio, audio budgets	Interactive audio systems, dynamic music, audio performance
📖 Narrative Designer	Story systems, branching dialogue, lore architecture	Writing branching narratives, implementing dialogue systems, world lore
💰 Economy Designer	Virtual currencies, sources/sinks, monetization modeling, inflation control	Designing in-game economies, balancing F2P monetization, live economy tuning

Unity

Agent	Specialty	When to Use
🏗️ Unity Architect	ScriptableObjects, data-driven modularity, DOTS/ECS	Large-scale Unity projects, data-driven system design, ECS performance work
✨ Unity Shader Graph Artist	Shader Graph, HLSL, URP/HDRP, Renderer Features	Custom Unity materials, VFX shaders, post-processing passes
🌐 Unity Multiplayer Engineer	Netcode for GameObjects, Unity Relay/Lobby, server authority, prediction	Online Unity games, client prediction, Unity Gaming Services integration
🛠️ Unity Editor Tool Developer	EditorWindows, AssetPostprocessors, PropertyDrawers, build validation	Custom Unity Editor tooling, pipeline automation, content validation

Unreal Engine

Agent	Specialty	When to Use
⚙️ Unreal Systems Engineer	C++/Blueprint hybrid, GAS, Nanite constraints, memory management	Complex Unreal gameplay systems, Gameplay Ability System, engine-level C++
🎨 Unreal Technical Artist	Material Editor, Niagara, PCG, Substrate	Unreal materials, Niagara VFX, procedural content generation
🌐 Unreal Multiplayer Architect	Actor replication, GameMode/GameState hierarchy, dedicated server	Unreal online games, replication graphs, server authoritative Unreal
🗺️ Unreal World Builder	World Partition, Landscape, HLOD, LWC	Large open-world Unreal levels, streaming systems, terrain at scale

Godot

Agent	Specialty	When to Use
📜 Godot Gameplay Scripter	GDScript 2.0, signals, composition, static typing	Godot gameplay systems, scene composition, performance-conscious GDScript
🌐 Godot Multiplayer Engineer	MultiplayerAPI, ENet/WebRTC, RPCs, authority model	Online Godot games, scene replication, server-authoritative Godot
✨ Godot Shader Developer	Godot shading language, VisualShader, RenderingDevice	Custom Godot materials, 2D/3D effects, post-processing, compute shaders

Blender

Agent	Specialty	When to Use
🧩 Blender Addon Engineer	Blender Python (`bpy`), custom operators/panels, asset validators, exporters, pipeline automation	Building Blender add-ons, asset prep tools, export workflows, and DCC pipeline automation

Roblox Studio

Agent	Specialty	When to Use
⚙️ Roblox Systems Scripter	Luau, RemoteEvents/Functions, DataStore, server-authoritative module architecture	Building secure Roblox game systems, client-server communication, data persistence
🎯 Roblox Experience Designer	Engagement loops, monetization, D1/D7 retention, onboarding flow	Designing Roblox game loops, Game Passes, daily rewards, player retention
👗 Roblox Avatar Creator	UGC pipeline, accessory rigging, Creator Marketplace submission	Roblox UGC items, HumanoidDescription customization, in-experience avatar shops

📚 Academic Division

Scholarly rigor for world-building, storytelling, and narrative design.

Agent	Specialty	When to Use
🌍 Anthropologist	Cultural systems, kinship, rituals, belief systems	Designing culturally coherent societies with internal logic
🌐 Geographer	Physical/human geography, climate, cartography	Building geographically coherent worlds with realistic terrain and settlements
📚 Historian	Historical analysis, periodization, material culture	Validating historical coherence, enriching settings with authentic period detail
📜 Narratologist	Narrative theory, story structure, character arcs	Analyzing and improving story structure with established theoretical frameworks
🧠 Psychologist	Personality theory, motivation, cognitive patterns	Building psychologically credible characters grounded in research
📊 Statistician	Statistical inference & experiment design	Hypothesis testing, causal inference, sampling, rigorous analysis

🌍 GIS Division

Mapping the Earth, analyzing the built world, and extracting intelligence from geospatial data.

Agent	Specialty	When to Use
🧠 Technical Consultant	GIS strategy, gap analysis, technology roadmaps, digital transformation	Understanding business needs, selecting the right geospatial stack, planning multi-phase GIS programs
🔧 Solution Engineer	Esri + FOSS4G prototype building, PoC delivery, technical feasibility	Building working demos, validating technical approaches, pre-sales support
🖥️ GIS Analyst	Map production, data QC, symbology, layouts, spatial queries	Day-to-day GIS operations, creating publication-ready maps, maintaining data integrity
📦 Spatial Data Engineer	Geospatial ETL, format conversion, CRS reprojection, automated pipelines	Ingesting messy data from any source, building repeatable data transformation pipelines
⚙️ Geoprocessing Specialist	ArcPy, Python Toolbox (.pyt), Model Builder, batch automation	Automating repetitive GIS workflows, building custom geoprocessing tools
✅ GIS QA Engineer	Topology validation, metadata audit, CRS consistency, accuracy assessment	Quality gates before data publication, compliance verification, data integrity audits
🤖 GeoAI/ML Engineer	Feature extraction, object detection, semantic segmentation, land cover classification	Extracting buildings/roads/vehicles from imagery, change detection, environmental monitoring
🏗️ BIM/GIS Specialist	Revit/IFC to GIS, indoor mapping, digital twin architecture, facility management	Smart campus, airport digital twins, indoor navigation, building operations
🏔️ 3D & Scene Developer	Cesium, ArcGIS Scene Viewer, 3D Tiles, point clouds, terrain visualization	3D city scenes, terrain flyovers, point cloud web viewers, OAuth-gated scene sharing
📊 Spatial Data Scientist	Spatial statistics, clustering, regression, interpolation, point pattern analysis	Hotspot detection, spatial modeling, predictive analytics, research-grade analysis
🛸 Drone/Reality Mapping	Photogrammetry, orthomosaic, DTM/DSM, point cloud classification, 3D mesh	Drone survey processing, reality capture, construction monitoring, environmental mapping
🌐 Web GIS Developer	MapLibre GL JS, ArcGIS JS API, Leaflet, real-time dashboards, REST APIs	Building interactive web maps, operational dashboards, real-time data visualization
🎨 Cartography Designer	Color theory, typography, basemap design, visual hierarchy, print and web aesthetics	Making maps beautiful and readable, colorblind-safe palettes, professional map layouts

🏥 Healthcare Division

Building AI agents for regulated clinical and sovereign health contexts.

Agent	Specialty	When to Use
🩺 Clinical Evidence Agent	Evidence standards, validated vs unvalidated claims, diagnostic authority boundaries	Making clinical claims credibly without overstepping into diagnostic authority
🌍 Sovereign Health Systems Agent	Government health mandates, UHC policy, emerging market deployment	Health tech teams operating at the intersection of national health infrastructure and sovereign health policy
🧭 Healthcare Innovation Strategist	Narrative architecture for healthcare founders across investor, regulatory, sovereign, and clinical audiences	Healthcare founders who need to translate clinical and financial complexity into language that moves capital and builds trust

🎯 Real-World Use Cases

Scenario 1: Building a Startup MVP

Your Team:

🎨 Frontend Developer - Build the React app
🏗️ Backend Architect - Design the API and database
🚀 Growth Hacker - Plan user acquisition
⚡ Rapid Prototyper - Fast iteration cycles
🔍 Reality Checker - Ensure quality before launch

Result: Ship faster with specialized expertise at every stage.

Scenario 2: Marketing Campaign Launch

Your Team:

📝 Content Creator - Develop campaign content
🐦 Twitter Engager - Twitter strategy and execution
📸 Instagram Curator - Visual content and stories
🤝 Reddit Community Builder - Authentic community engagement
📊 Analytics Reporter - Track and optimize performance

Result: Multi-channel coordinated campaign with platform-specific expertise.

Scenario 3: Enterprise Feature Development

Your Team:

👔 Senior Project Manager - Scope and task planning
💎 Senior Developer - Complex implementation
🎨 UI Designer - Design system and components
🧪 Experiment Tracker - A/B test planning
📸 Evidence Collector - Quality verification
🔍 Reality Checker - Production readiness

Result: Enterprise-grade delivery with quality gates and documentation.

Scenario 4: Paid Media Account Takeover

Your Team:

📋 Paid Media Auditor - Comprehensive account assessment
📡 Tracking & Measurement Specialist - Verify conversion tracking accuracy
💰 PPC Campaign Strategist - Redesign account architecture
🔍 Search Query Analyst - Clean up wasted spend from search terms
✍️ Ad Creative Strategist - Refresh all ad copy and extensions
📊 Analytics Reporter (Support Division) - Build reporting dashboards

Result: Systematic account takeover with tracking verified, waste eliminated, structure optimized, and creative refreshed — all within the first 30 days.

Scenario 5: Full Agency Product Discovery

Your Team: All 8 divisions working in parallel on a single mission.

See the Nexus Spatial Discovery Exercise -- a complete example where 8 agents (Product Trend Researcher, Backend Architect, Brand Guardian, Growth Hacker, Support Responder, UX Researcher, Project Shepherd, and XR Interface Architect) were deployed simultaneously to evaluate a software opportunity and produce a unified product plan covering market validation, technical architecture, brand strategy, go-to-market, support systems, UX research, project execution, and spatial UI design.

Result: Comprehensive, cross-functional product blueprint produced in a single session. More examples.

Scenario 6: Smart Campus Digital Twin

Your Team:

🧠 Technical Consultant - Define the digital twin strategy: BIM for buildings, GIS for campus, IoT for real-time
🏗️ BIM/GIS Specialist - Convert Revit building models to GIS scene layers, design indoor floor plans
🛸 Drone/Reality Mapping - Fly the campus, generate orthomosaic and 3D mesh for context
🌐 Web GIS Developer - Build the campus dashboard with MapLibre, building layer, and room finder
🏔️ 3D & Scene Developer - Create immersive 3D scene with terrain, buildings, and flyover tour
🤖 GeoAI/ML Engineer - Extract building footprints and tree canopy from drone imagery
✅ GIS QA Engineer - Validate data accuracy, check topology, verify CRS consistency

Result: A campus digital twin that combines BIM detail, drone reality capture, 3D visualization, and web accessibility — delivered by coordinated specialists in a single pipeline.

🤝 Contributing

We welcome contributions! Here's how you can help:

Add a New Agent

Fork the repository
Create a new agent file in the appropriate category
Follow the agent template structure:
- Frontmatter with name, description, color
- Identity & Memory section
- Core Mission
- Critical Rules (domain-specific)
- Technical Deliverables with examples
- Workflow Process
- Success Metrics
Submit a PR with your agent

Improve Existing Agents

Add real-world examples
Enhance code samples
Update success metrics
Improve workflows

Share Your Success Stories

Have you used these agents successfully? Share your story in the Discussions!

📖 Agent Design Philosophy

Each agent is designed with:

🎭 Strong Personality: Not generic templates - real character and voice
📋 Clear Deliverables: Concrete outputs, not vague guidance
✅ Success Metrics: Measurable outcomes and quality standards
🔄 Proven Workflows: Step-by-step processes that work
💡 Learning Memory: Pattern recognition and continuous improvement

🎁 What Makes This Special?

Unlike Generic AI Prompts:

❌ Generic "Act as a developer" prompts
✅ Deep specialization with personality and process

Unlike Prompt Libraries:

❌ One-off prompt collections
✅ Comprehensive agent systems with workflows and deliverables

Unlike AI Tools:

❌ Black box tools you can't customize
✅ Transparent, forkable, adaptable agent personalities

🎨 Agent Personality Highlights

"I don't just test your code - I default to finding 3-5 issues and require visual proof for everything."

-- Evidence Collector (Testing Division)

"You're not marketing on Reddit - you're becoming a valued community member who happens to represent a brand."

-- Reddit Community Builder (Marketing Division)

"Every playful element must serve a functional or emotional purpose. Design delight that enhances rather than distracts."

-- Whimsy Injector (Design Division)

"Let me add a celebration animation that reduces task completion anxiety by 40%"

-- Whimsy Injector (during a UX review)

📊 Stats

🎭 230+ Specialized Agents across every division
📝 10,000+ lines of personality, process, and code examples
⏱️ Months of iteration from real-world usage
🌟 Battle-tested in production environments
💬 50+ requests in first 12 hours on Reddit

🔌 Multi-Tool Integrations

The Agency works natively with Claude Code, and ships conversion + install scripts so you can use the same agents across every major agentic coding tool.

Supported Tools

Claude Code — native .md agents, no conversion needed → ~/.claude/agents/
GitHub Copilot — native .md agents, no conversion needed → ~/.github/agents/ + ~/.copilot/agents/
Antigravity — SKILL.md per agent → ~/.gemini/config/skills/
Gemini CLI -- .md agent files -> ~/.gemini/agents/
OpenCode — .md agent files → .opencode/agents/
Cursor — .mdc rule files → .cursor/rules/
Aider — single CONVENTIONS.md → ./CONVENTIONS.md
Windsurf — single .windsurfrules → ./.windsurfrules
OpenClaw — SOUL.md + AGENTS.md + IDENTITY.md per agent
Qwen Code — .md SubAgent files → ~/.qwen/agents/
Kimi Code — YAML agent specs → ~/.config/kimi/agents/
Codex — TOML custom agents → ~/.codex/agents/
Osaurus -- SKILL.md skills -> ~/.osaurus/skills/
Hermes -- lazy-router plugin -> ~/.hermes/plugins/

⚡ Quick Install

Step 1 -- Generate integration files:

./scripts/convert.sh
# Faster (parallel, output order may vary): ./scripts/convert.sh --parallel

Step 2 -- Install (interactive, auto-detects your tools):

./scripts/install.sh
# Faster (parallel, output order may vary): ./scripts/install.sh --no-interactive --parallel

The installer scans your system for installed tools, shows a checkbox UI, and lets you pick exactly what to install:

  +------------------------------------------------+
  |   The Agency -- Tool Installer                 |
  +------------------------------------------------+

  System scan: [*] = detected on this machine

  [x]  1)  [*]  Claude Code     (claude.ai/code)
  [x]  2)  [*]  Copilot         (~/.github + ~/.copilot)
  [x]  3)  [*]  Antigravity     (~/.gemini/antigravity)
  [ ]  4)  [ ]  Gemini CLI      (~/.gemini/agents)
  [ ]  5)  [ ]  OpenCode        (opencode.ai)
  [ ]  6)  [ ]  OpenClaw        (~/.openclaw/agency-agents)
  [x]  7)  [*]  Cursor          (.cursor/rules)
  [ ]  8)  [ ]  Aider           (CONVENTIONS.md)
  [ ]  9)  [ ]  Windsurf        (.windsurfrules)
  [ ] 10)  [ ]  Qwen Code       (~/.qwen/agents)
  [ ] 11)  [ ]  Kimi Code       (~/.config/kimi/agents)
  [ ] 12)  [ ]  Codex           (~/.codex/agents)
  [ ] 13)  [ ]  Osaurus         (~/.osaurus/skills)
  [ ] 14)  [ ]  Hermes          (~/.hermes/plugins)

  [1-14] toggle   [a] all   [n] none   [d] detected
  [Enter] install   [q] quit

Or install a specific tool directly:

./scripts/install.sh --tool cursor
./scripts/install.sh --tool opencode
./scripts/install.sh --tool openclaw
./scripts/install.sh --tool antigravity
./scripts/install.sh --tool codex
./scripts/install.sh --tool osaurus
./scripts/install.sh --tool hermes

Non-interactive (CI/scripts):

./scripts/install.sh --no-interactive --tool all

Faster runs (parallel) — On multi-core machines, use --parallel so each tool is processed in parallel. Output order across tools is non-deterministic. Works with both interactive and non-interactive install: e.g. ./scripts/install.sh --interactive --parallel (pick tools, then install in parallel) or ./scripts/install.sh --no-interactive --parallel. Job count defaults to nproc (Linux), sysctl -n hw.ncpu (macOS), or 4; override with --jobs N.

./scripts/convert.sh --parallel                    # convert all tools in parallel
./scripts/convert.sh --parallel --jobs 8           # cap parallel jobs
./scripts/install.sh --no-interactive --parallel   # install all detected tools in parallel
./scripts/install.sh --interactive --parallel      # pick tools, then install in parallel
./scripts/install.sh --no-interactive --parallel --jobs 4

Tool-Specific Instructions

Claude Code

Agents are copied directly from the repo into ~/.claude/agents/ -- no conversion needed.

./scripts/install.sh --tool claude-code

Then activate in Claude Code:

Use the Frontend Developer agent to review this component.

See integrations/claude-code/README.md for details.

GitHub Copilot

Agents are copied directly from the repo into ~/.github/agents/ and ~/.copilot/agents/ -- no conversion needed.

./scripts/install.sh --tool copilot

Then activate in GitHub Copilot:

Use the Frontend Developer agent to review this component.

See integrations/github-copilot/README.md for details.

Antigravity (Gemini)

Each agent becomes a skill in ~/.gemini/config/skills/agency-<slug>/.

./scripts/install.sh --tool antigravity

Activate in Gemini with Antigravity:

@agency-frontend-developer review this React component

See integrations/antigravity/README.md for details.

Gemini CLI

Installs as Gemini CLI subagents. On a fresh clone, generate the Gemini agent files before running the installer.

./scripts/convert.sh --tool gemini-cli
./scripts/install.sh --tool gemini-cli

See integrations/gemini-cli/README.md for details.

OpenCode

Agents are placed in .opencode/agents/ in your project root (project-scoped).

cd /your/project
/path/to/agency-agents/scripts/install.sh --tool opencode

Or install globally:

mkdir -p ~/.config/opencode/agents
cp integrations/opencode/agents/*.md ~/.config/opencode/agents/

Activate in OpenCode:

@backend-architect design this API.

See integrations/opencode/README.md for details.

Cursor

Each agent becomes a .mdc rule file in .cursor/rules/ of your project.

cd /your/project
/path/to/agency-agents/scripts/install.sh --tool cursor

Rules are auto-applied when Cursor detects them in the project. Reference them explicitly:

Use the @security-engineer rules to review this code.

See integrations/cursor/README.md for details.

Aider

All agents are compiled into a single CONVENTIONS.md file that Aider reads automatically.

cd /your/project
/path/to/agency-agents/scripts/install.sh --tool aider

Then reference agents in your Aider session:

Use the Frontend Developer agent to refactor this component.

See integrations/aider/README.md for details.

Windsurf

All agents are compiled into .windsurfrules in your project root.

cd /your/project
/path/to/agency-agents/scripts/install.sh --tool windsurf

Reference agents in Windsurf's Cascade:

Use the Reality Checker agent to verify this is production ready.

See integrations/windsurf/README.md for details.

OpenClaw

Each agent becomes a workspace with SOUL.md, AGENTS.md, and IDENTITY.md in ~/.openclaw/agency-agents/.

./scripts/convert.sh --tool openclaw
./scripts/install.sh --tool openclaw

If the openclaw CLI is available, the installer registers each workspace automatically. Run openclaw gateway restart after installation so the new agents are activated.

See integrations/openclaw/README.md for details.

Qwen Code

SubAgents are installed to .qwen/agents/ in your project root (project-scoped).

# Convert and install (run from your project root)
cd /your/project
./scripts/convert.sh --tool qwen
./scripts/install.sh --tool qwen

Usage in Qwen Code:

Reference by name: Use the frontend-developer agent to review this component
Or let Qwen auto-delegate based on task context
Manage via /agents command in interactive mode

📚 Qwen SubAgents Docs

Kimi Code

Agents are converted to Kimi Code CLI format (YAML + system prompt) and installed to ~/.config/kimi/agents/.

# Convert and install
./scripts/convert.sh --tool kimi
./scripts/install.sh --tool kimi

Usage with Kimi Code:

# Use an agent
kimi --agent-file ~/.config/kimi/agents/frontend-developer/agent.yaml

# In a project
kimi --agent-file ~/.config/kimi/agents/frontend-developer/agent.yaml \
     --work-dir /your/project \
     "Review this React component"

See integrations/kimi/README.md for details.

Codex

Each agent is converted into a Codex custom agent TOML file and installed to ~/.codex/agents/.

./scripts/convert.sh --tool codex
./scripts/install.sh --tool codex

Then reference the custom agent by name in Codex:

Use the Frontend Developer agent to review this component.

See integrations/codex/README.md for details.

Regenerating After Changes

When you add new agents or edit existing ones, regenerate all integration files:

./scripts/convert.sh                    # regenerate all (serial)
./scripts/convert.sh --parallel         # regenerate all in parallel (faster)
./scripts/convert.sh --tool codex       # regenerate just one tool
./scripts/convert.sh --tool cursor      # regenerate just one tool

🗺️ Roadmap

Interactive agent selector web tool
Multi-agent workflow examples -- see examples/
Multi-tool integration scripts (Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Qwen Code, Kimi Code, Codex, Osaurus, Hermes)
Video tutorials on agent design
Community agent marketplace
Agent "personality quiz" for project matching
"Agent of the Week" showcase series

🌐 Community Translations & Localizations

Community-maintained translations and regional adaptations. These are independently maintained -- see each repo for coverage and version compatibility.

Language	Maintainer	Link	Notes
🇨🇳 简体中文 (zh-CN)	@jnMetaCode	agency-agents-zh	141 translated agents + 46 China-market originals
🇨🇳 简体中文 (zh-CN)	@dsclca12	agent-teams	Independent translation with Bilibili, WeChat, Xiaohongshu localization
🇧🇷 Português brasileiro (pt-BR)	@jnMetaCode	agency-agents-pt-BR	184 upstream agents translated; Brazil-market PRs welcome
🇷🇺 Русский (ru)	@jnMetaCode	agency-agents-ru	184 upstream agents translated; Russia-market PRs welcome
🇮🇩 Bahasa Indonesia (id)	@jnMetaCode	agency-agents-id	184 upstream agents translated; Indonesia-market PRs welcome
🇸🇦 العربية (ar)	@jnMetaCode	agency-agents-ar	184 upstream agents translated; Arabic-market PRs welcome
🇰🇷 한국어 (ko)	@jnMetaCode	agency-agents-ko	184 upstream agents fully translated; Korea-specific PRs welcome
🇯🇵 日本語 (ja-JP)	@sscodeai	agency-agents-ja	281 Japan-localized agents + 97 Japan-market originals + 27 workflows
🇻🇳 Tiếng Việt (vi-VN)	@rodonguyen	agency-agents	Starter Vietnamese localization focused on README, quick start, and high-use docs

Want to add a translation? Open an issue and we'll link it here.

🔗 Related Resources

awesome-openclaw-agents — Community-maintained OpenClaw agent collection (derived from this repo)

📜 License

MIT License - Use freely, commercially or personally. Attribution appreciated but not required.

🙏 Acknowledgments

What started as a Reddit thread about AI agent specialization has grown into something remarkable — 230+ agents across every division, supported by a community of contributors from around the world. Every agent in this repo exists because someone cared enough to write it, test it, and share it.

To everyone who has opened a PR, filed an issue, started a Discussion, or simply tried an agent and told us what worked — thank you. You're the reason The Agency keeps getting better.

💬 Community

GitHub Discussions: Share your success stories
Issues: Report bugs or request features
Reddit: Join the conversation on r/ClaudeAI
Twitter/X: Share with #TheAgency

🚀 Get Started

Browse the agents above and find specialists for your needs
Copy the agents to ~/.claude/agents/ for Claude Code integration
Activate agents by referencing them in your Claude conversations
Customize agent personalities and workflows for your specific needs
Share your results and contribute back to the community

🎭 The Agency: Your AI Dream Team Awaits 🎭

⭐ Star this repo • 🍴 Fork it • 🐛 Report an issue • ❤️ Sponsor

Made with ❤️ by the community, for the community

nvm-sh/nvm

Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Node Version Manager

Intro

nvm allows you to quickly install and use different versions of node via the command line.

Example:

$ nvm install 24
Now using node v24.14.0 (npm v11.9.0)
$ node -v
v24.14.0
$ nvm use 22
Now using node v22.22.1 (npm v10.9.4)
$ node -v
v22.22.1
$ nvm use 20
Now using node v20.20.1 (npm v10.8.2)
$ node -v
v20.20.1

Simple as that!

About

nvm is a version manager for node.js, designed to be installed per-user, and invoked per-shell. nvm works on any POSIX-compliant shell (sh, dash, ksh, zsh, bash), in particular on these platforms: unix, macOS, and Windows WSL.

Installing and Updating

Install & Update Script

To install or update nvm, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Running either of the above commands downloads a script and runs it. The script clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bashrc, ~/.bash_profile, ~/.zshrc, or ~/.profile). If you find the install script is updating the wrong profile file, set the $PROFILE env var to the profile file’s path, and then rerun the installation script.

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Additional Notes

If the environment variable $XDG_CONFIG_HOME is present, it will place the nvm files there.
You can add --no-use to the end of the above script to postpone using nvm until you manually use it:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" --no-use # This loads nvm, without auto-using the default version

You can customize the install source, directory, profile, and version using the NVM_SOURCE, NVM_DIR, PROFILE, and NODE_VERSION variables. Eg: curl ... | NVM_DIR="path/to/nvm". Ensure that the NVM_DIR does not contain a trailing slash.
The installer can use git, curl, or wget to download nvm, whichever is available.
You can instruct the installer to not edit your shell config (for example if you already get completions via a zsh nvm plugin) by setting PROFILE=/dev/null before running the install.sh script. Here's an example one-line command to do that: PROFILE=/dev/null bash -c 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash'

Installing in Docker

When invoking bash as a non-interactive shell, like in a Docker container, none of the regular profile files are sourced. In order to use nvm, node, and npm like normal, you can instead specify the special BASH_ENV variable, which bash sources when invoked non-interactively.

# Use bash for the shell
SHELL ["/bin/bash", "-o", "pipefail", "-c"]

# Create a script file sourced by both interactive and non-interactive bash shells
ENV BASH_ENV "${HOME}/.bash_env"
RUN touch "${BASH_ENV}"
RUN echo '. "${BASH_ENV}"' >> ~/.bashrc

# Download and install nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | PROFILE="${BASH_ENV}" bash
RUN echo node > .nvmrc
RUN nvm install

Installing in Docker for CICD-Jobs

More robust, works in CI/CD-Jobs. Can be run in interactive and non-interactive containers. See https://github.com/nvm-sh/nvm/issues/3531.

FROM ubuntu:latest
ARG NODE_VERSION=20

# install curl
RUN apt update && apt install curl -y

# install nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

# set env
ENV NVM_DIR=/root/.nvm

# install node
RUN bash -c "source $NVM_DIR/nvm.sh && nvm install $NODE_VERSION"

# set ENTRYPOINT for reloading nvm-environment
ENTRYPOINT ["bash", "-c", "source $NVM_DIR/nvm.sh && exec \"$@\"", "--"]

# set cmd to bash
CMD ["/bin/bash"]

This example defaults to installation of nodejs version 20.x.y. Optionally you can easily override the version with docker build args like:

docker build -t nvmimage --build-arg NODE_VERSION=19 .

After creation of the image you can start container interactively and run commands, for example:

docker run --rm -it nvmimage

root@0a6b5a237c14:/# nvm -v
0.40.6

root@0a6b5a237c14:/# node -v
v19.9.0

root@0a6b5a237c14:/# npm -v
9.6.3

Noninteractive example:

user@host:/tmp/test $ docker run --rm -it nvmimage node -v
v19.9.0
user@host:/tmp/test $ docker run --rm -it nvmimage npm -v
9.6.3

Troubleshooting on Linux

On Linux, after running the install script, if you get nvm: command not found or see no feedback from your terminal after you type command -v nvm, simply close your current terminal, open a new terminal, and try verifying again. Alternatively, you can run the following commands for the different shells on the command line:

bash: source ~/.bashrc

zsh: source ~/.zshrc

ksh: . ~/.profile

These should pick up the nvm command.

Troubleshooting on macOS

Since OS X 10.9, /usr/bin/git has been preset by Xcode command line tools, which means we can't properly detect if Git is installed or not. You need to manually install the Xcode command line tools before running the install script, otherwise, it'll fail. (see #1782)

If you get nvm: command not found after running the install script, one of the following might be the reason:

Since macOS 10.15, the default shell is zsh and nvm will look for .zshrc to update, none is installed by default. Create one with touch ~/.zshrc and run the install script again.
If you use bash, the previous default shell, your system may not have .bash_profile or .bashrc files where the command is set up. Create one of them with touch ~/.bash_profile or touch ~/.bashrc and run the install script again. Then, run . ~/.bash_profile or . ~/.bashrc to pick up the nvm command.
You have previously used bash, but you have zsh installed. You need to manually add these lines to ~/.zshrc and run . ~/.zshrc.
You might need to restart your terminal instance or run . ~/.nvm/nvm.sh. Restarting your terminal/opening a new tab/window, or running the source command will load the command and the new configuration.
If the above didn't help, you might need to restart your terminal instance. Try opening a new tab/window in your terminal and retry.

If the above doesn't fix the problem, you may try the following:

If you use bash, it may be that your .bash_profile (or ~/.profile) does not source your ~/.bashrc properly. You could fix this by adding source ~/<your_profile_file> to it or following the next step below.
Try adding the snippet from the install section, that finds the correct nvm directory and loads nvm, to your usual profile (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).
For more information about this issue and possible workarounds, please refer here

Note For Macs with the Apple Silicon chip, node started offering arm64 arch Darwin packages since v16.0.0 and experimental arm64 support when compiling from source since v14.17.0. If you are facing issues installing node using nvm, you may want to update to one of those versions or later.

Ansible

You can use a task:

- name: Install nvm
  ansible.builtin.shell: >
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
  args:
    creates: "{{ ansible_env.HOME }}/.nvm/nvm.sh"

Verify Installation

To verify that nvm has been installed, do:

command -v nvm

which should output nvm if the installation was successful. Please note that which nvm will not work, since nvm is a sourced shell function, not an executable binary.

Note: On Linux, after running the install script, if you get nvm: command not found or see no feedback from your terminal after you type command -v nvm, simply close your current terminal, open a new terminal, and try verifying again.

Important Notes

If you're running a system without prepackaged binary available, which means you're going to install node or io.js from its source code, you need to make sure your system has a C++ compiler. For OS X, Xcode will work, for Debian/Ubuntu based GNU/Linux, the build-essential and libssl-dev packages work.

Note: nvm also supports Windows in some cases. It should work through WSL (Windows Subsystem for Linux) depending on the version of WSL. It should also work with Git Bash (MSYS) or Cygwin. Otherwise, for Windows, a few alternatives exist, which are neither supported nor developed by us:

Note: nvm does not support Fish either (see #303). Alternatives exist, which are neither supported nor developed by us:

bass allows you to use utilities written for Bash in fish shell
fast-nvm-fish only works with version numbers (not aliases) but doesn't significantly slow your shell startup
plugin-nvm plugin for Oh My Fish, which makes nvm and its completions available in fish shell
nvm.fish - The Node.js version manager you'll adore, crafted just for Fish
fish-nvm - Wrapper around nvm for fish, delays sourcing nvm until it's actually used.

Note: We still have some problems with FreeBSD, because there is no official pre-built binary for FreeBSD, and building from source may need patches; see the issue ticket:

Note: On OS X, if you do not have Xcode installed and you do not wish to download the ~4.3GB file, you can install the Command Line Tools. You can check out this blog post on how to just that:

How to Install Command Line Tools in OS X Mavericks & Yosemite (Without Xcode)

Note: On OS X, if you have/had a "system" node installed and want to install modules globally, keep in mind that:

When using nvm you do not need sudo to globally install a module with npm -g, so instead of doing sudo npm install -g grunt, do instead npm install -g grunt
If you have an ~/.npmrc file, make sure it does not contain any prefix settings (which is not compatible with nvm)
You can (but should not?) keep your previous "system" node install, but nvm will only be available to your user account (the one used to install nvm). This might cause version mismatches, as other users will be using /usr/local/lib/node_modules/* VS your user account using ~/.nvm/versions/node/vX.X.X/lib/node_modules/*

Homebrew installation is not supported. If you have issues with homebrew-installed nvm, please brew uninstall it, and install it using the instructions below, before filing an issue.

Note: If you're using zsh you can easily install nvm as a zsh plugin. Install zsh-nvm and run nvm upgrade to upgrade (you can set NVM_AUTO_USE=true to have it automatically detect and use .nvmrc files).

Note: Git versions before v1.7 may face a problem of cloning nvm source from GitHub via https protocol, and there is also different behavior of git before v1.6, and git prior to v1.17.10 can not clone tags, so the minimum required git version is v1.7.10. If you are interested in the problem we mentioned here, please refer to GitHub's HTTPS cloning errors article.

Git Install

If you have git installed (requires git v1.7.10+):

clone this repo in the root of your user profile
- cd ~/ from anywhere then git clone https://github.com/nvm-sh/nvm.git .nvm
cd ~/.nvm and check out the latest version with git checkout v0.40.6
activate nvm by sourcing it from your shell: . ./nvm.sh

Now add these lines to your ~/.bashrc, ~/.profile, or ~/.zshrc file to have it automatically sourced upon login: (you may have to add to more than one of the above files)

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Manual Install

For a fully manual install, execute the following lines to first clone the nvm repository into $HOME/.nvm, and then load nvm:

export NVM_DIR="$HOME/.nvm" && (
  git clone https://github.com/nvm-sh/nvm.git "$NVM_DIR"
  cd "$NVM_DIR"
  git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`
) && \. "$NVM_DIR/nvm.sh"

Now add these lines to your ~/.bashrc, ~/.profile, or ~/.zshrc file to have it automatically sourced upon login: (you may have to add to more than one of the above files)

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Manual Upgrade

For manual upgrade with git (requires git v1.7.10+):

change to the $NVM_DIR
pull down the latest changes
check out the latest version
activate the new version

(
  cd "$NVM_DIR"
  git fetch --tags origin
  git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`
) && \. "$NVM_DIR/nvm.sh"

Usage

To download, compile, and install the latest release of node, do this:

nvm install node # "node" is an alias for the latest version

To install a specific version of node:

nvm install 14.7.0 # or 16.3.0, 12.22.1, etc

To set an alias:

nvm alias my_alias v14.4.0

Make sure that your alias does not contain any spaces or slashes.

The first version installed becomes the default. New shells will start with the default version of node (e.g., nvm alias default).

You can list available versions using ls-remote:

nvm ls-remote

And then in any new shell just use the installed version:

nvm use node

Or you can just run it:

nvm run node --version

Or, you can run any arbitrary command in a subshell with the desired version of node:

nvm exec 4.2 node --version

You can also get the path to the executable to where it was installed:

nvm which 12.22

In place of a version pointer like "14.7" or "16.3" or "12.22.1", you can use the following special default aliases with nvm install, nvm use, nvm run, nvm exec, nvm which, etc:

node: this installs the latest version of node
iojs: this installs the latest version of io.js
stable: this alias is deprecated, and only truly applies to node v0.12 and earlier. Currently, this is an alias for node.
unstable: this alias points to node v0.11 - the last "unstable" node release, since post-1.0, all node versions are stable. (in SemVer, versions communicate breakage, not stability).
current: the version currently active in this shell (i.e. what node resolves to via $PATH). It is not affected by .nvmrc. Useful when you want to refer to the active version explicitly — e.g. nvm which current always prints the path to the active node, regardless of whether an .nvmrc file is present.

Long-term Support

Node has a schedule for long-term support (LTS) You can reference LTS versions in aliases and .nvmrc files with the notation lts/* for the latest LTS, and lts/argon for LTS releases from the "argon" line, for example. In addition, the following commands support LTS arguments:

nvm install --lts / nvm install --lts=argon / nvm install 'lts/*' / nvm install lts/argon
nvm uninstall --lts / nvm uninstall --lts=argon / nvm uninstall 'lts/*' / nvm uninstall lts/argon
nvm use --lts / nvm use --lts=argon / nvm use 'lts/*' / nvm use lts/argon
nvm exec --lts / nvm exec --lts=argon / nvm exec 'lts/*' / nvm exec lts/argon
nvm run --lts / nvm run --lts=argon / nvm run 'lts/*' / nvm run lts/argon
nvm ls-remote --lts / nvm ls-remote --lts=argon nvm ls-remote 'lts/*' / nvm ls-remote lts/argon
nvm version-remote --lts / nvm version-remote --lts=argon / nvm version-remote 'lts/*' / nvm version-remote lts/argon

Any time your local copy of nvm connects to https://nodejs.org, it will re-create the appropriate local aliases for all available LTS lines. These aliases (stored under $NVM_DIR/alias/lts), are managed by nvm, and you should not modify, remove, or create these files - expect your changes to be undone, and expect meddling with these files to cause bugs that will likely not be supported.

To get the latest LTS version of node and migrate your existing installed packages, use:

nvm install --reinstall-packages-from=current 'lts/*'

Migrating Global Packages While Installing

If you want to install a new version of Node.js and migrate npm packages from a previous version:

nvm install --reinstall-packages-from=node node

This will first use "nvm version node" to identify the current version you're migrating packages from. Then it resolves the new version to install from the remote server and installs it. Lastly, it runs "nvm reinstall-packages" to reinstall the npm packages from your prior version of Node to the new one.

You can also install and migrate npm packages from specific versions of Node like this:

nvm install --reinstall-packages-from=5 6
nvm install --reinstall-packages-from=iojs v4.2

Note that reinstalling packages explicitly does not update the npm version — this is to ensure that npm isn't accidentally upgraded to a broken version for the new node version.

To update npm at the same time add the --latest-npm flag, like this:

nvm install --reinstall-packages-from=default --latest-npm 'lts/*'

or, you can at any time run the following command to get the latest supported npm version on the current node version:

nvm install-latest-npm

If you've already gotten an error to the effect of "npm does not support Node.js", you'll need to (1) revert to a previous node version (nvm ls & nvm use <your latest _working_ version from the ls>), (2) delete the newly created node version (nvm uninstall <your _broken_ version of node from the ls>), then (3) rerun your nvm install with the --latest-npm flag.

Migrating Global Packages Between Installed Versions

--reinstall-packages-from is tied to nvm install. To migrate global npm packages between versions you already have installed, without (re)installing anything, nvm use the destination and run nvm reinstall-packages as a standalone command, pointing at the version you want to copy from:

nvm use 22.22.2
nvm reinstall-packages 22.20.0

This reinstalls all global packages from 22.20.0 into the currently-active version (22.22.2). As with --reinstall-packages-from, the npm version itself is not changed.

Offline Install

If you've previously downloaded a node version (or it's still in the cache), you can install it without any network access using the --offline flag:

nvm install --offline 14.7.0

This resolves versions using only locally installed versions and cached downloads. It will not attempt to download anything. This is useful in air-gapped environments, on planes, or when you want to avoid network latency.

You can combine --offline with --lts to install the latest cached LTS version (as long as LTS aliases have been populated by a prior nvm ls-remote --lts):

nvm install --offline --lts

Default Global Packages From File While Installing

If you have a list of default packages you want installed every time you install a new version, we support that too -- just add the package names, one per line, to the file $NVM_DIR/default-packages. You can add anything npm would accept as a package argument on the command line.

# $NVM_DIR/default-packages

rimraf
object-inspect@1.0.2
stevemao/left-pad

io.js

Warning

io.js was a fork of Node.js, created in 2014 and merged back in 2015. io.js shipped v1, v2, and v3 release lines; post-merge, node.js began releasing with v4.

If you want to install io.js:

nvm install iojs

If you want to install a new version of io.js and migrate npm packages from a previous version:

nvm install --reinstall-packages-from=iojs iojs

The same guidelines mentioned for migrating npm packages in node are applicable to io.js.

System Version of Node

If you want to use the system-installed version of node, you can use the special default alias "system":

nvm use system
nvm run system --version

Listing Versions

If you want to see what versions are installed:

nvm ls

If you want to see what versions are available to install:

nvm ls-remote

Setting Custom Colors

You can set five colors that will be used to display version and alias information. These colors replace the default colors. Initial colors are: g b y r e

Color codes:

r/R = red / bold red

g/G = green / bold green

b/B = blue / bold blue

c/C = cyan / bold cyan

m/M = magenta / bold magenta

y/Y = yellow / bold yellow

k/K = black / bold black

e/W = light grey / white

nvm set-colors rgBcm

Persisting custom colors

If you want the custom colors to persist after terminating the shell, export the NVM_COLORS variable in your shell profile. For example, if you want to use cyan, magenta, green, bold red and bold yellow, add the following line:

export NVM_COLORS='cmgRY'

Suppressing colorized output

nvm help (or -h or --help), nvm ls, nvm ls-remote and nvm alias usually produce colorized output. You can disable colors with the --no-colors option (or by setting the environment variable TERM=dumb):

nvm ls --no-colors
nvm help --no-colors
TERM=dumb nvm ls

Restoring PATH

To restore your PATH, you can deactivate it:

nvm deactivate

Set default node version

To set a default Node version to be used in any new shell, use the alias 'default':

nvm alias default node # this refers to the latest installed version of node
nvm alias default 18 # this refers to the latest installed v18.x version of node
nvm alias default 18.12  # this refers to the latest installed v18.12.x version of node

Use a mirror of node binaries

To use a mirror of the node binaries, set $NVM_NODEJS_ORG_MIRROR:

export NVM_NODEJS_ORG_MIRROR=https://nodejs.org/dist
nvm install node

NVM_NODEJS_ORG_MIRROR=https://nodejs.org/dist nvm install 4.2

To use a mirror of the io.js binaries, set $NVM_IOJS_ORG_MIRROR:

export NVM_IOJS_ORG_MIRROR=https://iojs.org/dist
nvm install iojs-v1.0.3

NVM_IOJS_ORG_MIRROR=https://iojs.org/dist nvm install iojs-v1.0.3

nvm use will not, by default, create a "current" symlink. Set $NVM_SYMLINK_CURRENT to "true" to enable this behavior, which is sometimes useful for IDEs. Note that using nvm in multiple shell tabs with this environment variable enabled can cause race conditions.

Pass Authorization header to mirror

To pass an Authorization header through to the mirror url, set $NVM_AUTH_HEADER

NVM_AUTH_HEADER="Bearer secret-token" nvm install node

.nvmrc

You can create a .nvmrc file containing a node version number (or any other string that nvm understands; see nvm --help for details) in the project root directory (or any parent directory). Afterwards, nvm use, nvm install, and nvm which will use the version specified in the .nvmrc file if no version is supplied on the command line; if no .nvmrc is found either, they exit with status 127. (nvm exec and nvm run follow the same .nvmrc lookup, but currently fall back to the active node if neither resolves — treat that fallback as undefined behavior; pass an explicit version if you need predictable scripting.) If you want the currently active version, pass current explicitly (e.g. nvm which current) — current is not affected by .nvmrc.

For example, to make nvm default to the latest 5.9 release, the latest LTS version, or the latest node version for the current directory:

$ echo "5.9" > .nvmrc

$ echo "lts/*" > .nvmrc # to default to the latest LTS version

$ echo "node" > .nvmrc # to default to the latest version

[NB these examples assume a POSIX-compliant shell version of echo. If you use a Windows cmd development environment, eg the .nvmrc file is used to configure a remote Linux deployment, then keep in mind the "s will be copied leading to an invalid file. Remove them.]

Then when you run nvm use:

$ nvm use
Found '/path/to/project/.nvmrc' with version <5.9>
Now using node v5.9.1 (npm v3.7.3)

Running nvm install will also switch over to the correct version, but if the correct node version isn't already installed, it will install it for you.

$ nvm install
Found '/path/to/project/.nvmrc' with version <5.9>
Downloading and installing node v5.9.1...
Downloading https://nodejs.org/dist/v5.9.1/node-v5.9.1-linux-x64.tar.xz...
#################################################################################### 100.0%
Computing checksum with sha256sum
Checksums matched!
Now using node v5.9.1 (npm v3.7.3)

nvm use et. al. will traverse directory structure upwards from the current directory looking for the .nvmrc file. In other words, running nvm use et. al. in any subdirectory of a directory with an .nvmrc will result in that .nvmrc being utilized.

The contents of a .nvmrc file must contain precisely one <version> (as described by nvm --help) followed by a newline. .nvmrc files may also have comments. The comment delimiter is #, and it and any text after it, as well as blank lines, and leading and trailing white space, will be ignored when parsing.

Key/value pairs using = are also allowed and ignored, but are reserved for future use, and may cause validation errors in the future.

Run npx nvmrc to validate an .nvmrc file. If that tool’s results do not agree with nvm, one or the other has a bug - please file an issue.

Deeper Shell Integration

You can use nvshim to shim the node, npm, and npx bins to automatically use the nvm config in the current directory. nvshim is not supported by the nvm maintainers. Please report issues to the nvshim team.

If you prefer a lighter-weight solution, the recipes below have been contributed by nvm users. They are not supported by the nvm maintainers. We are, however, accepting pull requests for more examples.

Calling `nvm use` automatically in a directory with a `.nvmrc` file

In your profile (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc), add the following to nvm use whenever you enter a new directory:

bash

Put the following at the end of your $HOME/.bashrc:

cdnvm() {
    command cd "$@" || return $?
    nvm_path="$(nvm_find_up .nvmrc | command tr -d '\n')"

    # If there are no .nvmrc file, use the default nvm version
    if [[ ! $nvm_path = *[^[:space:]]* ]]; then

        declare default_version
        default_version="$(nvm version default)"

        # If there is no default version, set it to `node`
        # This will use the latest version on your machine
        if [ $default_version = 'N/A' ]; then
            nvm alias default node
            default_version=$(nvm version default)
        fi

        # If the current version is not the default version, set it to use the default version
        if [ "$(nvm current)" != "${default_version}" ]; then
            nvm use default
        fi
    elif [[ -s "${nvm_path}/.nvmrc" && -r "${nvm_path}/.nvmrc" ]]; then
        declare nvm_version
        nvm_version=$(<"${nvm_path}"/.nvmrc)

        declare locally_resolved_nvm_version
        # `nvm ls` will check all locally-available versions
        # If there are multiple matching versions, take the latest one
        # Remove the `->` and `*` characters and spaces
        # `locally_resolved_nvm_version` will be `N/A` if no local versions are found
        locally_resolved_nvm_version=$(nvm ls --no-colors "${nvm_version}" | command tail -1 | command tr -d '\->*' | command tr -d '[:space:]')

        # If it is not already installed, install it
        # `nvm install` will implicitly use the newly-installed version
        if [ "${locally_resolved_nvm_version}" = 'N/A' ]; then
            nvm install "${nvm_version}";
        elif [ "$(nvm current)" != "${locally_resolved_nvm_version}" ]; then
            nvm use "${nvm_version}";
        fi
    fi
}

alias cd='cdnvm'
cdnvm "$PWD" || exit

This alias would search 'up' from your current directory in order to detect a .nvmrc file. If it finds it, it will switch to that version; if not, it will use the default version.

zsh

This shell function will install (if needed) and nvm use the specified Node version when an .nvmrc is found, and nvm use default otherwise.

Put this into your $HOME/.zshrc to call nvm use automatically whenever you enter a directory that contains an .nvmrc file with a string telling nvm which node to use:

# place this after nvm initialization!
autoload -U add-zsh-hook

load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version
    nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}

add-zsh-hook chpwd load-nvmrc
load-nvmrc

After saving the file, run source ~/.zshrc to reload the configuration with the latest changes made.

fish

This requires that you have bass installed.

# ~/.config/fish/functions/nvm.fish
function nvm
  bass source ~/.nvm/nvm.sh --no-use ';' nvm $argv
end

# ~/.config/fish/functions/nvm_find_nvmrc.fish
function nvm_find_nvmrc
  bass source ~/.nvm/nvm.sh --no-use ';' nvm_find_nvmrc
end

# ~/.config/fish/functions/load_nvm.fish
function load_nvm --on-variable="PWD"
  set -l default_node_version (nvm version default)
  set -l node_version (nvm version)
  set -l nvmrc_path (nvm_find_nvmrc)
  if test -n "$nvmrc_path"
    set -l nvmrc_node_version (nvm version (cat $nvmrc_path))
    if test "$nvmrc_node_version" = "N/A"
      nvm install (cat $nvmrc_path)
    else if test "$nvmrc_node_version" != "$node_version"
      nvm use $nvmrc_node_version
    end
  else if test "$node_version" != "$default_node_version"
    echo "Reverting to default Node version"
    nvm use default
  end
end

# ~/.config/fish/config.fish
# You must call it on initialization or listening to directory switching won't work
load_nvm > /dev/stderr

Running Tests

Tests are written in Urchin. Install Urchin (and other dependencies) like so:

npm install

There are slow tests and fast tests. The slow tests do things like install node and check that the right versions are used. The fast tests fake this to test things like aliases and uninstalling. From the root of the nvm git repository, run the fast tests like this:

npm run test/fast

Run the slow tests like this:

npm run test/slow

Run all of the tests like this:

npm test

Nota bene: Avoid running nvm while the tests are running.

Environment variables

nvm exposes the following environment variables:

NVM_DIR - nvm's installation directory.
NVM_BIN - where node, npm, and global packages for the active version of node are installed.
NVM_INC - node's include file directory (useful for building C/C++ addons for node).
NVM_CD_FLAGS - used to maintain compatibility with zsh.
NVM_RC_VERSION - version from .nvmrc file if being used.

Additionally, nvm modifies PATH, and, if present, MANPATH and NODE_PATH when changing versions.

The following environment variables can be set to configure nvm install:

NVM_NO_SOURCE_FALLBACK - when 1, a failed binary download aborts instead of silently falling back to a (much slower) from-source compile; the persistent equivalent of the -b flag, and mutually exclusive with -s.
NVM_INSTALL_LOCK_TIMEOUT - seconds to wait for a concurrent install of the same version to finish before giving up (default 600). On timeout, nvm prints the lock path so a lock left behind by a killed install can be removed.
NVM_INSTALL_LOCK_STALE - minutes after which an install lock is assumed abandoned and stolen automatically; 0 (the default) never steals.

nvm install <version> takes a per-version advisory lock (a directory under $NVM_DIR/.cache/locks), so two shells installing the same version at once cannot corrupt its version directory; installs of different versions never block each other.

Bash Completion

To activate, you need to source bash_completion:

[[ -r $NVM_DIR/bash_completion ]] && \. $NVM_DIR/bash_completion

Put the above sourcing line just below the sourcing line for nvm in your profile (.bashrc, .bash_profile).

Usage

nvm:

$ nvm Tab

alias               deactivate          install             list-remote         reinstall-packages  uninstall           version
cache               exec                install-latest-npm  ls                  run                 unload              version-remote
current             help                list                ls-remote           unalias             use                 which

nvm alias:

$ nvm alias Tab

default      iojs         lts/*        lts/argon    lts/boron    lts/carbon   lts/dubnium  lts/erbium   node         stable       unstable

$ nvm alias my_alias Tab

v10.22.0       v12.18.3      v14.8.0

nvm use:

$ nvm use Tab

my_alias        default        v10.22.0       v12.18.3      v14.8.0

nvm uninstall:

$ nvm uninstall Tab

my_alias        default        v10.22.0       v12.18.3      v14.8.0

Compatibility Issues

nvm will encounter some issues if you have some non-default settings set. (see #606) The following are known to cause issues:

Inside ~/.npmrc:

prefix='some/path'

Environment Variables:

$NPM_CONFIG_PREFIX
$PREFIX

Shell settings:

set -e

Installing nvm on Alpine Linux

In order to provide the best performance (and other optimizations), nvm will download and install pre-compiled binaries for Node (and npm) when you run nvm install X. The Node project compiles, tests and hosts/provides these pre-compiled binaries which are built for mainstream/traditional Linux distributions (such as Debian, Ubuntu, CentOS, RedHat et al).

Alpine Linux, unlike mainstream/traditional Linux distributions, is based on BusyBox, a very compact (~5MB) Linux distribution. BusyBox (and thus Alpine Linux) uses a different C/C++ stack to most mainstream/traditional Linux distributions - musl. This makes binary programs built for such mainstream/traditional incompatible with Alpine Linux, thus we cannot simply nvm install X on Alpine Linux and expect the downloaded binary to run correctly - you'll likely see "...does not exist" errors if you try that.

There is a -s flag for nvm install which requests nvm download Node source and compile it locally.

If installing nvm on Alpine Linux is still what you want or need to do, you should be able to achieve this by running the following from your Alpine Linux shell, depending on which version you are using:

Alpine Linux 3.13+

apk add -U curl bash ca-certificates openssl ncurses coreutils python3 make gcc g++ libgcc linux-headers grep util-linux binutils findutils
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Alpine Linux 3.5 - 3.12

apk add -U curl bash ca-certificates openssl ncurses coreutils python2 make gcc g++ libgcc linux-headers grep util-linux binutils findutils
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Note: Alpine 3.5 can only install NodeJS versions up to v6.9.5, Alpine 3.6 can only install versions up to v6.10.3, Alpine 3.7 installs versions up to v8.9.3, Alpine 3.8 installs versions up to v8.14.0, Alpine 3.9 installs versions up to v10.19.0, Alpine 3.10 installs versions up to v10.24.1, Alpine 3.11 installs versions up to v12.22.6, Alpine 3.12 installs versions up to v12.22.12, Alpine 3.13 & 3.14 install versions up to v14.20.0, Alpine 3.15 & 3.16 install versions up to v16.16.0 (These are all versions on the main branch). Alpine 3.5 - 3.12 required the package python2 to build NodeJS, as they are older versions to build. Alpine 3.13+ requires python3 to successfully build newer NodeJS versions, but you can use python2 with Alpine 3.13+ if you need to build versions of node supported in Alpine 3.5 - 3.15, you just need to specify what version of NodeJS you need to install in the package install script.

The Node project has some desire but no concrete plans (due to the overheads of building, testing and support) to offer Alpine-compatible binaries.

As a potential alternative, @mhart (a Node contributor) has some Docker images for Alpine Linux with Node and optionally, npm, pre-installed.

Uninstalling / Removal

Manual Uninstall

To remove nvm manually, execute the following:

First, use nvm unload to remove the nvm command from your terminal session and delete the installation directory:

$ nvm_dir="${NVM_DIR:-~/.nvm}"
$ nvm unload
$ rm -rf "$nvm_dir"

Edit ~/.bashrc (or other shell resource config) and remove the lines below:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[[ -r $NVM_DIR/bash_completion ]] && \. $NVM_DIR/bash_completion

Docker For Development Environment

To make development and testing work easier we supply a Dockerfile for development usage. It's based on an Ubuntu base image prepared with essential and useful tools for nvm development. To build the docker image of the environment, do a Docker build at the root of nvm repository:

$ docker build -t nvm-dev .

This will package your current nvm working copy with our pre-defined development environment into a Docker image named nvm-dev. After the build you should see it appear in the list of images:

$ docker images

REPOSITORY         TAG                 IMAGE ID            CREATED             SIZE
nvm-dev            latest              9ca4c57a97d8        7 days ago          650 MB

To start and enter a container based on this image:

$ docker run -h nvm-dev -it nvm-dev

nvm@nvm-dev:~/.nvm$

It takes several minutes to build the image and the image size is about 650MB, so it's not suitable for production usage.

For more information and documentation about Docker, please refer to its official website and documentation:

Problems

If you try to install a node version and the installation fails, be sure to run nvm cache clear to delete cached node downloads, or you might get an error like the following:

curl: (33) HTTP server doesn't seem to support byte ranges. Cannot resume.
Where's my sudo node? Check out #43
After the v0.8.6 release of node, nvm tries to install from binary packages. But in some systems, the official binary packages don't work due to incompatibility of shared libs. In such cases, use -s option to force install from source:

nvm install -s 0.8.6

If setting the default alias does not establish the node version in new shells (i.e. nvm current yields system), ensure that the system's node PATH is set before the nvm.sh source line in your shell profile (see #658)

macOS Troubleshooting

nvm node version not found in vim shell

If you set node version to a version other than your system node version nvm use 6.2.1 and open vim and run :!node -v you should see v6.2.1 if you see your system version v0.12.7. You need to run:

sudo chmod ugo-x /usr/libexec/path_helper

WSL Troubleshooting

If you've encountered this error on WSL-2:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload  Total   Spent    Left  Speed
0     0    0     0    0     0      0      0 --:--:--  0:00:09 --:--:--     0curl: (6) Could not resolve host: raw.githubusercontent.com

It may be due to your antivirus, VPN, or other reasons.

Where you can ping 8.8.8.8 while you can't ping google.com

This could simply be solved by running this in your root directory:

sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "[network]" > /etc/wsl.conf'
sudo bash -c 'echo "generateResolvConf = false" >> /etc/wsl.conf'
sudo chattr +i /etc/resolv.conf

This deletes your resolv.conf file that is automatically generated when you run WSL, creates a new file and puts nameserver 8.8.8.8, then creates a wsl.conf file and adds [network] and generateResolveConf = false to prevent auto-generation of that file.

You can check the contents of the file by running:

cat /etc/resolv.conf

Maintainers

Currently, the sole maintainer is @ljharb - more maintainers are quite welcome, and we hope to add folks to the team over time. Governance will be re-evaluated as the project evolves.

Project Support

Only the latest version (v0.40.6 at this time) is supported.

Enterprise Support

If you are unable to update to the latest version of nvm, our partners provide commercial security fixes for all unsupported versions:

HeroDevs Never-Ending Support

License

See LICENSE.md.

Copyright notice

Copyright OpenJS Foundation and nvm contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. The OpenJS Foundation | Terms of Use | Privacy Policy | Bylaws | Code of Conduct | Trademark Policy | Trademark List | Cookie Policy

0xNyk/council-of-high-intelligence

Structured multi-perspective deliberation for hard decisions. Run full councils, focused triads, or duo debates across Claude Code, Codex, Gemini CLI, and OpenCode.

Council of High Intelligence

Structured multi-perspective deliberation for decisions that deserve more than one reasoning path.

Claude Code · Codex · Gemini CLI · OpenCode

The council assigns a hard question to deliberately different analytical personas, keeps their first positions independent, forces direct disagreement, and returns a verdict that preserves unresolved questions, dissent, kill criteria, and the next concrete action.

Try a council

Claude Code users can install the plugin directly:

/plugin marketplace add 0xNyk/council-of-high-intelligence
/plugin install council@council-of-high-intelligence

Then convene the full council, a faster panel, or a two-member dialectic:

/council Should we open-source our agent framework?
/council --quick Should we add caching here?
/council --duo Should we use microservices or a monolith?

For Codex, Gemini CLI, or OpenCode, clone once and use the matching installer flag:

git clone https://github.com/0xNyk/council-of-high-intelligence.git
cd council-of-high-intelligence

./install.sh --codex-only
./install.sh --gemini-only
./install.sh --opencode-only

Restart the target client after installation. The command remains /council on every supported host.

Use it for the decision boundary

Good council questions have material downside, competing values, incomplete evidence, or an irreversible choice. Write down the decision, constraints, evidence, reversibility, and deadline before adding personas.

The field notes distinguish facts from inference, assumptions, and unknowns. They also make it harder to use a long deliberation as decoration for a decision already made.

When to use something smaller

Use a direct answer or primary documentation for factual lookups.
Run an experiment when the choice is cheap and reversible.
Use --quick when cross-examination will not change the outcome.
Use --duo when one tension matters more than broad coverage.
Do not convene a council to manufacture support for a preferred answer.

Choose a mode

Mode	Shape	Use it when
Full	Independent analysis, cross-examination, final stance, synthesis	Stakes are high and competing frames need contact
Quick	Restate, rapid analysis, final positions	The decision needs breadth but not a full adversarial round
Duo	Opening positions, direct response, final statements	One polarity defines the decision

/council --full What is the right pricing model?
/council --quick --triad shipping Should we release today?
/council --duo --members torvalds,ada Is this abstraction worth it?

Named triads select three relevant lenses without assembling the whole council:

/council --triad strategy Where is our defensible advantage?
/council --triad risk What could make this launch irreversible?
/council --triad ai-product Which capability belongs in the product?

Available domains include architecture, strategy, ethics, debugging, risk, shipping, product, founder, ai, ai-product, ai-safety, decision, systems, uncertainty, design, economics, and bias. The canonical routing table lives in SKILL.md.

What the protocol protects

The full protocol has a fixed round budget. Members first restate the problem, analyze blind, cross-examine other positions, declare a final stance, and then enter synthesis. Enforcement checks look for premature agreement, repeated claims, missing dissent, and unsupported confidence.

Verdicts lead with what remains unresolved. A recommendation is paired with acceptable compromises, kill criteria, and one concrete next step. When the weighted tally remains split, the result returns that split to the user instead of turning it into prose consensus.

Evidence labels separate:

FACT: directly supported by supplied or retrieved evidence;
INFERENCE: follows from evidence but is not directly observed;
ASSUMPTION: required for the argument and still unverified;
UNKNOWN: missing information that could change the decision.

Track the outcome

A verdict is useful only if it can be checked later. Before acting, record the prediction, owner, review date, and evidence that would change the recommendation. At the checkpoint, mark the result confirmed, revised, reversed, or inconclusive instead of rewriting the original rationale.

The 18 lenses

Members are analytical instruments, not impersonation claims. Each persona has a grounding protocol, a method, known blind spots, and a structured response contract.

Member	Primary lens	Useful counterweight
Aristotle	Categories and structure	Lao Tzu on emergence and excess structure
Socrates	Assumption destruction	Feynman on reconstruction from first principles
Sun Tzu	Terrain and adversarial strategy	Aurelius on internal control and moral cost
Ada Lovelace	Formal systems and abstraction	Machiavelli on incentives and informal power
Marcus Aurelius	Resilience and moral clarity	Sun Tzu on external competition
Machiavelli	Power and incentives	Ada on formal consistency
Lao Tzu	Non-action and emergence	Aristotle on explicit categories
Richard Feynman	Explanation and empirical debugging	Socrates on the premise itself
Linus Torvalds	Shipping and maintainability	Meadows on system-level consequences
Miyamoto Musashi	Timing and decisive action	Torvalds on acting before the ideal moment
Alan Watts	Reframing and false problems	Torvalds on concrete implementation
Andrej Karpathy	Empirical ML behavior	Sutskever on frontier risk
Ilya Sutskever	Scaling and AI safety	Karpathy on observation and iteration
Daniel Kahneman	Cognitive bias	Feynman on explicit causal reasoning
Donella Meadows	Feedback loops and high-impact interventions	Torvalds on local fixes
Charlie Munger	Inversion and model lattices	Aristotle on single-system classification
Nassim Taleb	Tail risk and fragility	Karpathy on smooth empirical trends
Dieter Rams	User clarity and restraint	Ada on what can be formalized

The repository stores each member contract under agents/. Custom panels can use --members, named triads, or the classic, exploration-orthogonal, and execution-lean profiles documented in SKILL.md.

Multi-provider routing

The detection script checks which supported providers are available, then the coordinator distributes seats across them. Polarity pairs are separated when possible so a single model family does not play both sides of a disagreement.

Provider path	Detection
Native host subagents	Available through the active supported client
OpenAI	`codex` executable
Google	`gemini` executable
Ollama	`ollama` executable
NVIDIA NIM	`NVIDIA_API_KEY`
Cursor	`cursor-agent` executable or configured login

Preview routing without running a council:

/council --dry-route --triad decision Should we accept this acquisition offer?

Use --no-auto-route to keep native-host defaults. Use --models <path> with a copy of configs/provider-model-slots.example.yaml for an explicit seat map. Provider failure is reported before the seat falls back to the native host.

Installation reference

./install.sh                         # Claude Code
./install.sh --codex                 # Claude Code + Codex
./install.sh --codex-only            # Codex only
./install.sh --gemini                # Claude Code + Gemini CLI
./install.sh --gemini-only           # Gemini CLI only
./install.sh --opencode              # Claude Code + OpenCode
./install.sh --opencode-only         # OpenCode only
./install.sh --copy-configs          # Include provider-routing templates
./install.sh --dry-run               # Preview writes

Custom target directories are supported through --claude-dir, --codex-dir, --gemini-dir, and --opencode-dir. Run ./install.sh --help for the current contract.

Verify the checkout

./scripts/council-simulation-checklist.sh
./install.sh --dry-run --codex
./install.sh --dry-run --gemini
./install.sh --dry-run --opencode

The checklist validates persona structure, host-protocol parity, routing configuration, execution checkpoints, verdict fields, and installer behavior. Use the demo session pack to exercise full, quick, and duo modes.

Repository map

SKILL.md                    canonical coordinator protocol
SKILL.codex.md              Codex host mirror
SKILL.gemini.md             Gemini CLI host mirror
SKILL.opencode.md           OpenCode host mirror
agents/                     18 grounded persona contracts
configs/                    provider and model-routing examples
demos/                      sample sessions and verdict template
scripts/                    detection, conversion, and validation tools
assets/                     brand system and README visuals
install.sh                  multi-host installer

Protocol changes start in SKILL.md and must remain behaviorally aligned with each host mirror. See CONTRIBUTING.md for the required checks and review contract. Security reports belong in SECURITY.md, not a public issue.

Project links

License

eugr/spark-vllm-docker

Docker configuration for running VLLM on dual DGX Sparks

vLLM Docker Optimized for DGX Spark (single or multi-node)

This repository contains the Docker configuration and startup scripts to run vLLM on DGX Spark, from a single node to multi-node clusters using Ray or vLLM's native PyTorch distributed mode. It supports InfiniBand/RDMA (NCCL), custom environment configuration, and high-performance model loading through fastsafetensors and InstantTensor. Cluster setup supports direct connections between dual Sparks, QSFP/RoCE switch configurations, and 3-node mesh configurations.

While it was primarily developed to support multi-node inference, it works just as well on single-node setups.

If you point an AI agent at this repository to prepare a host or run a recipe, use the operational agent runbook. Agent-assisted repository changes use the separate development guide; AGENTS.md routes agents to the appropriate guide.

DISCLAIMER

This repository is not affiliated with NVIDIA or their subsidiaries. This is a community effort aimed to help DGX Spark users to set up and run the most recent versions of vLLM on Spark cluster or single nodes.

By default, build-and-copy.sh pulls the tested nightly runner image from DockerHub: eugr/spark-vllm:latest. Nightly images are built and tested on multiple models in both cluster and solo configuration before latest is advanced. We will expand the selection of models we test in the pipeline, but since vLLM is a rapidly developing platform, some things may break.

Selecting --exp-b12x without local-build flags or customizations pulls the separately tested eugr/spark-vllm-b12x:latest image and tags it as vllm-node-b12x.

If you want to build only the runner from precompiled vLLM and FlashInfer wheels, specify --use-wheels. This option never falls back to compiling missing wheels: if a wheel cannot be downloaded or found locally, the command stops with an error. To build the latest vLLM from the main branch, use --rebuild-vllm; to target a specific repository, release, or commit, set --vllm-repo and/or --vllm-ref.

Similarly, --rebuild-flashinfer, --flashinfer-ref, and --apply-flashinfer-pr control the FlashInfer build and force the local build path.

QUICK START SHORTCUT

If you are here to run DeepSeek V4 Flash (07/31 version), follow these instructions, otherwise skip to the next section.

Before you start, make sure you connect your Sparks together and enable passwordless SSH as described in our Networking Guide. You can also check out NVIDIA's Connect Two Sparks Playbook, but using our guide is the best way to get started. The guide includes instructions for 3-node Spark mesh clusters.

Check out locally. Do it on the head node of the cluster. This will build the image, download and distribute the model and launch the cluster.

git clone https://github.com/eugr/spark-vllm-docker.git
cd spark-vllm-docker
./run-recipe.sh recipes/deepseek-v4-flash-0731.yaml --setup

REGULAR QUICK START

Build

Check out locally. If using DGX Spark cluster, do it on the head node.

git clone https://github.com/eugr/spark-vllm-docker.git
cd spark-vllm-docker

Prepare the container image.

If you have only one DGX Spark:

./build-and-copy.sh

On DGX Spark cluster:

Make sure you connect your Sparks together and enable passwordless SSH as described in our Networking Guide. You can also check out NVIDIA's Connect Two Sparks Playbook, but using our guide is the best way to get started. The guide includes instructions for 3-node Spark mesh clusters.

Then run the following command to pull, tag, and distribute the image across the cluster.

./build-and-copy.sh -c --copy-parallel

The default image preparation speed depends mostly on your Internet connection and whether eugr/spark-vllm:latest is already present locally.

For slower internet connections it can be faster to build from the precompiled wheels by using --use-wheels parameter. An initial build speed depends on your Internet connection speed and whether the base image is already present on your machine. After base image pull, the build should take only 2-3 minutes.

If --use-wheels, --rebuild-vllm, --rebuild-flashinfer, or another build customization is used, the script keeps the local wheel-based runner path. --use-wheels by itself only downloads or reuses precompiled wheels; source compilation occurs only for a dependency explicitly selected by a source-build flag. Full source rebuilds can take 20-40 minutes, but subsequent builds are faster.

Run

On a single node:

launch-cluster.sh supports solo mode, which is now a recommended way to run the container on a single Spark:

./launch-cluster.sh --solo exec \
  vllm serve \
    QuantTrio/Qwen3-VL-30B-A3B-Instruct-AWQ \
    --port 8000 --host 0.0.0.0 \
    --gpu-memory-utilization 0.8 \
    --load-format fastsafetensors

To publish the server port instead of using host networking, pass the Docker port mapping before exec:

./launch-cluster.sh --solo -p 8000:8000 exec \
  vllm serve \
    QuantTrio/Qwen3-VL-30B-A3B-Instruct-AWQ \
    --port 8000 --host 0.0.0.0

On a cluster

It's recommended to download the model on one node and distribute across the cluster using ConnectX interconnect prior to launching. This is to avoid re-downloading the model from the Internet on every node in the cluster.

This repository provides a convenience script, hf-download.sh. The following command will download the model and distribute it across the cluster using autodiscovery.

./hf-download.sh QuantTrio/MiniMax-M2-AWQ -c --copy-parallel

To launch the model:

./launch-cluster.sh exec vllm serve \
  QuantTrio/MiniMax-M2-AWQ \
  --port 8000 --host 0.0.0.0 \
  --gpu-memory-utilization 0.8 \
  -tp 2 \
  --max-model-len 128000 \
  --load-format fastsafetensors \
  --enable-auto-tool-choice --tool-call-parser minimax_m2 \
  --reasoning-parser minimax_m2

The launcher will use the number of nodes required by the parallelism flags. In a 2-node cluster, this command uses both nodes; in a larger configured cluster, extra nodes are not utilized. Do not pass --distributed-executor-backend, --nnodes, --node-rank, --master-addr, --master-port, or --headless to vllm serve; launch-cluster.sh supplies the correct backend and per-node multiprocessing arguments automatically.

NOTE: do not use --load-format fastsafetensors if you are loading models that would take >0.85 of available RAM (without KV cache) as it may result in out of memory situation.

Also: You can use other vLLM containers with the launch script as long as they have bash available. The launcher clears image entrypoints by default, to prevent containers such as vllm-openai to start vLLM before all necessary initialization is complete. However, it's recommended to build the container using this repository for best compatibility and most up-to-date features.

IMPORTANT

You may want to prune your build cache every once in a while, especially if you've been using these container builds since the beginning.

You can check the build cache size by running:

docker system df

To prune the cache for the first time or if you notice unusually big cache size, use:

docker builder prune

Don't do it every time you rebuild, because it will slow down compilation times.

For periodic maintenance, I recommend using a filter: docker builder prune --filter until=72h

CHANGELOG

2026-08-12

PyTorch 2.13 and CUTLASS DSL 4.7

Regular and B12X builds now use PyTorch 2.13.0, torchvision 0.28.0, torchaudio 2.11.0, and CUTLASS DSL 4.7.0.

2026-08-11

Nemotron 3.5 Lightning recipe

Added a recipe for NVIDIA's Nemotron 3.5 Lightning with DSpark and 1M context.

Quick start:

git pull
./hf-download.sh nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4 # add -c for cluster
./hf-download.sh nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4-DSpark # speculator model; add -c for cluster
./run-recipe.sh recipes/nemotron-3.5-lightning.yaml --solo

2026-08-06

GLM-5.2 NVFP4 8x Spark cluster recipe

Added the cluster-only recipes/8x-spark-cluster/glm-5.2-nvfp4.yaml recipe for serving nvidia/GLM-5.2-NVFP4. Requires 8x nodes. The recipe uses the vllm-node-b12x image.

./run-recipe.sh recipes/8x-spark-cluster/glm-5.2-nvfp4.yaml

2026-08-03

New B12X image

Added --exp-b12x (alias: --experimental-b12x) as an alternative version built from a fork by Luke Alonso. This fork supports a collection of experimental high-performance B12X kernels for sm12x architecture.

Since it is built from a forked vLLM branch, it will be supported in parallel to the main ("regular") build, at least for the time being.

Specifying --exp-b12x without arguments will pull eugr/spark-vllm-b12x:latest from Dockerhub, which is now built and tested together with the main image by CI pipeline on nightly basis (if there are any updates to the source branch or B12X).

Add --rebuild-vllm to compile from the source.

The preset defaults the image tag to vllm-node-b12x; an explicit -t still takes precedence. Additional vLLM changes can be layered onto the preset with one or more --apply-vllm-pr flags. PRs are applied from the upstream vLLM repository, not from Luke's fork! If any PRs are specified, the script will build from the source, not prebuilt images.

vLLM wheels are not published for this build, but it will reuse published Flashinfer wheels if you build from the source (unless --rebuild-flashinfer is specified).

For now, we have only one recipe using this build, with more to come.

DeepSeek V4 Flash 0731 B12X cluster recipe

Added the cluster-only deepseek-v4-flash-0731 recipe for serving deepseek-ai/DeepSeek-V4-Flash-0731 on a dual DGX Spark cluster. The recipe requires B12X container (vllm-node-b12x) that can be pulled by using ./build-and-copy.sh --exp-b12x -c (or just allow the recipe system to pull it for you). See details on b12x build above.

./run-recipe.sh deepseek-v4-flash-0731

2026-07-30

Inkling Small NVFP4 support

Added the support for thinkingmachines/Inkling-Small-NVFP4. It requires at least dual DGX Spark setup.

./run-recipe.sh inkling-small-nvfp4

Add --setup on the first run to prepare the container and download and distribute the model.

Official vLLM image support with earlyoom, InstantTensor, and SciPy

mods/use-official-vllm now installs earlyoom, InstantTensor, and SciPy in addition to the compatibility packages needed by other mods. This makes launch-cluster.sh --earlyoom, --load-format instanttensor, and SciPy-based functionality available when launching official vLLM images such as vllm-openai. The Python package install pins the image's existing Torch packages so the CUDA-enabled build is not replaced during dependency resolution.

Repeatable Docker volume mappings

launch-cluster.sh and run-recipe.sh now accept repeatable -v / --volume mappings using Docker's local_path:container_path syntax. In cluster mode, each mapping is applied to every launched node.

./launch-cluster.sh --solo \
  -v "$PWD/models:/models" \
  exec vllm serve /models/qwen3.6-35b-a4b-nvfp4 ...

2026-07-14

Custom vLLM repositories and PyTorch versions

build-and-copy.sh can now build vLLM from a fork with --vllm-repo. Custom repositories bypass the shared upstream Git checkout cache, force a vLLM source build, and suppress the Dockerfile's upstream preset PRs unless --apply-preset-vllm-prs is explicitly requested.

--torch-version, --torchvision-version, and --torchaudio-version select the packages installed in both the source-build environment and final runner image. The defaults are PyTorch 2.13.0, torchvision 0.28.0, and torchaudio 2.11.0, matching current upstream vLLM CUDA requirements.

Builds from any ref in local-inference-lab/vllm also clone and build the master ref of lukealonso/b12x automatically. The repository produces the b12x distribution. The source layer is refreshed on every applicable runner build so a previously cached clone cannot hide newer upstream commits. Only the locally built B12X wheel is installed. Its CUTLASS DSL metadata is adjusted to the image-wide 4.7.0 pin before installation. The checked-out commit is recorded at /workspace/b12x-source-commit in the image. B12X kernels remain JIT-compiled at runtime; building its Python wheel does not add another CUDA compilation phase to the image build.

2026-07-10

Optional earlyoom monitor

Runner images now include earlyoom, and launch-cluster.sh --earlyoom can run it as the container foreground process instead of sleep infinity. This keeps the existing launcher flow, where Ray and vLLM are started with docker exec, while allowing the container to monitor low host memory continuously. run-recipe.py and run-recipe.sh pass the same --earlyoom and --earlyoom-args options through to the launcher.

The default policy is conservative and absolute-memory based: -M 524288,102400 -s 100 -r 60. That sends SIGTERM when available memory drops below 512 MiB, escalates to SIGKILL below 100 MiB, does not wait for swap to fill before acting, and prints one memory report per minute. You can override the default per launch with --earlyoom-args or set VLLM_SPARK_EARLYOOM_ARGS.

Build and runtime compatibility updates

--gpu-arch now also drives the NCCL NVCC_GENCODE build argument, so non-default local builds compile NCCL for the same target architecture as Torch and FlashInfer.

The source-build KV-cache cleanup is now embedded directly in the Dockerfile, while mods/kv-cache-prealloc-cleanup keeps only the runtime policy tweaks.

mods/gpu-mem-util-gb was refreshed against current vLLM memory profiling code so fixed-GiB GPU memory reservations continue to work with the newer startup path.

2026-07-02

Prebuilt runner image by default

build-and-copy.sh now pulls prebuilt eugr/spark-vllm:latest by default and tags it locally as vllm-node or the tag requested with -t. The latest tag points at the latest tested nightly image. The prebuilt image is updated at the same time as prebuilt wheels by the CI pipeline, so they all stay in sync.

Use --use-wheels to keep the previous wheel-based runner build path. Build customization flags such as --exp-mxfp4, non-default --gpu-arch, --vllm-ref, --flashinfer-ref, rebuild/download flags, and PR application flags also keep the local build path. --tf5 remains a tag-compatibility alias and pulls the prebuilt image as vllm-node-tf5.

Copy now checks the image ID locally and on each remote host before saving the image. Hosts that already have the same image ID are skipped, and docker save is skipped entirely when every target is already current. --no-build still skips image preparation and only copies an already-local tag when needed.

2026-07-01

No-Ray is now the default multi-node backend

launch-cluster.sh and run-recipe.sh now default to no-Ray multi-node launches. Use --ray to opt into Ray; Ray mode ensures vLLM commands include --distributed-executor-backend ray when they omit it. --no-ray remains accepted for compatibility in multi-node launches.

Build and dependency updates

We now use NCCL main branch and include new experimental vLLM Rust frontend in the builds. DeepGEMM now tracks the nv_dev branch.

Transformers 5 flag deprecation

--tf5, --pre-tf, and --pre-transformers are now deprecated compatibility aliases. They no longer override dependency resolution; they only preserve the legacy default image tag. Recipes that previously used vllm-node-tf5 now use the standard vllm-node image.

Recipe updates

Added the gemma4-26b-a4b-nvfp4 recipe, reverted the Qwen3.6-35B-A3B-NVFP4 recipes to --kv-cache-dtype fp8, and cleaned up stale TF5 build args from affected recipes.

2026-06-22

Deepseek V4 Flash support

Support and a recipe for Deepseek V4 Flash has been added based on a newly merged vLLM PR. Please note that this PR requires the DeepGEMM nv_dev branch, which is not present in default vLLM builds, but included in this community build.

To run DSV4F you will need a Spark cluster (2 or more nodes).

To run:

git pull
./build-and-copy.sh -c
./hf-download.sh deepseek-ai/DeepSeek-V4-Flash -c
./run-recipe.sh deepseek-v4-flash --no-ray

DeepGEMM support added

vLLM now uses NVIDIA branch for DeepGEMM that includes support for sm12x GPU family, including DGX Spark. Please note that it is currently not compatible with NVRTC compiler, so DG_JIT_USE_NVRTC has been turned off for new builds.

MiniMax AWQ Weight-Shape Loader Workaround

Added a Dockerfile-level workaround for a vLLM nightly regression where compressed-tensors MoE weight_shape metadata is treated as a scalar during load, causing affected MoE quantized models to fail with shape '[]' is invalid for input of size 2.

2026-06-18

KV Cache Preallocation Cleanup Mod & Updated Qwen3.5-397B recipe for dual Sparks

Added KV cache preallocation cleanup for source-built vLLM wheels, which clears cached CUDA allocator memory before vLLM sizes and allocates KV cache blocks. The dual-node Qwen3.5-397B INT4 AutoRound recipe also applies mods/kv-cache-prealloc-cleanup after mods/gpu-mem-util-gb for its model-specific memory policy tweaks.

The same recipe now keeps the 108 GiB startup reservation, sets VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=0, and uses a manual 2.25 GiB KV-cache allocation to bypass vLLM's conservative profiler-derived KV budget. The source build handles profiling-only graph-pool cleanup before KV-cache sizing, while the recipe mod makes the env var skip CUDA graph memory profiling entirely and allows the fixed-GiB reservation argument to coexist with --kv-cache-memory-bytes for this model to load. This may result in a bit of swap to be used to offload unused resources, so make sure swap is enabled.

Added recipes for nvidia/Qwen3.6-35B-A3B-NVFP4

Added recipes for NVIDIA's mixed-precision quant for Qwen3.6-35B model. It has a higher precision and an improved performance compared to the earlier NVFP4 quants.

Use:

qwen3.6-35b-a3b-nvfp4 to run with MTP on
qwen3.6-35b-a3b-nvfp4-no-mtp to run without MTP.

2026-06-10

DiffusionGemma Recipes and Mod

Added day0 support for Google DeepMind's DiffusionGemma model via mods/diffusiongemma. Check out NVIDIA blog for details!

Added four solo-only DiffusionGemma recipes:

diffusion-gemma-bf16-thinking for google/diffusiongemma-26B-A4B-it with thinking enabled.
diffusion-gemma-bf16 for google/diffusiongemma-26B-A4B-it with thinking disabled.
diffusion-gemma-nvfp4-thinking for nvidia/diffusiongemma-26B-A4B-it-NVFP4 with thinking enabled.
diffusion-gemma-nvfp4 for nvidia/diffusiongemma-26B-A4B-it-NVFP4 with thinking disabled.

The non-thinking variants still keep --reasoning-parser gemma4, since these models can emit Gemma4 channel markers even when thinking is disabled.

Example:

./hf-download.sh google/diffusiongemma-26B-A4B-it
./run-recipe.sh diffusion-gemma-bf16-thinking --solo

`run-recipe.sh` Launch Flag Passthrough

run-recipe.sh now passes additional launch-cluster.sh flags through when running recipes: --apply-mod, -p / --publish, and --keep-entrypoint.

Port publishing is still solo-only, matching launch-cluster.sh behavior.

2026-06-09

Recipe Memory Defaults

Raised the default gpu_memory_utilization from 0.7 to 0.8 across the main single-node and two-node recipes to match the current vLLM memory allocation behavior.

2026-06-07

Docker Base Image Compatibility

The default CUDA base image was changed to nvidia/cuda:13.0.2-devel-ubuntu24.04 for broader host compatibility.

The Dockerfile also now passes --allow-change-held-packages when installing the custom NCCL Debian packages, avoiding apt failures when replacing held CUDA/NCCL packages during image builds.

2026-06-06

MiniMax Multi-Node Regression Workaround

Added a targeted Dockerfile patch that disables the MiniMax QK RMSNorm CUDA IPC fused path introduced by vLLM PR #43410. The fused path can fail when tensor parallelism spans DGX Spark nodes; the workaround preserves MiniMax multi-node TP while avoiding a full upstream revert.

2026-06-03

Solo Port Publishing

launch-cluster.sh now supports Docker-style -p / --publish port mappings in solo mode. When port publishing is used, the launcher switches from host networking to Docker bridge networking for that solo container.

Example:

./launch-cluster.sh --solo -p 8000:8000 exec vllm serve ...

2026-05-29

Wheel Freshness Detection

Improved build-and-copy.sh wheel freshness checks so newer locally built wheels are not overwritten just because their filenames differ from the latest release assets. The script now compares local wheel mtimes against remote release asset timestamps before deciding to download. Also switched from using GitHub API to regular HTTP checks to avoid throttling.

`gpu-mem-util-gb` Patch Refresh

Refreshed mods/gpu-mem-util-gb so it applies against newer vLLM CacheConfig code after upstream line/context drift.

2026-05-28

StepFun Step 3.7 Flash Support

Added support for StepFun Step 3.7 Flash multimodal model.

Requires at least 2 Sparks in a cluster. Both FP8 and NVFP4 checkpoints are supported. FP8 requires more memory, so using NVFP4 is recommended.

Update the repo and build a fresh container first:

git pull
./build-and-copy.sh --cleanup -c

To run NVFP4 version:

Download the model:

./hf-download.sh stepfun-ai/Step-3.7-Flash-NVFP4 -c

Run:

./run-recipe.sh step-3.7-flash-nvfp4 --no-ray

To run FP8 version:

Download the model:

./hf-download.sh stepfun-ai/Step-3.7-Flash-FP8 -c

Run:

./run-recipe.sh step-3.7-flash-fp8 --no-ray

Please note that --no-ray is required for FP8 to fit with full context!

`use-official-vllm` NCCL Workaround

Updated mods/use-official-vllm to also handle the NCCL load-order bug tracked in vllm-project/vllm#42354. When both the pip-installed nvidia/nccl/lib/libnccl.so.2 and system libnccl2 are present, the mod redirects the pip-installed NCCL path to the system /usr/lib soname, matching the manual workaround that fixes multi-node DGX Spark hangs.

Use it with official vLLM images before starting the model:

./launch-cluster.sh -t vllm/vllm-openai:latest \
  --apply-mod mods/use-official-vllm \
  exec vllm serve ...

Torch Pinning During Wheel Install

Pinned the already-installed CUDA torch build via uv --override when installing locally built wheels and final runtime dependencies in both Dockerfiles. This prevents transitive dependencies from re-resolving torch to a CPU wheel during image builds.

2026-05-22

New Mod: `use-official-vllm`

Added mods/use-official-vllm, a prerequisite mod for applying patches inside official vLLM Docker containers (e.g. vllm-openai). Official containers do not ship git, which several mods require. This mod installs git via apt-get if it is not already present.

Apply it before any other mod that requires git:

./launch-cluster.sh -t vllm/vllm-openai:latest \
  --apply-mod mods/use-official-vllm \
  --apply-mod mods/gpu-mem-util-gb \
  exec vllm serve ...

`gpu-mem-util-gb` Updated for Latest vLLM Main

Updated mods/gpu-mem-util-gb patch to apply cleanly against the current vLLM main branch. The mod now checks for git at startup and prints a hint to apply mods/use-official-vllm first if git is missing (relevant when using official vLLM containers).

2026-05-18

NCCL Updated to NVIDIA `v2.30u1`

The Dockerfile now builds NCCL from NVIDIA's v2.30u1 branch instead of the custom NCCL fork. This branch incorporates all features of the custom fork and is based on the latest NCCL release. The networking guide's NCCL test commands have been updated to use the same branch for 3-node mesh clusters.

2026-05-14

Default Entrypoint Clearing

launch-cluster.sh now clears the Docker image entrypoint by default when starting idle cluster containers. This allows images with server-style entrypoints, such as vllm-openai, to work with the same cluster launcher flow. Use --keep-entrypoint to preserve the image entrypoint.

2026-05-10

Qwen3.5-397B Recipe Memory Updates

Updated Qwen3.5-397B AutoRound recipes to reduce OOM risk. The dual-node recipe now uses standard fractional --gpu-memory-utilization, and the 3-node pipeline-parallel recipe uses InstantTensor loading with lower memory pressure.

2026-05-06

Qwen3.6-35B-A3B-FP8 Recipes

Added qwen3.6-35b-a3b-fp8 and qwen3.6-35b-a3b-fp8-dflash recipes plus a dedicated Qwen3.6 chat-template mod. The DFlash recipe has prefix caching disabled because it caused accuracy issues.

2026-04-29

Gemma4 Recipe Fixes and Experimental b12x Mod

The Gemma4-26B-A4B recipe now uses safetensors loading and no longer applies the obsolete tool parser mod by default.

2026-04-25

MiniMax-M2.7-AWQ Recipe

Added minimax-m2.7-awq, a cluster-only MiniMax M2.7 AWQ recipe using cyankiwi/MiniMax-M2.7-AWQ-4bit.

2026-04-14

Added --load-format instanttensor support to vLLM - thanks @SeraphimSerapis. An experimental option for now, but allows for faster loading than the current fastsafetensors default. You need to rebuild the container to start using the option, but you don't have to trigger the source build.

2026-04-12

Drop-caches mod for Qwen3.5-397B

Updated Qwen3.5-397B recipe (for dual node configuration) to use the new mod mods/drop-caches which clears filesystem caches every minute while the container is running, resolving fastsafetensors getting stuck during loading and a few other bugs when operating close to max memory limit.

2026-04-11

Pinned PyTorch Version

Pinned PyTorch to version 2.11.0 (previously using nightly builds) to fix incompatibility with transformers 5.x and avoid torch version mismatch in builds.

2026-04-02

A new recipe for Gemma4-26B-A4B in "on-the-fly" FP8 quantization:

Single Spark:

./run-recipe.sh gemma4-26b-a4b --solo

Dual Sparks:

./run-recipe.sh gemma4-26b-a4b --no-ray

2026-03-31

Flags to specify Flashinfer ref and apply PRs

build-and-copy.sh gains two new flags that mirror the existing vLLM equivalents:

--flashinfer-ref <ref> — build FlashInfer from a specific commit SHA, branch, or tag instead of main. Forces a local FlashInfer build (skips prebuilt wheel download).
--apply-flashinfer-pr <pr-num> — fetch and apply a FlashInfer GitHub PR patch before building. Can be specified multiple times. Forces a local FlashInfer build.

Both flags are incompatible with --exp-mxfp4.

Default image tag in `build-and-copy.sh`

build-and-copy.sh now automatically sets a sensible default image tag when -t is not specified:

--tf5 / --pre-tf - deprecated compatibility flag; normal build, tag defaults to vllm-node-tf5
--exp-mxfp4 - tag defaults to vllm-node-mxfp4
in all other cases - tag defaults to vllm-node (no change)

An explicit -t <tag> always takes precedence.

Support for 3-node mesh setups

Added initial support for setups where 3 Sparks are connected in a ring-like mesh without an additional switch. See Networking Guide for instructions on how to connect and set up networking in such cluster.

Autodiscover function in both launch-cluster.sh and run-recipe.sh now can detect mesh setups and configure parameters accordingly.

You can try running a model on all 3 nodes in pipeline-parallel configuration using the following recipe:

./run-recipe.sh --discover # force mesh discovery
./run-recipe.sh recipes/3x-spark-cluster/qwen3.5-397b-int4-autoround.yaml --setup --no-ray --force-build # you can drop --setup and --force-build on subsequent calls

Please note that --tensor-parallel-size 3 or -tp 3 is not supported by any commonly used model, so the only two viable options to utilize all three nodes for a single model are:

--pipeline-parallel 3 will let you run a model that can't fit on dual Sparks, but without additional speed improvements (total throughtput may improve though).
--data-parallel 3 (possibly with --enable-expert-parallel) will let you run a model that can fit on a single Spark, but allow for better concurrency.

You can also run models with --tensor-parallel 2 in a 3-node configuration - in this case only first two nodes (from autodiscovery/.env or from the CLI parameters) will be utilized.

GB10 Verification During Node Discovery

Node discovery now confirms each SSH-reachable peer is a GB10 system before adding it to the cluster: Only hosts reporting NVIDIA GB10 are included. This prevents accidentally adding non-Spark machines that happen to be on the same subnet.

Separate COPY_HOSTS Discovery

Autodiscover now determines the host list used for image and model distribution separately from CLUSTER_NODES:

Non-mesh: COPY_HOSTS mirrors CLUSTER_NODES (no change in behaviour).
Mesh: scans the direct IB-attached enp1s0f0np0 and enp1s0f1np1 interfaces (not the OOB ETH interface), so large file transfers use the faster direct InfiniBand path.

COPY_HOSTS is saved to .env and respected by build-and-copy.sh, hf-download.sh, and run-recipe.py.

Interactive Configuration Save in `autodiscover.sh`

autodiscover.sh now handles .env creation with a guided interactive flow, replacing the previous logic in run-recipe.py:

Runs automatically when .env is absent.
Asks per-node confirmation for both CLUSTER_NODES and COPY_HOSTS.
Skips if .env already exists (use --setup to force).

run-recipe.py no longer contains its own .env-save prompt — it delegates entirely to autodiscover.sh.

`--setup` Flag in `launch-cluster.sh` and `build-and-copy.sh`

Both scripts now accept --setup to force a full autodiscovery run and overwrite the existing .env:

./launch-cluster.sh --setup exec vllm serve ...
./build-and-copy.sh --setup -c

This is equivalent to the existing --setup in run-recipe.sh.

`--config` Flag

hf-download.sh, build-and-copy.sh and launch-cluster.sh now accept --config <file> to load a custom .env configuration file. COPY_HOSTS from the config is used for model distribution:

./hf-download.sh QuantTrio/MiniMax-M2-AWQ --config /path/to/cluster.env -c --copy-parallel

Parallelism-Aware Node Trimming

launch-cluster.sh now parses -tp / --tensor-parallel-size, -pp / --pipeline-parallel-size, and -dp / --data-parallel-size from the exec command or launch script and adjusts the active node count accordingly — for both Ray and no-Ray modes.

If fewer nodes are needed than configured, only the required nodes get containers started (excess nodes are left idle).
If more nodes are needed than available, an error is raised before anything starts.

Note: Command requires 2 node(s) (tp=2 * pp=1 * dp=1); using 2 of 3 configured node(s).
Error: Command requires 4 nodes (tp=4 * pp=1 * dp=1) but only 3 node(s) are configured.

No flags required — the check is automatic whenever parallelism arguments are present in the command.

2026-03-18

`--master-port` / `--head-port` Parameter

Added --master-port (synonym: --head-port) to both launch-cluster.sh and run-recipe.sh to configure the port used for cluster coordination:

In Ray mode: sets the Ray head node port (previously hardcoded to 6379)
In No-Ray mode: sets the PyTorch distributed --master-port passed to vLLM

Default is 29501.

./launch-cluster.sh --master-port 29501 --no-ray exec vllm serve ...
./run-recipe.sh qwen3.5-122b-fp8 --no-ray --master-port 29501

`--network` Parameter in Build Arguments

Added --network <name> to build-and-copy.sh to allow using host networking during builds. Thanks @apairmont for the PR.

2026-03-17

EXPERIMENTAL Intel/Qwen3.5-397B-A17B-int4-AutoRound Recipe

You can run full 397B Qwen3.5 model on just two Sparks with vision and full context, however you need to make sure your Sparks don't run anything extra that can take a lot of RAM. That means that you don't want to log into the graphical interface or use remote desktop. Connect to the head node via ssh.

Alternatively, you can run in non-graphical mode (runlevel 3) by using sudo systemctl isolate multi-user.target to switch (you can use sudo systemctl set-default graphical.target to switch back to graphical mode), however this is known to reduce performance a bit.

You can run the model with the following command on the head node:

./run-recipe.sh qwen3.5-397b-int4-autoround.yaml --no-ray

Please, note --no-ray is necessary to fit full context. It also improves inference speed by ~1 t/s. By default it will try to allocate 108 GiB for vLLM on each node. You can change this by changing gpu_memory_utilization in the recipe or passing --gpu-mem; this recipe maps that value to --gpu-memory-utilization-gb, so it is GiB rather than a percentage.

KNOWN ISSUES:

The current firmware may cause sudden shutdown event on one or both Sparks during heavy inference. If you have this issue, you will need to lower GPU clock frequency on the affected unit(s), e.g. sudo nvidia-smi -lgc 200,2150. This command will reduce max GPU frequency to 2150 MHz. You can play with higher values to see what works for you (default is 2411 MHz, but can boost to 3000 MHz). Please note that this setting only survives until the next reboot, but can be applied at any time.
You will need to use the new --no-ray argument to fit full context.
If the model gets stuck loading weights, clearing the cache on both nodes can "unstuck" it. Use sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches' to clear the cache.

Major Cluster Orchestration Refactoring

Significantly refactored the internal cluster startup logic in launch-cluster.sh:

Removed the standalone run-cluster-node.sh script; its logic is now fully integrated into launch-cluster.sh.
Ray head/worker startup, environment variable injection, and launch script distribution are now handled by launch-cluster.sh directly.
Worker containers are started with proper per-node environment variables (VLLM_HOST_IP, NCCL_SOCKET_IFNAME, etc.) injected via docker run/docker exec instead of relying on .bashrc.
You will now be able to run other vLLM containers without applying use-ngc-vllm mod (current version is just an empty stub).

No-Ray Multi-Node Mode

Added --no-ray flag to launch-cluster.sh to run multi-node vLLM clusters without Ray, using PyTorch's native distributed backend instead. It slightly improves inference performance for most models and reduces memory requirements.

./launch-cluster.sh --no-ray exec vllm serve ...

--no-ray is incompatible with --solo (which already runs without Ray).

`run-recipe.sh` No-Ray Mode and Extended Flag Passthrough

run-recipe.sh now supports --no-ray flag for running multi-node inference without Ray (uses PyTorch distributed backend instead):

./run-recipe.sh qwen3.5-122b-fp8 --no-ray

The following launch-cluster.sh flags are now also passed through from run-recipe.sh: --master-port, --name, --eth-if, --ib-if, -j, --no-cache-dirs, --non-privileged, --mem-limit-gb, --mem-swap-limit-gb, --pids-limit, --shm-size-gb.

Nemotron-3-Nano-NVFP4 Switched to Marlin Backend

The nemotron-3-nano-nvfp4 recipe has been updated to use the Marlin backend for better performance and reliability (until Flashinfer fully supports NVFP4 on sm121).

2026-03-12

Experimental `--gpu-memory-utilization-gb` Mod

Added a new mod mods/gpu-mem-util-gb that adds a --gpu-memory-utilization-gb flag to vLLM, allowing you to specify GPU memory reservation in GiB instead of as a fraction. This is particularly useful on DGX Spark's unified memory architecture where available memory changes dynamically.

./launch-cluster.sh --apply-mod mods/gpu-mem-util-gb exec vllm serve ... \
  --gpu-memory-utilization-gb 110

Cannot be used simultaneously with --kv-cache-memory-bytes.

Qwen3.5-397B INT4-AutoRound TP=4 Recipe (4× Spark Cluster)

Added recipes/4x-spark-cluster/qwen3.5-397b-int4-autoround.yaml for running Intel/Qwen3.5-397B-A17B-int4-AutoRound across 4 DGX Spark nodes with tensor parallelism (TP=4).

Benchmarked at ~37 tok/s single-user, ~103 tok/s aggregate (4 concurrent users).

Includes a new mod mods/fix-qwen35-tp4-marlin that resolves a Marlin kernel constraint (MIN_THREAD_N=64) that breaks certain projection layers at TP=4.

Note: Requires NVIDIA driver 580.x. Driver 590.x has a CUDAGraph capture deadlock on GB10 unified memory.

./run-recipe.sh 4x-spark-cluster/qwen3.5-397b-int4-autoround

Thanks @sonusflow for the contribution.

Nemotron-3-Super-120B NVFP4 Recipe

Added a new recipe nemotron-3-super-nvfp4 for running nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4 with Marlin kernels. Supports both solo and cluster modes. Includes a custom reasoning parser (super_v3_reasoning_parser.py) fetched from the model repository. Supports both dual and single Spark configurations.

./run-recipe.sh nemotron-3-super-nvfp4

2026-03-11

Qwen3-Coder-Next INT4-AutoRound Recipe

Added a new recipe qwen3-coder-next-int4-autoround for running Intel/Qwen3-Coder-Next-int4-AutoRound. Supports single Spark only (use with --solo switch), since split weights are too small for Marlin kernel.

./run-recipe.sh qwen3-coder-next-int4-autoround --solo

2026-03-06

`-e/--env` Passthrough in `run-recipe.py`

run-recipe.sh now accepts one or more -e VAR=VALUE flags to pass environment variables directly to the container, mirroring the existing behaviour of launch-cluster.sh.

./run-recipe.sh qwen3.5-122b-int4-autoround --solo -e HF_TOKEN="$HF_TOKEN"

Unsloth Chat Template for Qwen3.5

Added a new mod mods/fix-qwen3.5-chat-template that applies the Unsloth chat template to Qwen3.5 models for better compatibility with modern clients. The template is now included in the qwen3.5-122b-fp8, qwen3.5-122b-int4-autoround, and qwen3.5-35b-a3b-fp8 recipes.

Fix Shell Quoting for Exec Command Arguments

Fixed shell quoting for exec command arguments in launch-cluster.sh and run-recipe.py to correctly handle arguments containing spaces or special characters.

2026-03-05

Qwen3.5-35B-A3B-FP8 Recipe

Added a new recipe qwen3.5-35b-a3b-fp8 for running Qwen3.5-35B-A3B in FP8 format.

./run-recipe.sh qwen3.5-35b-a3b-fp8

4× Spark Cluster Recipes

Added a recipes/4x-spark-cluster/ subdirectory with recipes optimised for a 4-node Spark cluster:

minimax-m2.5 — MiniMax M2.5 on 4× Spark
qwen3.5-397b-a17B-fp8 — Qwen3.5-397B-A17B in FP8 on 4× Spark

More Robust Wheels Check Before Download

Improved the wheels availability check in build-and-copy.sh to be more reliable when deciding whether to download remote wheels.

2026-03-04

Prebuilt vLLM Wheels via GitHub Releases

build-and-copy.sh automatically downloads prebuilt vLLM wheels from the GitHub releases for wheel-based runner builds. It does not implicitly fall back to a source build.

The download logic mirrors the FlashInfer behaviour:

If prebuilt wheels are available and newer than any locally cached version, they are downloaded automatically.
If the download fails (e.g. no network, release not found, GPU arch not supported), the script reuses an existing local wheel when available; otherwise it exits and identifies the explicit source-build flag.
--rebuild-vllm, --vllm-ref, or --apply-vllm-pr skip the download entirely and force a local build.

No new flags are required — the download happens transparently.

All prebuilt wheels are now tested with multiple models in both solo and cluster configuration as a part of automated deployment pipeline which will now run nightly. The wheels are released only if they pass all the tests and no significant performance regressions are detected.

Qwen3.5-122B-FP8 Recipe

Added a new recipe qwen3.5-122b-fp8 for running Qwen3.5-122B in FP8 format.

./run-recipe.sh qwen3.5-122b-fp8

2026-03-02

Qwen3.5-122B-INT4-Autoround Support

Added support for Intel/Qwen3.5-122B-A10B-int4-AutoRound model with a new mod mods/fix-qwen3.5-autoround that fixes a ROPE syntax error.

Recipe available at recipes/qwen3.5-122b-int4-autoround.yaml.

2026-02-26

Daemon Mode Improvements

You can now use daemon mode (both solo and in the cluster) when exec action is specified.
Piping exec command to docker logs when running in daemon mode.

2026-02-25

HF_HOME Support

Added support for using $HF_HOME environment variable as huggingface cache directory.

Intel/Qwen3-Coder-Next-INT4-Autoround Mod

Added a new mod for Intel/Qwen3-Coder-Next-INT4-Autoround model support: mods/fix-qwen3-next-autoround

2026-02-21

Minimax Reasoning Parser Update

Changed reasoning parser in Minimax for better compatibility with modern clients (like coding tools).

2026-02-18

Completely Redesigned Build Process

build-and-copy.sh automatically downloads prebuilt FlashInfer wheels from the GitHub releases for wheel-based runner builds. It does not implicitly fall back to a source build.

The download logic:

If prebuilt wheels are available and newer than any locally cached version, they are downloaded automatically.
If the download fails (e.g. no network, release not found, GPU arch is not compatible), the script reuses an existing local wheel when available; otherwise it exits and suggests --rebuild-flashinfer.
--rebuild-flashinfer skips the download entirely and forces a fresh local build.

No new flags are required - the download happens transparently unless --rebuild-flashinfer is specified.

Wheels are cached by component and profile under ./.wheel-cache for subsequent reuse.

--rebuild-flashinfer will force FlashInfer rebuild from the flashinfer main branch.
--rebuild-vllm will force vLLM rebuild from vLLM main branch or specific commit in --vllm-ref.

Please, note that specifying --vllm-ref or --apply-vllm-pr will force vLLM rebuild every time.

2026-02-17

Non-Privileged Mode Support

Added --non-privileged flag to launch-cluster.sh for running containers without full privileged access while maintaining RDMA/InfiniBand functionality:

Replaces --privileged with --cap-add=IPC_LOCK
Replaces --ipc=host with --shm-size=64g (configurable via --shm-size-gb)
Exposes RDMA devices via --device=/dev/infiniband
Adds resource limits: memory (110GB), memory+swap (120GB), pids (4096)

Example usage:

./launch-cluster.sh --non-privileged exec vllm serve ...
./launch-cluster.sh --non-privileged --mem-limit-gb 120 --shm-size-gb 64 exec vllm serve ...

May result in a slightly reduced performance (within 2%) in exchange for better reliability and stability.

Qwen3-Coder-Next recipe update

Updated qwen3-coder-next-fp8 recipe: KV cache type changed to fp8 and maximum context length reduced to 131072 tokens to reliably fit within a single Spark's memory.

2026-02-16

MiniMax M2.5 AWQ recipe

Added a new recipe minimax-m2.5-awq for running MiniMax-Text-01-AWQ (M2.5). Usage:

./run-recipe.sh minimax-m2.5-awq

GLM-4.7-Flash-AWQ mod extended with vLLM crash fix

The fix-glm-4.7-flash-AWQ mod now also applies the fix from PR #34695, which addresses a crash in mla_attention.py when running GLM models with AWQ quantization. The patch is applied automatically alongside the existing speed fix, and is skipped if it has already been merged into the installed vLLM version.

2026-02-13

FlashInfer cubin caching

FlashInfer cubins (pre-compiled GPU kernels) are now cached via a Docker bind mount and reused across rebuilds. Previously, all cubins were recompiled from scratch on every FlashInfer rebuild even if unchanged. This significantly reduces FlashInfer rebuild times when only minor source changes are made.

2026-02-12

Added a mod for Qwen3-Coder-Next-FP8 that fixes:

A bug with Triton allocator (https://github.com/vllm-project/vllm/issues/33857) that prevented the model to run in a cluster.
A bug that introduced crash when --enable-prefix-caching is on (https://github.com/vllm-project/vllm/issues/34361).
A bug that significantly impacted the performance on Spark (https://github.com/vllm-project/vllm/issues/34413).

This mod was included in qwen3-coder-next-fp8 recipe.

2026-02-11

Configurable GPU Architecture

Added --gpu-arch <arch> flag to build-and-copy.sh. This allows specifying the target GPU architecture (e.g., 12.0f) during the build process, instead of being hardcoded to 12.1a. This argument controls both TORCH_CUDA_ARCH_LIST and FLASHINFER_CUDA_ARCH_LIST build arguments.

2026-02-10

Cache Directory Mounting

launch-cluster.sh now automatically mounts default cache directories to the container to improve cold start times:

~/.cache/vllm
~/.cache/flashinfer
~/.triton
~/.tilelang

To disable this behavior (clean start), use --no-cache-dirs flag.

2026-02-09

Migrated to a new base image with PyTorch 2.10 compiled with Spark support. With this change, wheels build is no longer a recommended way - please use a source build instead.
Triton 3.6.0 is now default.
Removed temporary fastsafetensors patch, as proper fix is now merged into vLLM main branch.

2026-02-04

Recipes support

A major contribution from @raphaelamorim - model recipes. Recipes allow to launch models with preconfigured settings with one command.

Example:

# List available recipes
./run-recipe.sh --list

# Run a recipe in solo mode (single node)
./run-recipe.sh glm-4.7-flash-awq --solo

# Full setup: build container + download model + run
./run-recipe.sh glm-4.7-flash-awq --solo --setup

# Run with overrides
./run-recipe.sh glm-4.7-flash-awq --solo --port 9000 --gpu-mem 0.8

# Apply an extra launch-cluster mod on top of recipe mods
./run-recipe.sh glm-4.7-flash-awq --solo --apply-mod mods/use-official-vllm

# Publish ports in solo mode
./run-recipe.sh glm-4.7-flash-awq --solo -p 8000:8000

# Cluster deployment
./run-recipe.sh glm-4.7-nvfp4 --setup

Please refer to the documentation for the details.

Launch script option

You can now specify a launch script to execute on head node instead of specifying a command directly via exec action. Example:

./launch-cluster.sh --launch-script examples/vllm-openai-gpt-oss-120b.sh

Thanks @raphaelamorim for the contribution!

Ability to apply vLLM PRs during build

./build-and-copy.sh now supports ability to apply vLLM PRs to builds. PR patches are applied to the selected vLLM ref (--vllm-ref, default main) without carrying the PR branch's original base history. This does NOT apply to MXFP4 special build!

To use, just specify --apply-vllm-pr <pr_num> in the arguments. Dockerfile preset vLLM PRs are applied automatically for an ordinary main source build. Specifying either --vllm-ref or --apply-vllm-pr suppresses the preset PRs unless --apply-preset-vllm-prs is also specified; when enabled, both preset and requested PR patches are applied on top of the selected vLLM ref. Please note that a PR patch may fail if it does not apply cleanly to the selected ref. Use with caution!

Example:

./build-and-copy.sh -t vllm-node-20260204-pr31740 --apply-vllm-pr 31740 -c

2026-02-02

Nemotron Nano mod

Added a mod for nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B support. It supports all Nemotron Nano models/quants using the same reasoning parser. To use, add --apply-mod mods/nemotron-nano to ./launch-cluster.sh arguments.

For example, to run nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4 on a single node:

./launch-cluster.sh --solo --apply-mod mods/nemotron-nano \
  -e VLLM_USE_FLASHINFER_MOE_FP4=1 \
  -e VLLM_FLASHINFER_MOE_BACKEND=throughput \
  exec vllm serve nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4 \
    --max-num-seqs 8 \
    --tensor-parallel-size 1 \
    --max-model-len 262144 \
    --port 8888 --host 0.0.0.0 \
    --trust-remote-code \
    --enable-auto-tool-choice \
    --tool-call-parser qwen3_coder \
    --reasoning-parser-plugin nano_v3_reasoning_parser.py \
    --reasoning-parser nano_v3 \
    --kv-cache-dtype fp8 \
    --gpu-memory-utilization 0.7 \
    --load-format fastsafetensors

Please note, that NVFP4 models on Spark are not fully supported on vLLM (any build) yet, so the performance will not be optimal. You will likely see Flashinfer errors during load. This model is also known to crash sometimes.

Ability to use launch-cluster.sh with NVIDIA NGC containers

Added a new mod that enables using cluster launch script with NVIDIA NGC vLLM or any other vLLM container that includes Infiniband libraries and Ray support.

To use, add --apply-mod mods/use-ngc-vllm to ./launch-cluster.sh arguments. It can be combined with other mods. For example, to launch Nemotron Nano in the cluster using NGC container, you can use the following command:

./launch-cluster.sh \
   -t nvcr.io/nvidia/vllm:26.01-py3 \
   --apply-mod mods/use-ngc-vllm \
   --apply-mod mods/nemotron-nano \
   -e VLLM_USE_FLASHINFER_MOE_FP4=1 \
   -e VLLM_FLASHINFER_MOE_BACKEND=throughput \
   exec vllm serve nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4 \
       --max-model-len 262144 \
       --port 8888 --host 0.0.0.0 \
       --trust-remote-code \
       --enable-auto-tool-choice \
       --tool-call-parser qwen3_coder \
       --reasoning-parser-plugin nano_v3_reasoning_parser.py \
       --reasoning-parser nano_v3 \
       --kv-cache-dtype fp8 \
       --gpu-memory-utilization 0.7 \
       --tensor-parallel-size 2 \
       --distributed-executor-backend ray

Make sure you have the container pulled on both nodes!

At this point it doesn't seem like NGC container performs any better for this model than a custom build.

2026-01-29

New Parameters for launch-cluster.sh

Added solo mode to launch-cluster.sh to launch models on a single node. Just use --solo flag or if you have only a single Spark, it will default to Solo mode if no other nodes are found.
Added -e / --env parameter to launch-cluster.sh to pass environment variables to the container.

New Mod for GLM-4.7-Flash-AWQ

Added a mod to prevent severe inference speed degradation when using cyankiwi/GLM-4.7-Flash-AWQ-4bit (and potentially other AWQ quants of this model). See (this post on NVIDIA forums)[https://forums.developer.nvidia.com/t/make-glm-4-7-flash-go-brrrrr/359111] for implementation details.

Build the standard image first:

# Standard image tag defaults to vllm-node
./build-and-copy.sh -c

Then, to run on a single node:

./launch-cluster.sh -t vllm-node --solo \
  --apply-mod mods/fix-glm-4.7-flash-AWQ \
  exec vllm serve cyankiwi/GLM-4.7-Flash-AWQ-4bit \
  --tool-call-parser glm47 \
  --reasoning-parser glm45 \
  --enable-auto-tool-choice \
  --served-model-name glm-4.7-flash \
  --max-model-len 202752 \
  --max-num-batched-tokens 4096 \
  --max-num-seqs 64 \
  --host 0.0.0.0 --port 8888 \
  --gpu-memory-utilization 0.7

To run on cluster:

./launch-cluster.sh -t vllm-node \
  --apply-mod mods/fix-glm-4.7-flash-AWQ \
  exec vllm serve cyankiwi/GLM-4.7-Flash-AWQ-4bit \
  --tool-call-parser glm47 \
  --reasoning-parser glm45 \
  --enable-auto-tool-choice \
  --served-model-name glm-4.7-flash \
  --max-model-len 202752 \
  --max-num-batched-tokens 4096 \
  --max-num-seqs 64 \
  --host 0.0.0.0 --port 8888 \
  --gpu-memory-utilization 0.7 \
  --distributed-executor-backend ray \
  --tensor-parallel-size 2

NOTE: vLLM implementation is suboptimal even with the patch. The model performance is still significantly slower than it should be for the model with this number of active parameters. Running in the cluster increases prompt processing performance, but not token generation. You can expect ~40 t/s generation speed in both single node and cluster.

Experimental Optimized MXFP4 Build

Added an experimental build option, optimized for DGX Spark and gpt-oss models by Christopher Owen.

It is currently the fastest way to run GPT-OSS on DGX Spark, achieving 60 t/s on a single Spark.

To use this build, first build the container with --exp-mxfp4 flag. I recommend using a separate label as it is currently not recommended to use this build for models other than gpt-oss:

# Image tag defaults to vllm-node-mxfp4 when --exp-mxfp4 is used
./build-and-copy.sh --exp-mxfp4 -c

Then, to run on a single Spark:

 docker run \
  --privileged \
  --gpus all \
  -it --rm \
  --network host --ipc=host \
  -v  ~/.cache/huggingface:/root/.cache/huggingface \
  vllm-node-mxfp4 \
  bash -c -i "vllm serve openai/gpt-oss-120b \
        --host 0.0.0.0 \
        --port 8888 \
        --enable-auto-tool-choice \
        --tool-call-parser openai \
        --reasoning-parser openai_gptoss \
        --gpu-memory-utilization 0.70 \
        --enable-prefix-caching \
        --load-format fastsafetensors \
        --quantization mxfp4 \
        --mxfp4-backend CUTLASS \
        --mxfp4-layers moe,qkv,o,lm_head \
        --attention-backend FLASHINFER \
        --kv-cache-dtype fp8 \
        --max-num-batched-tokens 8192"

On a Dual Spark cluster:

./launch-cluster.sh -t vllm-node-mxfp4 exec vllm serve \
  openai/gpt-oss-120b \
        --host 0.0.0.0 \
        --port 8888 \
        --enable-auto-tool-choice \
        --tool-call-parser openai \
        --reasoning-parser openai_gptoss \
        --gpu-memory-utilization 0.70 \
        --enable-prefix-caching \
        --load-format fastsafetensors \
        --quantization mxfp4 \
        --mxfp4-backend CUTLASS \
        --mxfp4-layers moe,qkv,o,lm_head \
        --attention-backend FLASHINFER \
        --kv-cache-dtype fp8 \
        --max-num-batched-tokens 8192 \
        --distributed-executor-backend ray \
        --tensor-parallel-size 2

2025-12-24

Added hf-download.sh script to download models from HuggingFace using uvx and optionally copy them to other cluster nodes.

Example usage. This will download model and distribute in parallel across all nodes in the cluster:

./hf-download.sh QuantTrio/GLM-4.7-AWQ -c --copy-parallel

2025-12-23

Added mods/patches functionality allowing custom patches to be applied via --apply-mod flag in launch-cluster.sh, enabling model-specific compatibility fixes and experimental features without rebuilding the entire image.
Added support for Salyut1/GLM-4.7-NVFP4 quant.

To run, use the new --apply-mod flag to apply a patch that fixes incompatibility due to glm4 parser expecting separate k and v scales, while this model uses fused quantization scheme. See this issue on Huggingface for details.

After downloading the model on both nodes (to avoid excessive wait times during launch), use this command:

./launch-cluster.sh --apply-mod ./mods/fix-Salyut1-GLM-4.7-NVFP4 \
exec vllm serve Salyut1/GLM-4.7-NVFP4 \
        --attention-config.backend flashinfer \
        --tool-call-parser glm47 \
        --reasoning-parser glm45 \
        --enable-auto-tool-choice \
        -tp 2 \
        --gpu-memory-utilization 0.88 \
        --max-model-len 32000 \
        --distributed-executor-backend ray \
        --host 0.0.0.0 \
        --port 8000

2025-12-21

Added --pre-tf / --pre-transformers flag to build-and-copy.sh for early Transformers 5 testing. Historical note: this flag is now deprecated; current builds use the vLLM default Transformers dependency and the flag only preserves legacy inputs/tagging.
Pre-built wheels now support release versions. Use with --use-wheels release.
Using nightly wheels or building from source is recommended for better performance.

2025-12-20

Limited ccache to 50G when building from source to reduce build cache size.
Added --pre-flashinfer flag to build-and-copy.sh to use pre-release versions of FlashInfer.
Added --use-wheels [mode] flag to build-and-copy.sh.
- Allows building the container using pre-built vLLM wheels instead of compiling from source.
- Reduced build time and container size.
- mode is optional and defaults to nightly.
- Supported modes: nightly (release wheels are broken with CUDA 13 currently). UPDATE: release also works now.

2025-12-19

Updated build-and-copy.sh to support copying to multiple hosts (thanks @ericlewis for the contribution).

Added -c, --copy-to (accepts space- or comma-separated host lists) and kept --copy-to-host as a backward-compatible alias.
Added --copy-parallel to copy to all hosts concurrently.
Added autodiscovery support: if no hosts are provided to --copy-to, the script detects other cluster nodes automatically.
BREAKING CHANGE: Short -h argument is now used for help. Use -c for copy.

2025-12-18

Added launch-cluster.sh convenience script for basic cluster management - see details below.
Added -j / --build-jobs argument to build-and-copy.sh to control build parallelism.
Added --nccl-debug option to specify NCCL debug level. Default is none to decrease verbosity.

2025-12-15

Updated build-and-copy.sh flags:

Renamed --triton-sha to --triton-ref to support branches and tags in addition to commit SHAs.
Added --vllm-ref <ref>: Specify vLLM commit SHA, branch or tag (defaults to main).

2025-12-14

Converted to multi-stage Docker build with improved build times and reduced final image size. The builder stage is now separate from the runtime stage, excluding unnecessary build tools from the final image.

Added timing statistics to build-and-copy.sh to track Docker build and image copy durations, displaying a summary at the end.

Triton is now being built from the source, alongside with its companion triton_kernels package. The Triton version is set to v3.5.1 by default, but it can be changed by using --triton-sha parameter.

Added new flags to build-and-copy.sh:

--triton-sha <sha>: Specify Triton commit SHA (defaults to v3.5.1 currently)
--no-build: Skip building and only copy existing image (requires --copy-to)

2025-12-11 update

PR for MiniMax-M2 has been merged into main, so removed the temporary patch from Dockerfile.

2025-12-11

Applied a patch to fix broken MiniMax-M2 in some quants after this commit until this PR is approved. See this issue for details.

2025-12-05

Added build-and-copy.sh for convenience.

2025-11-26

Initial release. Updated RoCE configuration example to include both interfaces in the list. Applied patch to enable FastSafeTensors in cluster configuration (EXPERIMENTAL) and added documentation on fastsafetensors use.

1. Building the Docker Image

Building Manually

Building the container manually is no longer supported due to Dockerfile complexity. Please use the provided build script.

Using the Build Script

The build-and-copy.sh script prepares the runner image and optionally copies it to one or more nodes. By default it pulls eugr/spark-vllm:latest and tags it locally. Use --use-wheels to build only the runner from downloaded or local precompiled wheels. Source compilation happens only when an explicit source-build flag such as --rebuild-vllm, --vllm-ref, --apply-vllm-pr, --rebuild-flashinfer, --flashinfer-ref, or --apply-flashinfer-pr is supplied.

Basic usage (prepare local image):

./build-and-copy.sh

Prepare with a custom local tag:

./build-and-copy.sh -t my-vllm-node

Build runner image from wheels:

./build-and-copy.sh --use-wheels

Prepare and copy to Spark node(s) using autodiscovery (recommended):

If you omit the host list after --copy-to, the script discovers the other nodes in the cluster and excludes the current node.

./build-and-copy.sh -c --copy-parallel

-c / --copy-to requests distribution. With no addresses, the script uses COPY_HOSTS from .env or autodiscovery; --copy-parallel transfers to all resolved hosts concurrently.

Manual host fallback:

Pass addresses only when you were specifically instructed to do so or the network topology prevents autodiscovery from working.

Using the same username as currently logged-in user (single host):

./build-and-copy.sh --copy-to 192.168.177.12

Copy to multiple hosts (space- or comma-separated after the flag):

./build-and-copy.sh --copy-to 192.168.177.12 192.168.177.13

Copy to multiple hosts in parallel:

./build-and-copy.sh --copy-to 192.168.177.12 192.168.177.13 --copy-parallel

Using a different username:

./build-and-copy.sh --copy-to 192.168.177.12 --user your_username

Force rebuild vLLM from source:

./build-and-copy.sh --rebuild-vllm

Force rebuild FlashInfer from source (skips prebuilt wheel download):

./build-and-copy.sh --rebuild-flashinfer

Combined example (rebuild vLLM and copy to another node):

./build-and-copy.sh --rebuild-vllm -c

Build for specific GPU architecture:

./build-and-copy.sh --gpu-arch 12.0f

Build a vLLM fork with custom PyTorch versions:

./build-and-copy.sh \
  --vllm-repo https://github.com/local-inference-lab/vllm.git \
  --vllm-ref dev/fathomless-firmament \
  --torch-version 2.12.0 \
  --torchvision-version 0.27.0 \
  --torchaudio-version none

For the maintained experimental B12X combination, the equivalent shortcut is:

./build-and-copy.sh --exp-b12x

Without local-build flags, this pulls eugr/spark-vllm-b12x:latest and tags it as vllm-node-b12x unless -t is supplied. To build the maintained combination from local-inference-lab/vllm@dev/gilded-gnosis and the master branch of the B12X repository, run:

./build-and-copy.sh --exp-b12x --rebuild-vllm

It can be combined with --apply-vllm-pr <pr-num> to build custom vLLM patches. The preset preserves selected Blackwell subarchitectures in vLLM's CUDA 13 CMake configuration. This prevents targets such as 10.3a and the default 12.1a from being reduced to generic sm_100 or sm_120, which cannot compile the B12X branch's NVFP4 cache writer. Explicit --gpu-arch 12.0a and --gpu-arch 12.0f selections remain supported and are forwarded unchanged. FlashInfer architecture validation applies to every standard-Dockerfile build, including B12X: alternate targets rebuild FlashInfer when no matching architecture marker is present, and the cached wheel records its architecture so a later build cannot silently reuse a wheel for a different target.

Custom vLLM repositories are cloned fresh instead of using the shared upstream checkout cache. Specifying a custom repository forces a vLLM source build. Upstream preset PRs are skipped by default for custom repositories and refs.

Wheel profiles are selected automatically:

.wheel-cache/
├── flashinfer/
│   ├── regular/   # shared by regular and B12X builds
│   └── custom/    # custom ref/PR or non-default GPU target
└── vllm/
    ├── regular/
    ├── b12x/
    └── custom/    # custom repository/ref/PR, Torch family, or GPU target

Only regular vLLM wheels are downloaded from the published wheel release. --exp-b12x is therefore incompatible with --use-wheels: use bare --exp-b12x for the published image or add --rebuild-vllm for a source build.

For any branch, tag, or commit selected from local-inference-lab/vllm, the runner freshly clones the master ref of https://github.com/lukealonso/b12x.git, builds and installs its b12x distribution automatically. A per-build cache key prevents Docker from reusing a stale source checkout. Before the --no-deps install, its package metadata is updated to the image-wide CUTLASS DSL 4.7.0 pin. The exact source commit is recorded at /workspace/b12x-source-commit. B12X requires PyTorch 2.12 or newer; the preset uses 2.13.0.

Copy existing image without rebuilding:

./build-and-copy.sh --no-build --copy-to

Available options:

Flag	Description
`-t, --tag <tag>`	Local image tag (default: `vllm-node`; auto-set to `vllm-node-tf5` with `--tf5`, `vllm-node-mxfp4` with `--exp-mxfp4`, or `vllm-node-b12x` with `--exp-b12x`)
`--use-wheels`	Build only the runner image from downloaded or local precompiled wheels; never implicitly compile missing wheels. Incompatible with `--exp-b12x`.
`--gpu-arch <arch>`	Target GPU architecture for wheel/source builds. Non-default targets rebuild FlashInfer unless the local cache is marked for that architecture. The default `12.1a` still uses the prebuilt image unless another build-forcing flag is set.
`--rebuild-flashinfer`	Skip prebuilt wheel download; force a fresh local FlashInfer build
`--rebuild-vllm`	Force rebuild vLLM from source
`--force-flashinfer-download`	Force download FlashInfer wheels, skipping cached wheel checks
`--force-vllm-download`	Force download vLLM wheels, skipping cached wheel checks
`--force-download`	Force download all prebuilt wheels, skipping cached wheel checks
`--vllm-repo <url>`	vLLM Git repository. Defaults to `https://github.com/vllm-project/vllm.git`; custom repositories bypass the shared checkout cache and force a source build.
`--vllm-ref <ref>`	vLLM commit SHA, branch or tag (default: `main`)
`--torch-version <version>`	PyTorch version installed in source-build and runner stages (default: `2.13.0`)
`--torchvision-version <version>`	Optional torchvision version (default: `0.28.0`)
`--torchaudio-version <version>`	Optional torchaudio version (default: `2.11.0`; use `none` to omit it)
`--flashinfer-ref <ref>`	FlashInfer commit SHA, branch or tag (default: `main`)
`--apply-vllm-pr <pr-num>`	Apply a vLLM PR patch during build. Can be specified multiple times.
`--apply-preset-vllm-prs`	Apply preset vLLM PRs even when `--vllm-repo`, `--vllm-ref`, or `--apply-vllm-pr` would otherwise suppress them
`--apply-flashinfer-pr <pr-num>`	Apply a FlashInfer PR patch during build. Can be specified multiple times.
`--tf5`	Deprecated compatibility flag; pulls/tags the prebuilt image as `vllm-node-tf5` unless another build-forcing flag is set. Aliases: `--pre-tf, --pre-transformers`.
`--exp-mxfp4`	Build with experimental native MXFP4 support. Alias: `--experimental-mxfp4`.
`--exp-b12x`	Select the B12X profile. Pulls `eugr/spark-vllm-b12x:latest` unless a local wheel/image build is requested; defaults to local tag `vllm-node-b12x`. Alias: `--experimental-b12x`.
`-c, --copy-to <hosts>`	Host(s) to copy the image to after preparation (space- or comma-separated). Hosts with the same image ID are skipped.
`--copy-to-host`	Alias for `--copy-to` (backwards compatibility).
`--copy-parallel`	Copy to all specified hosts concurrently.
`-j, --build-jobs <jobs>`	Number of parallel build jobs (default: 16)
`-u, --user <user>`	Username for SSH connection (default: current user)
`--full-log`	Enable full Docker build output (`--progress=plain`)
`--no-build`	Skip image preparation entirely, only copy an existing local image tag (requires `--copy-to`)
`--network <name>`	Docker network to use during build (e.g. `host`).
`--cleanup`	Remove cached wheel files and provenance markers from every `.wheel-cache` profile; this does not force a local build by itself.
`--config <file>`	Path to `.env` configuration file (default: `.env` in script directory)
`--setup`	Force autodiscovery and save configuration to `.env` (even if `.env` already exists)
`-h, --help`	Show help message

IMPORTANT: When copying to another node manually, use the IP assigned to a ConnectX 7 interface (enp1s0f*), not the 10G/wireless interfaces. When using -c without addresses, autodiscovery selects the correct interface automatically — in mesh mode it uses the direct IB-attached interfaces (enp1s0f0np0, enp1s0f1np1) for maximum transfer speed.

Copying the container to another Spark node (Manual Method)

Alternatively, you can manually copy the image directly to your second Spark node via ConnectX 7 interface by using the following command:

docker save vllm-node | ssh your_username@another_spark_hostname_or_ip "docker load"

IMPORTANT: make sure you use Spark IP assigned to it's ConnectX 7 interface (enp1s0f1np1) , and not 10G one (enP7s7)!

2. Launching the Cluster (Recommended)

The launch-cluster.sh script simplifies the process of starting the cluster nodes. It handles Docker parameters, network interface detection, and node configuration automatically. It loads the default .env when present and runs autodiscovery when the file is absent.

Basic Usage

Start idle cluster containers (auto-detects everything):

./launch-cluster.sh start

This will:

Auto-detect the active InfiniBand and Ethernet interfaces.
Auto-detect the node IP.
Verify that the selected Docker image has the same content-addressable image ID on the head and every worker.
Launch idle containers on the head and worker nodes.
Use native no-Ray multiprocessing by default, or start Ray when --ray is selected.

Assumptions and limitations:

It assumes that you've already set up passwordless SSH access on all nodes. If not, follow NVIDIA's Connect Two Sparks Playbook. I recommend setting up static IPs in the configuration instead of automatically assigning them every time, but this script should work with automatically assigned addresses too.
By default, it assumes that the container image name is vllm-node. If it differs, you need to specify it with -t <name> parameter.
Before launching a multi-node cluster, it compares docker image inspect IDs for the selected image on the head and every active worker. The launch is aborted if an image is missing or any ID differs.
If both ConnectX physical ports are utilized, and both have IP addresses, it will use whatever interface it finds first. Use --eth-if to override.
It will ignore IPs associated with the 2nd "clone" of the physical interface. For instance, the outermost port on Spark has two logical Ethernet interfaces: enp1s0f1np1 and enP2p1s0f1np1. Only enp1s0f1np1 will be used. To override, use --eth-if parameter.
It assumes that the same physical interfaces are named the same on all nodes (IOW, enp1s0f1np1 refers to the same physical port on all nodes). If it's not the case, you will have to launch cluster nodes manually or modify the script.
It clears the Docker image entrypoint by default so images that define an entrypoint, such as vllm-openai, can still start as idle cluster containers before commands are executed. Use --keep-entrypoint to keep the image entrypoint.
In solo mode, -p / --publish can be used to publish ports in Docker format, for example -p 8000:8000. When port publishing is used, the launcher does not use host networking. Port publishing is not supported in cluster mode.
It sets PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True in each container by default to reduce allocator fragmentation on DGX Spark. Override it with -e PYTORCH_CUDA_ALLOC_CONF=<value> when needed.
It mounts ~/.cache/huggingface, ~/.cache/vllm, ~/.cache/flashinfer, ~/.triton, and ~/.tilelang by default. Use --no-cache-dirs to skip the vLLM/FlashInfer/Triton/TileLang cache mounts. Add other mounts with repeatable Docker-style -v / --volume options, e.g. -v "$HOME/my-data:/data".

Start in daemon mode (background):

./launch-cluster.sh -d start

Stop the container:

./launch-cluster.sh stop

Check status:

./launch-cluster.sh status

Execute a command inside the running container:

./launch-cluster.sh exec vllm serve ...

Running `vllm serve` Commands

Pass ordinary model, serving, and parallelism arguments through exec:

./launch-cluster.sh exec vllm serve MODEL_NAME \
  --host 0.0.0.0 \
  --port 8000 \
  -tp 2

For a cluster, the launcher uses .env or autodiscovery and derives the required node count from -tp / --tensor-parallel-size, -pp / --pipeline-parallel-size, and -dp / --data-parallel-size. Do not add --distributed-executor-backend, --nnodes, --node-rank, --master-addr, --master-port, or --headless to the vLLM command. Default no-Ray mode adds the correct per-node arguments automatically; launcher option --ray starts Ray and adds its executor backend. Use --solo for a single-node launch.

Environment Variables and Volume Mappings

Both launch-cluster.sh and run-recipe.sh accept repeatable -e VAR=VALUE options to pass environment variables into the container and repeatable -v LOCAL_PATH:CONTAINER_PATH options to add Docker volume mappings:

./launch-cluster.sh \
  -e VLLM_LOGGING_LEVEL=DEBUG \
  -v "$HOME/models:/models" \
  exec vllm serve /models/MODEL_NAME --port 8000 -tp 2

./run-recipe.sh RECIPE_NAME \
  -e VLLM_LOGGING_LEVEL=DEBUG \
  -v "$HOME/models:/models" \
  --setup

Options for launch-cluster.sh must appear before exec. In cluster mode, each volume is mapped on every launched node, so its local path must be suitable on every host.

For gated Hugging Face models, export the token for host-side downloads and pass it into the container with -e:

export HF_TOKEN="YOUR_TOKEN"
./run-recipe.sh RECIPE_NAME -e HF_TOKEN="$HF_TOKEN" --setup

# Direct launch
./launch-cluster.sh -e HF_TOKEN="$HF_TOKEN" exec vllm serve MODEL_NAME -tp 2

Do not print or share the expanded command because it contains the token.

Recipe Overrides and Additional vLLM Arguments

run-recipe.sh directly supports --port, --host, --tp / --tensor-parallel, --gpu-mem / --gpu-memory-utilization, and --max-model-len overrides. Add any other vLLM arguments after the -- separator:

./run-recipe.sh RECIPE_NAME \
  --port 9000 \
  --gpu-mem 0.85 \
  -- --max-num-seqs 16 --enforce-eager

Extra arguments are appended to the generated vLLM command. When an option is defined more than once, vLLM uses the last occurrence; the recipe runner warns about detected duplicates of its built-in overrides.

Auto-Detection

The script attempts to automatically detect:

Ethernet Interface (ETH_IF): Determined by the number of active CX7 interfaces:
- 2 active (standard): the enp* interface (no capital P) that has an IP address.
- 4 active (mesh topology): enP7s7 (preferred) or wlP9s9 (wireless, shown with a warning) — the cluster coordination interface is separate from the CX7 ports in this configuration.
InfiniBand Interface (IB_IF): All active RoCE devices. In mesh mode this is always rocep1s0f0,roceP2p1s0f0,rocep1s0f1,roceP2p1s0f1.
Cluster peers: Discovered by scanning the ETH_IF subnet for hosts with SSH access and a GB10 GPU (nvidia-smi --query-gpu=name must return NVIDIA GB10).
Copy hosts (COPY_HOSTS): In standard mode, same as cluster peers. In mesh mode, scanned separately on enp1s0f0np0 and enp1s0f1np1 subnets so that image/model transfers use the direct InfiniBand path.

Manual Overrides

Use manual overrides only when instructed or when the topology cannot be discovered correctly:

./launch-cluster.sh --nodes "10.0.0.1,10.0.0.2" --eth-if enp1s0f1np1 --ib-if rocep1s0f1 -e MY_ENV=123

Flag	Description
`-n, --nodes`	Manual fallback/override: comma-separated node IPs (head node first).
`-t`	Docker image name (default: `vllm-node`).
`--name`	Container name (default: `vllm_node`).
`--eth-if`	Ethernet interface name.
`--ib-if`	InfiniBand interface name.
`-e, --env`	Environment variable to pass to container (e.g. `-e VAR=val`). Can be used multiple times.
`-j`	Number of parallel jobs for build environment variables (optional).
`--apply-mod`	Apply mods/patches from specified directory. Can be used multiple times to apply multiple mods.
`--nccl-debug`	NCCL debug level (e.g., INFO, WARN). Defaults to INFO if flag is present but value is omitted.
`--check-config`	Check configuration and auto-detection without launching.
`--solo`	Solo mode: skip autodetection, launch only on current node, do not launch Ray cluster
`-p, --publish`	Publish a container port in Docker format, for example `-p 8000:8000`. Solo mode only; replaces host networking. Can be used multiple times.
`-v, --volume`	Map a volume in Docker format, for example `-v /local/path:/container/path`. Applies to every launched node and can be used multiple times.
`--ray`	Opt into Ray for multi-node vLLM and add `--distributed-executor-backend ray` when missing.
`--no-ray`	Default multi-node no-Ray mode; accepted for compatibility.
`--master-port` / `--head-port`	Port for cluster coordination: Ray head port or PyTorch distributed master port (default: 29501).
`--no-cache-dirs`	Do not mount default cache directories (~/.cache/vllm, ~/.cache/flashinfer, ~/.triton, ~/.tilelang).
`--keep-entrypoint`	Keep the Docker image entrypoint instead of clearing it before launching the idle cluster container.
`--earlyoom`	Run `earlyoom` as the container foreground process instead of `sleep infinity`.
`--earlyoom-args`	Arguments passed to `earlyoom` (default: `-M 524288,102400 -s 100 -r 60`). Implies `--earlyoom`.
`--launch-script`	Path to bash script to execute in the container (from examples/ directory or absolute path). If launch script is specified, action should be omitted.
`-d`	Run in daemon mode (detached).
`--non-privileged`	Run in non-privileged mode (removes `--privileged` and `--ipc=host`).
`--mem-limit-gb`	Memory limit in GB (default: 110, only with `--non-privileged`).
`--mem-swap-limit-gb`	Memory+swap limit in GB (default: mem-limit + 10, only with `--non-privileged`).
`--pids-limit`	Process limit (default: 4096, only with `--non-privileged`).
`--shm-size-gb`	Shared memory size in GB (default: 64, only with `--non-privileged`).
`--config <file>`	Path to `.env` configuration file (default: `.env` in script directory).
`--setup`	Force autodiscovery and save configuration to `.env` (even if `.env` already exists).
`start \| stop \| status \| exec`	Action to perform. Use `start` for idle containers or `exec` to run a command. Not compatible with `--launch-script`.
`command`	Command to execute inside the container (only for `exec` action).

Early OOM Monitor

The --earlyoom flag starts the idle container with earlyoom as PID 1 instead of sleep infinity, so it monitors memory while Ray and vLLM are launched with docker exec. This is optional; without --earlyoom, containers still use the plain idle command.

Default policy:

earlyoom -M 524288,102400 -s 100 -r 60

What those arguments mean:

-M 524288,102400: send SIGTERM when available memory is below 524288 KiB (512 MiB), then SIGKILL when it is below 102400 KiB (100 MiB).
-s 100: do not wait for swap to fill before acting. Earlyoom normally requires both memory and swap to be below their thresholds; -s 100 makes the swap threshold effectively satisfied so host RAM pressure is enough. Use a paired value such as -s 70,50 if you want swap-free thresholds for TERM and KILL.
-r 60: print a memory report every 60 seconds. Use -r 0 to disable periodic reports.

Tune the policy per launch with --earlyoom-args:

./launch-cluster.sh --earlyoom \
  --earlyoom-args "-M 1048576,262144 -s 70,50 -r 30" \
  exec vllm serve ...

The same options pass through recipe launches:

./run-recipe.sh minimax-m2-awq --solo \
  --earlyoom --earlyoom-args "-M 786432,196608 -s 100 -r 120"

You can also set the default arguments through the environment:

VLLM_SPARK_EARLYOOM_ARGS="-M 786432,196608 -s 100 -r 120" \
  ./launch-cluster.sh --earlyoom exec vllm serve ...

Other useful upstream options include --prefer REGEX and --avoid REGEX to bias victim selection, --dryrun to log what would be killed without killing it, and -g to kill the selected process group instead of only the selected process. Keep custom argument values shell-safe because they are passed through the launcher as command arguments.

--earlyoom is not compatible with --keep-entrypoint: the launcher must clear the image entrypoint so earlyoom can be the container foreground process.

Non-Privileged Mode

The --non-privileged flag allows running containers without full privileged access while maintaining RDMA/InfiniBand functionality:

./launch-cluster.sh --non-privileged exec vllm serve ...

When --non-privileged is specified:

--privileged is replaced with --cap-add=IPC_LOCK
--ipc=host is replaced with --shm-size=64g (configurable via --shm-size-gb)
RDMA devices are exposed via --device=/dev/infiniband
Resource limits are applied: memory (110GB), memory+swap (120GB), pids (4096)

All launch modes set Docker's open-file ulimit to 1048576, which avoids loader failures when highly sharded models are opened in parallel by Ray workers. Override it with VLLM_SPARK_NOFILE_LIMIT if your host requires a different value.

These resource limits can be customized:

./launch-cluster.sh --non-privileged \
  --mem-limit-gb 120 \
  --mem-swap-limit-gb 130 \
  --shm-size-gb 64 \
  exec vllm serve ...

3. Running the Container (Manual)

Manual docker run can be useful if you want full control over Docker parameters, but it's not recommended even for single Sparks. For multi-node Ray or no-Ray launches, use launch-cluster.sh; the old standalone run-cluster-node.sh flow has been removed and its logic is now integrated into the launcher.

docker run -it --rm \
  --gpus all \
  --net=host \
  --ipc=host \
  --privileged \
  --ulimit nofile=1048576:1048576 \
  --name vllm_node \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm-node bash

Inside the container, run vllm serve ... directly for solo inference.

IMPORTANT: for cluster commands, use the IP addresses associated with ConnectX 7 interfaces, not the 10G or wireless interfaces.

Flags Explained:

--net=host: Required for cluster commands. Ray and NCCL need full access to host network interfaces.
--ipc=host: Recommended. Allows shared memory access for PyTorch/NCCL. As an alternative, you can set it via --shm-size=16g.
--privileged: Recommended for InfiniBand. Grants the container access to RDMA devices (/dev/infiniband). As an alternative, you can pass --ulimit memlock=-1 --ulimit stack=67108864 --device=/dev/infiniband.
--ulimit nofile=1048576:1048576: Recommended for large sharded models. Prevents Too many open files errors during parallel safetensors metadata loading.

4. Configuration Details

Cluster Configuration (`.env` file)

The scripts share a .env file (default: .env in the repo directory) for persistent cluster configuration. It is created automatically by autodiscovery — run --discover (via run-recipe.sh) or --setup (via launch-cluster.sh / build-and-copy.sh) on first use.

Autodiscovery and the saved .env are the default user workflow. Do not pass node IPs manually unless you were specifically instructed to do so or the network topology prevents autodiscovery from working.

Supported variables:

Variable	Description
`CLUSTER_NODES`	Comma-separated node IPs used for Ray/vLLM cluster (head node first).
`COPY_HOSTS`	Comma-separated node IPs used for image and model distribution. In mesh mode these are the IPs on the direct IB-attached interfaces, which may differ from `CLUSTER_NODES`.
`LOCAL_IP`	IP address of the local node.
`ETH_IF`	Ethernet interface for cluster coordination (e.g. `enp1s0f1np1` or `enP7s7`).
`IB_IF`	Comma-separated RoCE/IB device names (e.g. `rocep1s0f0,roceP2p1s0f0,rocep1s0f1,roceP2p1s0f1`).
`CONTAINER_*`	Any variable prefixed with `CONTAINER_` (except `CONTAINER_NAME`) is passed as `-e VAR=VALUE` to the container. Example: `CONTAINER_NCCL_DEBUG=INFO` → `-e NCCL_DEBUG=INFO`.

Mesh-mode NCCL variables (written automatically when mesh topology is detected):

CONTAINER_NCCL_NET_PLUGIN=none
CONTAINER_NCCL_IB_SUBNET_AWARE_ROUTING=1
CONTAINER_NCCL_IB_MERGE_NICS=0

Example .env for a standard 2-node cluster:

CLUSTER_NODES=192.168.177.11,192.168.177.12
COPY_HOSTS=192.168.177.12
LOCAL_IP=192.168.177.11
ETH_IF=enp1s0f1np1
IB_IF=rocep1s0f1,roceP2p1s0f1

To use a custom config file path, pass --config /path/to/file.env to any script.

Autodiscovery Workflow

On first run, if no .env is present, the scripts will automatically trigger autodiscovery. You can also run it explicitly:

# Via run-recipe.sh
./run-recipe.sh --discover

# Via launch-cluster.sh or build-and-copy.sh (force re-run even if .env exists)
./launch-cluster.sh --setup exec vllm serve ...
./build-and-copy.sh --setup -c

Autodiscovery:

Detects active CX7 interfaces and determines mesh vs. standard topology.
Scans the network for SSH-reachable GB10 peers.
In mesh mode, separately discovers COPY_HOSTS on direct IB-attached interfaces.
Prompts for per-node confirmation for both CLUSTER_NODES and COPY_HOSTS.
Saves the result to .env.

Environment Persistence

The launcher injects node-specific environment variables with Docker -e flags when each container starts. If you need to open a second terminal into the running container for debugging, run:

docker exec -it vllm_node bash

The new shell inherits the container environment, including NCCL, Ray, and vLLM network settings.

5. Mods and Patches

The vLLM Docker setup supports applying custom mods and patches to address specific model compatibility issues or apply experimental features. This functionality is primarily managed through the --apply-mod option in the cluster launch script, and run-recipe.sh can pass additional --apply-mod flags through to launch-cluster.sh.

Available Mods

The repository includes several pre-configured mods in the mods/ directory:

fix-Salyut1-GLM-4.7-NVFP4/: Fixes the GLM4MoE parser for Salyut1/GLM-4.7-NVFP4 fused QKV quantization.
fix-glm-4.7-flash-AWQ/: Applies GLM-4.7-Flash-AWQ compatibility and performance fixes.
fix-qwen3.5-chat-template/ and fix-qwen3.6-chat-template/: Install fixed chat templates used by the Qwen3.5 and Qwen3.6 recipes.
fix-qwen3.5-autoround/, fix-qwen3-next-autoround/, and fix-qwen35-tp4-marlin/: Model-specific Qwen AutoRound and Marlin compatibility fixes.
fix-qwen3-coder-next/: Qwen3-Coder-Next runtime and performance fixes.
dspark-instanttensor/: Filters embedded mtp.* DSpark draft weights before InstantTensor or safetensors I/O, preventing a second full-checkpoint load.
gpu-mem-util-gb/: Adds experimental --gpu-memory-utilization-gb support.
kv-cache-prealloc-cleanup/: Applies model-specific manual KV-cache startup tweaks: skip CUDA graph profiling when disabled by env and allow --gpu-memory-utilization-gb with --kv-cache-memory-bytes.
uma-fix/: Uses CUDA/NVML memory accounting under WSL and skips host-memory UMA accounting there.
drop-caches/: Periodically clears filesystem caches for large models running near the memory limit.
diffusiongemma/: Adds DiffusionGemma support, dynamic causal attention compatibility, and Gemma4 reasoning/content-channel fixes used by the DiffusionGemma recipes.
nemotron-nano/ and nemotron-super/: Nemotron reasoning parser and model support helpers.
inkling-sm12-paged-kv/: Routes Inkling's SM12 paged-KV relative attention through a vendored FA4 implementation while leaving other models and GPU architectures unchanged.
instanttensor-hybrid-draft-loader/: Keeps a target model on InstantTensor while using lazy safetensors for eligible speculative draft weights, including embedded MTP drafts.
exp-b12x/: Experimental FlashInfer b12x support for builds that include the required upstream vLLM support.
use-official-vllm/: Installs git, earlyoom, InstantTensor, and SciPy inside official vLLM containers (Ubuntu/Debian-based) so that other mods can rely on git apply, the launcher can use --earlyoom, and vLLM can use --load-format instanttensor and SciPy-based functionality. The Python install preserves the image's existing Torch build. The mod also redirects the pip-installed NCCL library to the system libnccl2 library to avoid DGX Spark multi-node NCCL hangs. Apply this mod first when using official vLLM images (e.g. vllm-openai).

Each mod directory typically contains:

Patch files (.patch) for code modifications and/or other assets.
run.sh script to apply the patch.

Patch can also be represented as a .zip file with the same structure.

Using Mods

To apply mods when launching the cluster, use the --apply-mod flag:

./launch-cluster.sh --apply-mod ./mods/fix-Salyut1-GLM-4.7-NVFP4

You can apply multiple mods by specifying additional --apply-mod flags:

./launch-cluster.sh --apply-mod ./mods/fix-Salyut1-GLM-4.7-NVFP4 --apply-mod ./mods/other-mod

When using recipes, any mods listed in the recipe are applied first, followed by mods supplied on the command line:

./run-recipe.sh glm-4.7-flash-awq --solo --apply-mod ./mods/other-mod

Creating Custom Mods

To create your own mod:

Create a new directory in the mods/ folder
Add your patch files (.patch) or other assets as necessary (optional).
Create a run.sh script to apply the patch. It shouldn't accept any parameters. This script is required.
Reference your mod using the --apply-mod path/to/your/mod flag

Mods can be used for:

Applying specific model compatibility fixes
Testing experimental features
Customizing vLLM behavior for specific workloads
Rapid iteration on development without rebuilding the entire image

6. Launch Scripts

Launch scripts provide a simple way to define reusable model configurations. Instead of passing long command lines, you can create a bash script that is copied into the container and executed directly.

Basic Usage

# Use a launch script by name (looks in examples/ directory)
./launch-cluster.sh --launch-script example-vllm-minimax

# Manual fallback when autodiscovery cannot support the topology
./launch-cluster.sh -n 192.168.1.1,192.168.1.2 --launch-script vllm-openai-gpt-oss-120b.sh

# Combine with mods for models requiring patches
./launch-cluster.sh --launch-script vllm-glm-4.7-nvfp4.sh --apply-mod mods/fix-Salyut1-GLM-4.7-NVFP4

Script Format

Launch scripts are simple bash files that run directly inside the container:

#!/bin/bash
# PROFILE: OpenAI GPT-OSS 120B
# DESCRIPTION: vLLM serving openai/gpt-oss-120b with FlashInfer MOE optimization

# Set environment variables if needed
export VLLM_USE_FLASHINFER_MOE_MXFP4_MXFP8=1

# Run your command
vllm serve openai/gpt-oss-120b \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2 \
    --enable-auto-tool-choice

Available Launch Scripts

The examples/ directory contains ready-to-use launch scripts:

example-vllm-minimax.sh - MiniMax-M2-AWQ cluster launch example
vllm-openai-gpt-oss-120b.sh - OpenAI GPT-OSS 120B with FlashInfer MOE
vllm-glm-4.7-nvfp4.sh - GLM-4.7-NVFP4 (requires the glm4_moe patch mod)

See examples/README.md for detailed documentation and more examples.

7. Using cluster mode for inference

The preferred path is to let launch-cluster.sh start containers and run the command in one step:

./launch-cluster.sh exec vllm serve RedHatAI/Qwen3-VL-235B-A22B-Instruct-NVFP4 \
  --port 8888 --host 0.0.0.0 \
  --gpu-memory-utilization 0.7 \
  -tp 2 \
  --max-model-len 32768

No-Ray mode is the default. The launcher starts worker commands first, then runs rank 0 on the head. To opt into Ray, add --ray before exec; do not add the executor backend to the vLLM arguments:

./launch-cluster.sh --ray exec vllm serve RedHatAI/Qwen3-VL-235B-A22B-Instruct-NVFP4 \
  --port 8888 --host 0.0.0.0 \
  --gpu-memory-utilization 0.7 \
  -tp 2 \
  --max-model-len 32768

When parallelism flags are present, the launcher automatically trims the active node list or errors before startup if more nodes are required than configured.

8. Model Loading

This build includes support for fastsafetensors and InstantTensor loading.

fastsafetensors significantly improves loading speeds, especially on DGX Spark where MMAP performance is currently poor. It uses more efficient multi-threaded loading while avoiding mmap.

To use it, include --load-format fastsafetensors when running vLLM:

./launch-cluster.sh -e HF_HUB_OFFLINE=1 exec vllm serve openai/gpt-oss-120b --port 8888 --host 0.0.0.0 --trust_remote_code --swap-space 16 --gpu-memory-utilization 0.7 -tp 2 --load-format fastsafetensors

InstantTensor is available with --load-format instanttensor. Several large-model recipes use it to reduce load-time memory pressure.

9. Benchmarking

I recommend using llama-benchy - a new benchmarking tool that delivers results in the same format as llama-bench from llama.cpp suite.

10. Downloading Models

The hf-download.sh script provides a convenient way to download models from HuggingFace and distribute them across your cluster nodes. It uses Huggingface CLI via uvx for fast downloads and rsync for distribution across the cluster.

Prerequisites

uvx must be installed (the script will prompt you to install it if missing).
Passwordless SSH access to other nodes (if copying).

Usage

Download a model (local only):

./hf-download.sh QuantTrio/MiniMax-M2-AWQ

Download and copy using autodiscovery (recommended):

./hf-download.sh -c QuantTrio/MiniMax-M2-AWQ

Download and copy in parallel:

./hf-download.sh -c --copy-parallel QuantTrio/MiniMax-M2-AWQ

Use nodes from .env (respects COPY_HOSTS):

./hf-download.sh -c QuantTrio/MiniMax-M2-AWQ

When -c is given without explicit hosts, the script checks COPY_HOSTS in .env first, then falls back to autodiscovery. In mesh mode this means transfers go over the direct IB-attached interfaces automatically.

If distribution fails with permission errors under ~/.cache, verify ownership on every node. When root-owned cache files are the cause and the cache should belong to the login user, run this locally on each node:

sudo chown -R "$USER" "$HOME/.cache"

This is a privileged recursive change; confirm the target and ownership problem before running it. If HF_HOME points elsewhere, repair that cache path instead.

Manual host fallback:

Pass specific nodes only when instructed or when autodiscovery cannot support the topology:

./hf-download.sh -c 192.168.177.12,192.168.177.13 QuantTrio/MiniMax-M2-AWQ

Use a custom config file:

./hf-download.sh --config /path/to/cluster.env -c QuantTrio/MiniMax-M2-AWQ

Available options:

Flag	Description
`<model-name>`	HuggingFace model ID (e.g. `QuantTrio/MiniMax-M2-AWQ`). Required.
`-c, --copy-to <hosts>`	Host(s) to copy the model to after download (space- or comma-separated). Omit hosts to use `COPY_HOSTS` from `.env` or autodiscovery.
`--copy-to-host`	Alias for `--copy-to` (backwards compatibility).
`--copy-parallel`	Copy to all hosts concurrently instead of serially.
`-u, --user <user>`	SSH username for remote copies (default: current user).
`--config <file>`	Path to `.env` configuration file (default: `.env` in script directory).
`-h, --help`	Show help message.

Hardware Architecture

Note: This project targets 12.1a architecture (NVIDIA GB10 / DGX Spark). If you are using different hardware, you can use --gpu-arch flag in ./build-and-copy.sh.

Donchitos/Claude-Code-Game-Studios

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

Claude Code Game Studios

Turn a single Claude Code session into a full game development studio.
49 agents. 73 skills. One coordinated AI team.

Why This Exists

Building a game solo with AI is powerful — but a single chat session has no structure. No one stops you from hardcoding magic numbers, skipping design docs, or writing spaghetti code. There's no QA pass, no design review, no one asking "does this actually fit the game's vision?"

Claude Code Game Studios solves this by giving your AI session the structure of a real studio. Instead of one general-purpose assistant, you get 49 specialized agents organized into a studio hierarchy — directors who guard the vision, department leads who own their domains, and specialists who do the hands-on work. Each agent has defined responsibilities, escalation paths, and quality gates.

The result: you still make every decision, but now you have a team that asks the right questions, catches mistakes early, and keeps your project organized from first brainstorm to launch.

What's Included

Category	Count	Description
Agents	49	Specialized subagents across design, programming, art, audio, narrative, QA, and production
Skills	73	Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.)
Hooks	12	Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection
Rules	11	Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more
Templates	41	Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more

Studio Hierarchy

Agents are organized into three tiers, matching how real studios operate:

Tier 1 — Directors (Opus)
  creative-director    technical-director    producer

Tier 2 — Department Leads (Sonnet)
  game-designer        lead-programmer       art-director
  audio-director       narrative-director    qa-lead
  release-manager      localization-lead

Tier 3 — Specialists (Sonnet/Haiku)
  gameplay-programmer  engine-programmer     ai-programmer
  network-programmer   tools-programmer      ui-programmer
  systems-designer     level-designer        economy-designer
  technical-artist     sound-designer        writer
  world-builder        ux-designer           prototyper
  performance-analyst  devops-engineer       analytics-engineer
  security-engineer    qa-tester             accessibility-specialist
  live-ops-designer    community-manager

Engine Specialists

The template includes agent sets for all three major engines. Use the set that matches your project:

Engine	Lead Agent	Sub-Specialists
Godot 4	`godot-specialist`	GDScript, Shaders, GDExtension
Unity	`unity-specialist`	DOTS/ECS, Shaders/VFX, Addressables, UI Toolkit
Unreal Engine 5	`unreal-specialist`	GAS, Blueprints, Replication, UMG/CommonUI

Slash Commands

Type / in Claude Code to access all 73 skills:

Onboarding & Navigation /start /help /project-stage-detect /setup-engine /adopt

Game Design /brainstorm /map-systems /design-system /quick-design /review-all-gdds /propagate-design-change

Art & Assets /art-bible /asset-spec /asset-audit

UX & Interface Design /ux-design /ux-review

Architecture /create-architecture /architecture-decision /architecture-review /create-control-manifest

Stories & Sprints /create-epics /create-stories /dev-story /sprint-plan /sprint-status /story-readiness /story-done /estimate

Reviews & Analysis /design-review /code-review /balance-check /content-audit /scope-check /perf-profile /tech-debt /gate-check /consistency-check /security-audit

QA & Testing /qa-plan /smoke-check /soak-test /regression-suite /test-setup /test-helpers /test-evidence-review /test-flakiness /skill-test /skill-improve

Production /milestone-review /retrospective /bug-report /bug-triage /reverse-document /playtest-report

Release /release-checklist /launch-checklist /changelog /patch-notes /hotfix /day-one-patch

Creative & Content /prototype /onboard /localize

Team Orchestration (coordinate multiple agents on a single feature) /team-combat /team-narrative /team-ui /team-release /team-polish /team-audio /team-level /team-live-ops /team-qa

Getting Started

Prerequisites

Git
Claude Code (npm install -g @anthropic-ai/claude-code)
Recommended: jq (for hook validation) and Python 3 (for JSON validation)

All hooks fail gracefully if optional tools are missing — nothing breaks, you just lose validation.

Setup

Clone or use as template:

git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game
cd my-game

Open Claude Code and start a session:
```
claude
```
Run /start — the system asks where you are (no idea, vague concept, clear design, existing work) and guides you to the right workflow. No assumptions.

Or jump directly to a specific skill if you already know what you need:
- /brainstorm — explore game ideas from scratch
- /setup-engine godot 4.6 — configure your engine if you already know
- /project-stage-detect — analyze an existing project

Upgrading

Already using an older version of this template? See UPGRADING.md for step-by-step migration instructions, a breakdown of what changed between versions, and which files are safe to overwrite vs. which need a manual merge.

Project Structure

CLAUDE.md                           # Master configuration
.claude/
  settings.json                     # Hooks, permissions, safety rules
  agents/                           # 49 agent definitions (markdown + YAML frontmatter)
  skills/                           # 73 slash commands (subdirectory per skill)
  hooks/                            # 12 hook scripts (bash, cross-platform)
  rules/                            # 11 path-scoped coding standards
  statusline.sh                     # Status line script (context%, model, stage, epic breadcrumb)
  docs/
    workflow-catalog.yaml           # 7-phase pipeline definition (read by /help)
    templates/                      # 41 document templates
src/                                # Game source code
assets/                             # Art, audio, VFX, shaders, data files
design/                             # GDDs, narrative docs, level designs
docs/                               # Technical documentation and ADRs
tests/                              # Test suites (unit, integration, performance, playtest)
tools/                              # Build and pipeline tools
prototypes/                         # Throwaway prototypes (isolated from src/)
production/                         # Sprint plans, milestones, release tracking

How It Works

Agent Coordination

Agents follow a structured delegation model:

Vertical delegation — directors delegate to leads, leads delegate to specialists
Horizontal consultation — same-tier agents can consult each other but can't make binding cross-domain decisions
Conflict resolution — disagreements escalate up to the shared parent (creative-director for design, technical-director for technical)
Change propagation — cross-department changes are coordinated by producer
Domain boundaries — agents don't modify files outside their domain without explicit delegation

Collaborative, Not Autonomous

This is not an auto-pilot system. Every agent follows a strict collaboration protocol:

Ask — agents ask questions before proposing solutions
Present options — agents show 2-4 options with pros/cons
You decide — the user always makes the call
Draft — agents show work before finalizing
Approve — nothing gets written without your sign-off

You stay in control. The agents provide structure and expertise, not autonomy.

Automated Safety

Hooks run automatically on every session:

Hook	Trigger	What It Does
`validate-commit.sh`	PreToolUse (Bash)	Checks for hardcoded values, TODO format, JSON validity, design doc sections — exits early if the command is not `git commit`
`validate-push.sh`	PreToolUse (Bash)	Warns on pushes to protected branches — exits early if the command is not `git push`
`validate-assets.sh`	PostToolUse (Write/Edit)	Validates naming conventions and JSON structure — exits early if the file is not in `assets/`
`session-start.sh`	Session open	Shows current branch and recent commits for orientation
`detect-gaps.sh`	Session open	Detects fresh projects (suggests `/start`) and missing design docs when code or prototypes exist
`pre-compact.sh`	Before compaction	Preserves session progress notes
`post-compact.sh`	After compaction	Reminds Claude to restore session state from `active.md`
`notify.sh`	Notification event	Shows Windows toast notification via PowerShell
`session-stop.sh`	Session close	Archives `active.md` to session log and records git activity
`log-agent.sh`	Agent spawned	Audit trail start — logs subagent invocation
`log-agent-stop.sh`	Agent stops	Audit trail stop — completes subagent record
`validate-skill-change.sh`	PostToolUse (Write/Edit)	Advises running `/skill-test` after any `.claude/skills/` change

Note: validate-commit.sh, validate-assets.sh, and validate-skill-change.sh fire on every Bash/Write tool call and exit immediately (exit 0) when the command or file path is not relevant. This is normal hook behavior — not a performance concern.

Permission rules in settings.json auto-allow safe operations (git status, test runs) and block dangerous ones (force push, rm -rf, reading .env files).

Path-Scoped Rules

Coding standards are automatically enforced based on file location:

Path	Enforces
`src/gameplay/**`	Data-driven values, delta time usage, no UI references
`src/core/**`	Zero allocations in hot paths, thread safety, API stability
`src/ai/**`	Performance budgets, debuggability, data-driven parameters
`src/networking/**`	Server-authoritative, versioned messages, security
`src/ui/**`	No game state ownership, localization-ready, accessibility
`design/gdd/**`	Required 8 sections, formula format, edge cases
`tests/**`	Test naming, coverage requirements, fixture patterns
`prototypes/**`	Relaxed standards, README required, hypothesis documented

Design Philosophy

This template is grounded in professional game development practices:

MDA Framework — Mechanics, Dynamics, Aesthetics analysis for game design
Self-Determination Theory — Autonomy, Competence, Relatedness for player motivation
Flow State Design — Challenge-skill balance for player engagement
Bartle Player Types — Audience targeting and validation
Verification-Driven Development — Tests first, then implementation

Customization

This is a template, not a locked framework. Everything is meant to be customized:

Add/remove agents — delete agent files you don't need, add new ones for your domains
Edit agent prompts — tune agent behavior, add project-specific knowledge
Modify skills — adjust workflows to match your team's process
Add rules — create new path-scoped rules for your project's directory structure
Tune hooks — adjust validation strictness, add new checks
Pick your engine — use the Godot, Unity, or Unreal agent set (or none)
Set review intensity — full (all director gates), lean (phase gates only), or solo (none). Set during /start or edit production/review-mode.txt. Override per-run with --review solo on any skill.

Platform Support

Primary development and testing on Windows 10 with Git Bash. All hooks use POSIX-compatible patterns (grep -E, not grep -P) and include fallbacks for missing tools, so they should run on macOS and Linux. The notify.sh hook uses PowerShell for Windows toast notifications and is a no-op elsewhere — desktop notifications on macOS/Linux are not yet wired. Cross-platform testing is ongoing; please file issues for any platform-specific breakage.

Community

Discussions — GitHub Discussions for questions, ideas, and showcasing what you've built
Issues — Bug reports and feature requests

Supporting This Project

Claude Code Game Studios is free and open source. If it saves you time or helps you ship your game, consider supporting continued development:

Buy Me a Coffee — one-time support
GitHub Sponsors — recurring support through GitHub

Sponsorships help fund time spent maintaining skills, adding new agents, keeping up with Claude Code and engine API changes, and responding to community issues.

Built for Claude Code. Maintained and extended — contributions welcome via GitHub Discussions.

License

MIT License. See LICENSE for details.

llm-d/llm-d

Achieve state of the art inference performance with modern accelerators on Kubernetes

Achieve SOTA Inference Performance On Any Accelerator

llm-d is a high-performance distributed inference serving stack optimized for production deployments on Kubernetes. We help you achieve the fastest "time to state-of-the-art (SOTA) performance" for key OSS large language models across most hardware accelerators and infrastructure providers with well-tested guides and real-world benchmarks.

llm-d is a Cloud Native Computing Foundation (CNCF) sandbox project, founded by Red Hat, Google Cloud, IBM Research, CoreWeave, and NVIDIA.

What does llm-d offer to production inference?

Model servers like vLLM and SGLang handle efficiently running large language models on accelerators. llm-d provides state-of-the-art orchestration and optimizations above model servers to serve high-scale real-world traffic efficiently and reliably. Our offerings are organized into four core themes:

Intelligent Routing: Maximize performance with prefix-cache and load-aware balancing, including experimental predicted latency-based scheduling to decrease latency and increase throughput.
Advanced KV-Cache Management: Increase the effective "working set size" for multi-turn requests with tiered offloading to CPU or disk and precise global indexing of the KV cache state.
Serving Large Models: Optimize massive models (e.g., DeepSeek-R1, GPT-OSS) using prefill/decode disaggregation and wide expert-parallelism over fast accelerator interconnects.
Operational Excellence: Ensure production stability with intelligent flow control for multi-tenant serving and proactive, SLO-aware autoscaling based on real-time inference signals.
Batch Processing: Efficiently manage large-scale offline inference with OpenAI-compatible Batch APIs and asynchronous processing to maximize hardware utilization.

For a complete list of tested recipes and architectural patterns, see our well-lit path guides. These guides provide benchmarked recipes and Helm charts to start serving quickly with best practices common to production deployments. Our intent is to eliminate the heavy lifting common in tuning and deploying generative AI inference on modern accelerators.

Performance Highlights

Validated performance gains from production deployments and partner benchmarks:

3x higher output throughput and 2x faster TTFT with prefix-cache-aware routing vs round-robin — Llama 3.1 70B on 4× AMD MI300X, Tesla / Red Hat (blog)
40% reduction in TTFT and ITL with predicted-latency scheduling vs heuristics on NVIDIA GPUs, Google (blog)
Up to 70% higher tokens/sec with prefill/decode disaggregation vs standard vLLM — GPT-OSS on NVIDIA B200 (p6-b200), AWS (blog)
10–30% throughput improvement with disaggregated serving on identical infrastructure — GPT-OSS-120B and Llama 3.3 70B on AMD MI300X, Oracle (blog)
50k tokens/sec cluster throughput with Wide Expert-Parallelism — 16×16 NVIDIA B200, ~3.1k tok/s per GPU (blog)
13.9x throughput improvement with hierarchical KV offloading at 250 concurrent users vs GPU-only — 4× NVIDIA H100 (blog)

Explore detailed, reproducible benchmarks on Prism.

Get Started Now

Ready to achieve SOTA performance? Follow our Quickstart Guide to deploy your first optimized inference service on Kubernetes. You'll learn how to set up the llm-d stack, configure the intelligent router, and validate performance with production-ready benchmarks.

Tip

Most users begin with our Optimized Baseline, which provides a high-performance foundation for a wide range of LLM serving use cases.

Latest News 🔥

[2026-05] The v0.7 release introduces an optimized baseline renamed and stabilized, kustomize-first migrated guides, expanded nightly CI (OpenShift, GKE, CoreWeave), predicted-latency scheduling GA, batch gateway (experimental), and revamped project-wide documentation.
[2026-03] llm-d joins the CNCF as a Sandbox project! Founded by Red Hat, Google Cloud, IBM Research, CoreWeave, and NVIDIA, with support from AMD, Cisco, Hugging Face, Intel, Lambda, Mistral AI, UC Berkeley, and University of Chicago. We're excited to collaborate openly on building flexible, future-proof AI infrastructure.
[2026-02] The v0.5 introduces reproducible benchmark workflows, hierarchical KV offloading, cache-aware LoRA routing, active-active HA, UCCL-based transport resilience, and scale-to-zero autoscaling; validated ~3.1k tok/s per B200 decode GPU (wide-EP) and up to 50k output tok/s on a 16×16 B200 prefill/decode topology with order-of-magnitude TTFT reduction vs round-robin baseline.
[2025-12] The v0.4 release demonstrates 40% reduction in per output token latency for DeepSeek V3.1 on H200 GPUs, Intel XPU and Google TPU disaggregation support for lower time to first token, a new well-lit path for prefix cache offload to vLLM-native CPU memory tiering, and a preview of the workload variant autoscaler improving model-as-a-service efficiency.

🧱 Architecture

llm-d accelerates distributed inference by integrating industry-standard open technologies like vLLM and Kubernetes. For more details, see our full Architecture Documentation.

📦 Releases

Our guides are living docs and kept current. For details about the Helm charts and component releases, visit our GitHub Releases page to review release notes.

See the accelerator docs for points of contact and more details about the accelerators, networks, and configurations tested.

Contribute

We adhere to the CNCF Code of Conduct.

See our project overview for more details on our development process and governance.
Review our contributing guidelines for detailed information on how to contribute to the project.
Join one of our Special Interest Groups (SIGs) to contribute to specific areas of the project and collaborate with domain experts.
We use Slack to discuss development across organizations. Please join: Slack
We host a bi-weekly standup for contributors every other Wednesday at 12:30 PM ET, as well as meetings for various SIGs. You can find them in the shared llm-d calendar
We use Google Groups to share architecture diagrams and other content. Please join: Google Group

License

This project is licensed under Apache License 2.0. See the LICENSE file for details.

kodekloudhub/certified-kubernetes-administrator-course

Certified Kubernetes Administrator - CKA Course

Certified Kubernetes Administrator (CKA) Course

These are notes from the Certified Kubernetes Administrator Course hosted on KodeKloud.

Sections

quickemu-project/quickemu

Quickly create and run optimised Windows, macOS and Linux virtual machines

Quickemu

Quickly create and run optimised Windows, macOS and Linux virtual machines:

Made with 💝 for &

Introduction

Quickemu is a wrapper for the excellent QEMU that automatically "does the right thing" when creating virtual machines. No requirement for exhaustive configuration options. You decide what operating system you want to run and Quickemu takes care of the rest 🤖

quickget automatically downloads the upstream OS and creates the configuration 📀
quickemu enumerates your hardware and launches the virtual machine with the optimum configuration best suited to your computer ⚡️

The original objective of the project was to enable quick testing of Linux distributions where the virtual machines and their configuration can be stored anywhere (such as external USB storage or your home directory) and no elevated permissions are required to run the virtual machines.

Today, Quickemu includes comprehensive support for macOS, Windows, most of the BSDs, novel non-Linux operating systems such as FreeDOS, Haiku, KolibriOS, OpenIndiana, ReactOS, and more.

Features

Host support for Linux and macOS
macOS Sequoia, Sonoma, Ventura, Monterey, Big Sur, Catalina & Mojave
Windows 10 and 11 including TPM 2.0
Windows Server 2022 2019 2016
ARM64 guest support for running aarch64 VMs (native on ARM hosts, emulated on x86_64)
Ubuntu and all the official Ubuntu flavours
Nearly 1000 operating system editions are supported!
Full SPICE support including host/guest clipboard sharing
VirtIO-webdavd file sharing for Linux and Windows guests
VirtIO-9p file sharing for Linux and macOS guests
QEMU Guest Agent support; provides access to a system-level agent via standard QMP commands
Samba file sharing for Linux, macOS and Windows guests (if smbd is installed on the host)
VirGL acceleration
USB device pass-through
Smartcard pass-through
Automatic SSH port forwarding to guests
Network port forwarding
Full duplex audio
Braille support
EFI (with or without SecureBoot) and Legacy BIOS boot

As featured on Linux Matters podcast!

The presenters of Linux Matters 🐧🎙️ are the creators of each of the principal Quickemu projects. We discussed Quickemu's 2024 reboot in Episode 30 - Quickemu Rising From the Bashes.

Linux Matters Podcast

Quick start

Once Quickemu is installed, there are two simple steps to create and run a virtual machine:

quickget automatically downloads the ISO image for the operating system you want to run and creates a configuration file for the virtual machine.

quickget nixos unstable minimal

quickemu starts the virtual machine using the configuration file created by quickget.

quickemu --vm nixos-unstable-minimal.conf

Execute quickget (with no arguments) to see a list of all the supported operating systems.

Demo

Documentation

The wiki describes how to get up and running with Quickemu and also covers more advanced configuration and usage.

Steam-Headless/docker-steam-headless

A Headless Steam Docker image supporting NVIDIA GPU and accessible via Web UI

Headless Steam Service

Remote Game Streaming Server.

Play your games either in the browser with audio or via Steam Link or Moonlight. Play from another Steam Client with Steam Remote Play.

Easily deploy a Steam Docker instance in seconds.

Features:

Steam Client configured for running on Linux with Proton
Moonlight compatible server for easy remote desktop streaming
Easy installation of EmeDeck, Heroic and Lutris via Flatpak
Full video/audio noVNC web access to a Xfce4 Desktop
NVIDIA, AMD and Intel GPU support
Full controller support
Support for Flatpak and Appimage installation
Root access
Based on Debian Trixie

Notes:

ADDITIONAL SOFTWARE:

If you wish to install additional applications, you can generate a script inside the ~/init.d directory ending with ".sh". This will be executed on the container startup.

Also, you can install applications using the WebUI under Applications > System > Software. There you can install other game launchers like Lutris, Heroic or EmuDeck.

STORAGE PATHS:

Everything that you wish to save in this container should be stored in the home directory or a docker container mount that you have specified. All files that are store outside your home directory are not persistent and will be wiped if there is an update of the container or you change something in the template.

GAMES LIBRARY:

It is recommended that you mount your games library to /mnt/games and configure Steam to add that path.

AUTO START APPLICATIONS:

In this container, Steam is configured to automatically start. If you wish to add additional services to automatically start, add them under Applications > Settings > Session and Startup in the WebUI.

NETWORK MODE:

If you want to use the container as a Steam Remote Play (previously "In Home Streaming") host device you should create a custom network and assign this container it's own IP, if you don't do this the traffic will be routed through the internet since Steam thinks you are on a different network.

USING HOST X SERVER:

If your host is already running X, you can just use that. To do this, be sure to configure:

DISPLAY=:0
(Variable) - Configures the sceen to use the primary display. Set this to whatever your host is using
MODE=secondary
(Variable) - Configures the container to not start an X server of its own
HOST_DBUS=true
(Variable) - Optional - Configures the container to use the host dbus process
/run/dbus:/run/dbus:ro
(Mount) - Optional - Configures the container to use the host dbus process

Installation:

Running locally:

For a development environment, I have created a script in the devops directory.

TODO:

Remove SSH
Require user to enter password for sudo
Document how to run this container:
- Other server OS
- TrueNAS Scale

jnMetaCode/agency-agents-zh

🎭 267 个即插即用的 AI 专家角色 — 支持 Hermes Agent/Claude Code/Cursor/Copilot 等 18 种工具，覆盖工程/设计/营销/金融等 20 个部门。含 52 个中国市场原创智能体（小红书/抖音/微信/飞书/钉钉等）。搭配编排器 agency-orchestrator，一句话即可让多位专家按 DAG 自动协作。

agency-agents 中文版（AI 智能体专家团队）

🌐 简体中文 | 繁體中文 | English (upstream)

268 个即插即用的 AI 专家角色 — 覆盖工程、设计、营销、产品、游戏、安全、GIS、金融等 20 个部门。不是通用提示词模板，每个智能体都有独立的人设、专业流程和可交付成果。支持 Claude Code / Cursor / Copilot 等 18 种 AI 编程工具。

agency-agents 的中文社区版。在完整翻译上游的基础上，新增了 50 个中国市场原创智能体（小红书、抖音、微信、B站、飞书、钉钉等平台运营，以及跨境电商、政务ToG、医疗合规、Qt 工业上位机、机械设计、畜禽养殖档案核对等垂直领域）。

想更好地用起来，或想给团队打造统一的智能体工作台？下载桌面客户端（原生 App，免装 Node，macOS / Windows / Linux），或在线体验 ao.aiolaola.com/experts。

📊 项目规模

🤖 AI 智能体	🌏 英文版翻译	🇨🇳 中国市场原创	🧠 支持工具	🏢 部门
268	215	53	18 种	20 个

📖 官方配套课程 → AI 专家团队实战（33 节，免费）：手把手把这仓 268 位专家用成一支团队——单兵点名、自动组队、一人公司全流程，桌面端零代码教学。另有从零学会 AI 编程（180 节）＋从零构建 AI 智能体（40 节）

🌍 Also available in English · 日本語 · Español · 한국어 · 繁體中文

🙏 赞助商 _{想出现在这里？联系 jnMetaCode@qq.com}

感谢 APINEBULA 大屏赞助本项目！APINEBULA 是银河录像局旗下的企业级 AI 聚合平台，背靠大平台资源，面向开发者、团队与企业用户提供稳定、高性价比的大模型 API 接入服务。平台聚合 Claude、GPT、Gemini 等主流满血模型，一个接口接入全球顶尖 AI 大模型，各大模型价格低至 1 折起，支持企业级高并发、正式合同、对公打款与开票服务，适合 AI 编程、Agent 开发、业务系统集成等多种场景！

🎁 通过此链接注册并在充值时填写 "agent" 优惠码可享九折优惠！

感谢多元探索赞助了本项目！多元探索专注全球AI模型API聚合与源头直供服务，已与多家头部科技企业建立合作，汇集OpenAI、Claude、Gemini、DeepSeek等数百款主流模型。平台构建统一、稳定、安全、高性价比的服务体系，实现一次接入、多模型调用，持续提升使用效率并优化算力成本；同时提供企业级解决方案、专业技术支持与快速客服响应，为每一次AI调用提供可靠保障。

🎁 通过专属链接注册后立获3元免费测试额度，充值100元以上返现10%（找客服获取）！

感谢 AICodeMirror 赞助了本项目！AICodeMirror 提供 Claude / Codex / Gemini 官方高稳定中转服务，支持企业级高并发、极速开票、7×24 专属技术支持。Codex 官方渠道低至 0.7 折，充值更有折上折！🎁 AICodeMirror 为 agency-agents-zh 项目的用户提供了特别福利，通过此链接注册的用户，可享受首充 8 折！

感谢 Cubence 对本项目的支持。Cubence 是一家致力为客户提供稳定、高效的 API 中转服务商。从 25 年 9 月运营至今，提供了 Claude Code、Codex、Gemini 等多种模型支持。🎁 通过此链接注册的用户，首次购买时填写专属优惠码 AGENCY 即可享受 9 折优惠！

感谢火山引擎赞助了本项目！火山引擎AI巅峰盛惠来袭！豆包大模型限时5折起，19元即可入手约440万Tokens文本模型，新客首单再享AI统一节省计划。从文本生成、图像创作到视频合成、语音复刻，全模态AI能力一站式配齐。开发者专属编程模型套餐2.5折订阅，支持Kimi-K2.7、GLM-5.2等主流模型。 🎁 注册即领2500万Tokens，立即访问火山引擎活动页面抢购。

感谢优云智算赞助了本项目！优云智算是UCloud旗下AI云平台，主打包月、按次的高性价比国模Agent Plan套餐，支持GLM5.2 低至49元/月起。同时提供官转稳定海外模型。支持接入 Claude Code、Codex 及 API 调用。支持企业高并发、7*24技术支持、自助开票。🎁 通过此链接注册的用户，可得免费5元平台体验金！

🚀 让角色库跑起来 · Agency Orchestrator

一句话，让多个 AI 专家自动组队协作，几分钟交付完整方案。

npm install -g agency-orchestrator
ao compose "帮我写一篇关于 AI Agent 的深度分析文章" --run

不想用命令行？ 下载桌面客户端（原生 App，免装 Node，macOS / Windows / Linux），或在线体验 ao.aiolaola.com/experts。

零代码编排 · DAG 并行 · 断点续跑 · 10 种大模型（7 种免 key）· 现成模板开箱即用 —— 了解 Agency Orchestrator →

🖼️ 在线浏览全部专家（无需安装）

搜索 / 按部门筛选 / 查看与复制每位专家的完整提示词 —— 全部 268 位，直接在浏览器里看：

🔗 在线专家库 ao.aiolaola.com/experts →

这是什么？

一套开箱即用的 AI 角色库。每个智能体都有明确的身份定义、关键规则、工作流程和交付物，安装到你的 AI 编程工具后用自然语言激活。

和普通提示词的区别：普通提示词告诉 AI "你是一个专家"；这里的智能体定义了专家怎么思考、怎么做事、交付什么。例如安全工程师会按 OWASP Top 10 逐项审查代码，小红书运营专家会输出完整的种草笔记策略和达人合作方案。

快速开始

方式一：一键安装到你的 AI 工具

支持 18 种主流 AI 编程工具，一条命令搞定：

# 自动检测已安装的工具，一键安装
./scripts/install.sh

# 或指定安装到特定工具
./scripts/install.sh --tool openclaw       # OpenClaw ⭐ 推荐
./scripts/install.sh --tool claude-code    # Claude Code
./scripts/install.sh --tool copilot        # GitHub Copilot
./scripts/install.sh --tool cursor         # Cursor
./scripts/install.sh --tool kiro           # Kiro (Amazon)
./scripts/install.sh --tool trae           # Trae
./scripts/install.sh --tool opencode       # OpenCode
./scripts/install.sh --tool aider          # Aider
./scripts/install.sh --tool windsurf       # Windsurf
./scripts/install.sh --tool antigravity    # Antigravity
./scripts/install.sh --tool gemini-cli     # Gemini CLI
./scripts/install.sh --tool qwen           # Qwen Code
./scripts/install.sh --tool codex          # Codex CLI
./scripts/install.sh --tool deerflow       # DeerFlow 2.0 (ByteDance)
./scripts/install.sh --tool workbuddy      # WorkBuddy (Tencent)
./scripts/install.sh --tool codewhale      # CodeWhale (原 DeepSeek-TUI)
./scripts/install.sh --tool hermes         # Hermes Agent (NousResearch)
./scripts/install.sh --tool qoder          # Qoder

Claude Code 和 GitHub Copilot 可直接安装；其他工具需先运行 ./scripts/convert.sh 转换格式。

🔥 OpenClaw 用户快速上手

OpenClaw 是目前社区用户最多的集成方式，每个智能体会拆分为三个文件：SOUL.md（身份人设）+ AGENTS.md（业务能力）+ IDENTITY.md（简介），天然支持多智能体协作编排。

./scripts/convert.sh --tool openclaw   # 第一步：转换为 SOUL.md 格式
./scripts/install.sh --tool openclaw   # 第二步：安装到 ~/.openclaw/

安装后重启 OpenClaw 网关即可使用。

方式二：手动复制

# Claude Code / GitHub Copilot（直接复制即可）
cp -r marketing/*.md ~/.claude/agents/

# 在 Claude Code 中激活：
# "激活前端开发者模式，帮我构建一个 React 组件"

方式三：作为提示词参考

浏览下方智能体列表，复制/改编你需要的内容！

智能体阵容

🛠️ 工程部

构建未来，一个 commit 一个脚印。

智能体	专长	适用场景
前端开发者	React/Vue、UI 实现、性能优化	现代 Web 应用、像素级 UI
后端架构师	API 设计、数据库架构、可扩展性	服务端系统、微服务
AI 工程师	机器学习、模型部署、AI 集成	ML 功能、数据管线
DevOps 自动化师	CI/CD、基础设施自动化	流水线开发、部署自动化
安全工程师	威胁建模、代码审计、安全架构	应用安全、漏洞评估
快速原型师	快速 POC、MVP 开发	概念验证、黑客马拉松
高级开发者	Laravel/Livewire/FluxUI、高端 CSS、Three.js	高品质 Web 体验
移动应用开发者	iOS/Android 原生、跨平台框架	移动端开发、App 性能优化
数据工程师	ETL/ELT、数据湖、Spark/dbt	数据管线、数据仓库
技术文档工程师	API 文档、开发者文档、docs-as-code	技术文档、知识库
自主优化架构师	自适应系统、自动调优	智能运维、自愈系统
嵌入式固件工程师	RTOS、外设驱动、低功耗设计	IoT、嵌入式系统
上位机工程师 ⭐	Qt/QML、QSerialPort、Modbus/CAN、QChart 实时可视化	工业上位机、检测设备、HMI
机械设计工程师 ⭐	传动选型、强度刚度疲劳振动校核、DFMA、GB/ISO 标准件	工业装备、自动化产线、检测仪器
嵌入式 Linux 驱动工程师 ⭐	内核模块、设备树、Platform/I2C/SPI 驱动	嵌入式 Linux BSP 开发
FPGA/ASIC 数字设计工程师 ⭐	Verilog/SystemVerilog、时序收敛、AXI 总线	FPGA 开发、数字逻辑设计
IoT 方案架构师 ⭐	MQTT/CoAP、边缘计算、设备管理、云平台	物联网端到端方案设计
国内网络工程师 ⭐	华为 VRP/华三 Comware/锐捷、VLAN/OSPF/BGP/VXLAN、信创国产化、等保组网	国产设备园区网/数据中心/广域网
故障响应指挥官	故障处置、SLO 管理、事后复盘	线上故障、应急响应
威胁检测工程师	SIEM、威胁狩猎、检测规则	安全运营、威胁检测
Solidity 智能合约工程师	Solidity、EVM、Gas 优化、DeFi	智能合约开发、Web3
微信小程序开发者 ⭐	WXML/WXSS、微信支付、云开发	微信小程序全栈开发
代码审查员	代码审查、安全审计、质量把关	PR 审查、代码质量
数据库优化师	Schema 设计、查询优化、索引策略	数据库性能调优
Git 工作流大师	分支策略、约定式提交、变基	Git 工作流规范
软件架构师	系统设计、DDD、架构决策	系统架构设计
SRE (站点可靠性工程师)	SLO、可观测性、混沌工程	站点可靠性工程
AI 数据修复工程师	自愈管道、SLM 语义聚类、零数据丢失	大规模数据异常修复
飞书集成开发工程师 ⭐	飞书机器人、审批流、多维表格	飞书生态集成开发
钉钉集成开发工程师 ⭐	钉钉机器人、酷应用、连接器	钉钉生态集成开发
CMS 开发者	Drupal/WordPress、主题开发、自定义插件	CMS 站点开发与内容架构
邮件智能工程师	邮件解析、结构化提取、AI 推理数据	智能体邮件集成
Filament 优化专家	Filament PHP 后台重构、高影响力改造	PHP 后台管理优化

🎨 设计部

让产品好看、好用、有惊喜。

智能体	专长	适用场景
UI 设计师	视觉设计、组件库、设计系统	界面设计、品牌一致性
UX 研究员	用户测试、行为分析	用户研究、可用性测试
UX 架构师	信息架构、交互设计、导航系统	复杂产品的 UX 架构
品牌守护者	品牌标识、一致性、定位	品牌策略、视觉规范
图像提示词工程师	AI 图像生成、提示词优化	Midjourney/DALL-E 出图
视觉叙事师	数据可视化、视觉叙事	信息图、演示文稿
趣味注入师	微交互、彩蛋、趣味元素	产品细节体验提升
包容性视觉专家	多元化视觉、无障碍设计	包容性设计、全球化视觉

📢 营销部

一个真实互动一个粉丝地增长。

国内平台：

智能体	专长	适用场景
小红书运营专家 ⭐	种草笔记、达人合作、爆款内容	小红书获客、品牌种草
抖音策略师 ⭐	短视频策划、算法优化、直播带货	抖音增长、短视频营销
微信公众号运营 ⭐	公众号内容、社群运营、裂变增长	微信生态营销
B站内容策略师 ⭐	UP主运营、弹幕文化、中长视频	B站内容增长、品牌合作
快手策略师 ⭐	下沉市场、老铁文化、直播电商	快手运营、社区信任
中国电商运营专家	淘宝/拼多多/京东、广告投放、大促作战	电商全链路深度运营
电商运营师 ⭐	淘宝/拼多多/京东、直播带货、大促	电商全平台运营（简洁版）
百度 SEO 专家 ⭐	百度优化、百科/知道/贴吧生态	百度搜索营销
私域流量运营师 ⭐	企微SCRM、社群运营、用户生命周期	私域体系搭建、复购增长
直播电商主播教练 ⭐	直播话术、选品排品、千川投放	直播带货、主播孵化
跨境电商运营专家 ⭐	Amazon/Shopee/Lazada、海外仓、品牌出海	跨境电商全链路运营
短视频剪辑指导师 ⭐	剪映/PR/达芬奇、调色、音频、特效	短视频剪辑技术指导
微博运营策略师 ⭐	热搜运营、超话、舆情公关、粉丝经济	微博全链路运营
播客内容策略师 ⭐	小宇宙/喜马拉雅、音频制作、商业化	播客内容创作与增长
微信视频号运营策略师 ⭐	视频号直播、社交裂变、私域闭环	视频号运营与变现
知识付费产品策划师 ⭐	得到/知识星球/小鹅通、内容定价	知识付费产品运营
小红书专家	生活方式内容、趋势策略	小红书品牌建设
微信公众号管理	订阅者运营、内容营销	微信公众号增长
知乎策略师	知识型内容、思想领袖建设	知乎品牌权威
中国市场本地化策略师 ⭐	抖音/小红书/微信/B站全栈本地化	中国市场进入策略
新闻情报官 ⭐	国内外多源新闻采集、交叉验证、结构化简报	内容生产线上游素材供应

⭐ 标记的是本项目原创，更贴合国内实操。其余为上游英文版翻译。

出海营销：

智能体	专长	适用场景
TikTok 策略师	病毒式内容、算法优化	出海短视频营销
Twitter 互动官	实时互动、思想领袖	出海品牌社交
Instagram 策展师	视觉叙事、社区运营	出海视觉营销
Reddit 社区运营	社区文化、真实互动	出海社区营销
应用商店优化师	ASO、转化优化	App 出海推广
视频优化专家	YouTube 算法、观众留存、跨平台分发	视频营销与 SEO

通用：

智能体	专长	适用场景
增长黑客	快速获客、病毒循环、实验	用户增长、转化优化
内容创作者	多平台内容、编辑日历	内容策略、品牌故事
社交媒体策略师	跨平台策略、整合营销	全渠道社交运营
SEO 专家	搜索引擎优化、技术 SEO	Google SEO、内容优化
轮播图增长引擎	轮播图内容、自动化投放	社交媒体轮播素材
LinkedIn 内容创作专家	LinkedIn 职场内容、B2B 获客	LinkedIn 品牌建设
图书联合作者	思想领袖力图书、代笔协作	图书策划与撰写
AI 引文策略师	AEO/GEO 优化、AI 平台可见性审计	AI 搜索引擎品牌可见性

💰 付费媒体部

精准投放，每一分预算都花在刀刃上。

智能体	专长	适用场景
付费媒体审计师	广告账户审计、预算优化	广告效果诊断、降本增效
广告创意策略师	广告素材策划、A/B 测试	广告创意优化
社交广告策略师	社交平台广告投放	Meta/TikTok/LinkedIn 广告
PPC 竞价策略师	搜索竞价、关键词管理	Google Ads、百度推广
程序化广告采买专家	DSP、RTB、程序化购买	程序化广告投放
搜索词分析师	搜索词挖掘、否词优化	搜索广告精细化运营
追踪与归因专家	转化追踪、归因模型	广告效果衡量、数据打通

💼 销售部

从线索到成交，让每一单都有章法。

智能体	专长	适用场景
客户拓展策略师	大客户拓展、ABM 策略	重点客户攻关
销售教练	销售辅导、技能提升	团队销售能力建设
赢单策略师	成交策略、MEDDPICC	复杂销售推进
Discovery 教练	需求挖掘、客户洞察	销售前期沟通
售前工程师	技术方案、Demo 演示	技术售前支持
Outbound 策略师	外呼策略、Cold outreach	新客户开拓
Pipeline 分析师	销售漏斗、预测分析	销售数据分析、预测
投标策略师	投标方案、提案撰写	招投标、方案竞标

🏦 金融部

让每一笔钱都清清楚楚。

智能体	专长	适用场景
财务预测分析师 ⭐	收入预测、场景建模、现金流	SaaS 财务规划、融资对接
发票管理专家 ⭐	增值税发票、金税系统、三单匹配	发票全生命周期管理
金融风控分析师 ⭐	交易风控、反洗钱、电信诈骗	支付风控、合规审查

👔 人力资源部

找对人、用好人、留住人。

智能体	专长	适用场景
招聘专家 ⭐	Boss直聘/猎聘、校招社招、背调	招聘全流程管理
绩效管理专家 ⭐	OKR/KPI、361分布、晋升答辩	绩效体系搭建与评估

⚖️ 法务部

合规是底线，风控是生命线。

智能体	专长	适用场景
合同审查专家 ⭐	民法典合同编、电子签章、风险评估	合同审查与风控
制度文件撰写专家 ⭐	PIPL/数据安全法、隐私政策	合规制度与政策撰写

🚚 供应链部

从工厂到用户，每一环都不掉链子。

智能体	专长	适用场景
库存预测专家 ⭐	需求预测、安全库存、618/双11备货	库存管理与补货优化
供应商评估专家 ⭐	1688供应商、验厂、国标质检	供应商准入与分级管理
物流路线优化师 ⭐	顺丰/通达系、冷链、跨境物流	物流成本优化与路线规划
供应链采购策略师 ⭐	1688采购、质检、供应商管理、ERP	供应链与采购管理

📦 产品部

在正确的时间做正确的事。

智能体	专长	适用场景
Sprint 排序师	敏捷规划、功能优先级	Sprint 规划、资源分配
趋势研究员	市场情报、竞品分析	市场调研、机会评估
反馈分析师	用户反馈分析、洞察提取	反馈分析、产品优先级
行为助推引擎	行为心理学、用户引导	用户行为设计、转化提升
产品经理	产品全生命周期、PRD、路线图	产品策略与交付管理

📋 项目管理部

让项目按时按质交付。

智能体	专长	适用场景
高级项目经理	需求拆解、范围管控	大型项目管理
项目牧羊人	跨团队协调、进度跟踪	多团队项目协调
实验追踪员	A/B 测试、实验管理	数据驱动决策
工作室制片人	创意项目管理、资源调度	内容/创意项目
工作室运营	工作室日常运营管理	团队运营效率
Jira 工作流管家	Jira 配置、工作流优化	Jira 项目管理

🧪 测试部

打破一切，让用户不必承受。

智能体	专长	适用场景
证据收集者	截图 QA、视觉验证	UI 测试、Bug 文档
现实检验者	证据驱动认证、质量关卡	生产就绪评估
API 测试员	API 验证、集成测试	接口测试、端点验证
性能基准师	性能测试、优化	压测、性能调优
无障碍审核员	WCAG 审核、辅助技术测试	无障碍合规、包容性设计
测试结果分析师	测试数据分析、质量度量	质量趋势、发布决策
工具评估师	工具选型、功能对比	技术选型、工具采购
工作流优化师	流程分析、自动化	效率提升、流程改进
嵌入式测试工程师 ⭐	HIL 测试、固件自动化测试、EMC 测试	嵌入式质量保障、量产测试

🤝 支持部

运营的中流砥柱。

智能体	专长	适用场景
客服响应者	客户服务、工单处理	客户支持、用户体验
数据分析师	数据分析、仪表盘	商业智能、KPI 追踪
法务合规员	合规审查、法规检查	法律合规、风险管理
高管摘要师	业务摘要、战略沟通	高管汇报、决策支持
财务追踪员	财务分析、预算管理	财务规划、成本管控
基础设施运维师	系统运维、可靠性工程	基础设施管理、故障排查
招聘运营专家 ⭐	Boss直聘/猎聘、劳动法、校招社招	招聘全流程与HR合规

🔬 专项部

不走寻常路的专家。

智能体	专长	适用场景
智能体编排者	多智能体协调、工作流管理	复杂项目的多智能体协作
提示词工程师 ⭐	LLM 提示词设计、优化、评测	提示词开发、AI 应用优化
身份信任架构师	AI 身份验证、信任框架	AI 系统安全与信任
数据整合师	多源数据整合、仪表盘	数据汇总与可视化
LSP 索引工程师	代码智能、语义索引	代码导航、IDE 集成
报告分发师	报告分发、多渠道推送	自动化报告分发
销售数据提取师	销售数据采集、结构化	CRM 数据处理
合规审计师	SOC 2/ISO 27001/HIPAA 合规	合规审计、安全认证
应付账款智能体	发票处理、付款自动化	财务流程自动化
身份图谱操作员	身份解析、多源匹配	用户身份治理
文化智能策略师	文化洞察、跨文化设计	全球化产品、本地化策略
开发者布道师	开发者关系、DX 工程	开发者社区、技术推广
模型 QA 专家	ML 模型审计、质量验证	模型上线前检查
ZK 管家	Zettelkasten 知识管理	知识库构建、笔记系统
区块链安全审计师	智能合约审计、漏洞检测	合约安全、DeFi 审计
留学规划顾问 ⭐	多国申请策略、选校定位	留学规划、文书指导
政务数字化售前顾问 ⭐	方案设计、标书、等保/信创	政务ToG项目售前
企业培训课程设计师 ⭐	ADDIE/SAM、企业学习平台、TTT	培训体系搭建与课程开发
MCP 构建器	MCP 服务器、工具设计、API 集成	MCP 开发、AI 工具扩展
文档生成器	PDF/PPTX/DOCX/XLSX 生成	程序化文档创建
工作流架构师	工作流树设计、交接契约、故障恢复	系统流程规格化
自动化治理架构师	自动化审计、n8n 工作流治理、风险评估	业务自动化决策
Salesforce 架构师	Salesforce 多云设计、集成、数据模型	企业级 Salesforce 架构
医疗健康营销合规师 ⭐	医疗广告法、NMPA、互联网医疗	医疗健康营销合规
高考志愿填报顾问 ⭐	平行志愿、位次法、冲稳保策略	高考志愿填报规划
动态定价策略师 ⭐	淘宝/京东/拼多多定价、大促机制	电商定价与促销策略
AI 治理政策专家 ⭐	算法备案、生成式AI管理、伦理审查	AI 合规与治理框架
企业风险评估师 ⭐	COSO本土化、国企风控、ESG	企业风险管理与审计
会议效率专家 ⭐	飞书/钉钉/腾讯会议、OKR周会	会议管理与纪要输出
土木工程师	Eurocode/DIN/ACI/GB 多标准结构分析	土木与结构工程设计
法国咨询市场专家	ESN/SI 生态、Malt 平台、薪资代管	法国自由职业市场导航
韩国商务专家	품의流程、KakaoTalk 礼仪、层级关系	韩国商务文化导航
招聘专家 ⭐	国内招聘平台、人才评估、劳动法合规	招聘运营与雇主品牌
技术翻译专家	中英文双向翻译、编程/AI/云计算术语	技术文档翻译

🥽 空间计算部

构建下一代空间交互体验。

智能体	专长	适用场景
visionOS 空间工程师	visionOS、SwiftUI 空间 UI	Apple Vision Pro 开发
macOS Metal 空间工程师	Metal、GPU 渲染	macOS 高性能图形
XR 界面架构师	空间 UI 架构、交互设计	XR 应用界面设计
XR 沉浸式开发者	WebXR、沉浸式体验	VR/AR 应用开发
XR 座舱交互专家	座舱 UI、多模态交互	汽车/航空 XR 交互
终端集成专家	终端模拟、系统集成	空间计算终端工具

🎮 游戏开发部

从独立游戏到 3A 大作，全引擎覆盖。

通用：

智能体	专长	适用场景
游戏设计师	游戏机制、系统设计、平衡性	游戏核心玩法设计
关卡设计师	关卡布局、节奏控制、空间叙事	关卡设计、场景构建
叙事设计师	剧情设计、对话系统、世界观	游戏剧情、互动叙事
技术美术	Shader、渲染管线、美术工具	画面效果、性能优化
游戏音频工程师	音效设计、音频引擎、空间音频	游戏音效、配乐

Unity：

智能体	专长	适用场景
Unity 架构师	Unity 架构、ECS、性能优化	Unity 项目架构
Unity 编辑器工具开发者	编辑器扩展、自定义工具	Unity 工具链开发
Unity 多人游戏工程师	Netcode、同步、网络架构	Unity 联机游戏
Unity Shader Graph 美术师	Shader Graph、URP/HDRP	Unity 视觉效果

Unreal Engine：

智能体	专长	适用场景
Unreal 多人游戏架构师	Replication、网络同步	UE 联机架构
Unreal 系统工程师	Gameplay 框架、C++ 系统	UE 核心系统开发
Unreal 技术美术	材质、Niagara、渲染管线	UE 画面与性能
Unreal 世界构建师	开放世界、地形、关卡串流	UE 场景构建

Blender：

智能体	专长	适用场景
Blender 插件工程师	Python 插件、资源验证、导出自动化	Blender 管线工具开发

Godot：

智能体	专长	适用场景
Godot 游戏脚本开发者	GDScript、场景树、信号系统	Godot 游戏逻辑
Godot 多人游戏工程师	MultiplayerAPI、网络同步	Godot 联机游戏
Godot Shader 开发者	Godot Shader Language、视觉效果	Godot 画面效果

Roblox Studio：

智能体	专长	适用场景
Roblox 虚拟形象创作者	虚拟形象、UGC 资产	Roblox 角色设计
Roblox 体验设计师	体验设计、游戏循环	Roblox 游戏设计
Roblox 系统脚本工程师	Luau 脚本、数据存储	Roblox 游戏开发

📖 学术部

为叙事设计、世界构建和文化研究提供学术级支撑。

智能体	专长	适用场景
人类学家	文化体系、仪式、民族志	世界观设计、文化构建
地理学家	自然与人文地理、空间分析	地图构建、场景设计
历史学家	历史分析、史料考证	历史题材验证、年代设定
叙事学家	叙事理论、故事结构	剧情设计、角色弧线
心理学家	行为心理、人格理论	角色心理塑造、动机设计
学习规划师 ⭐	考研/考公/法考备考、学习方法论	个性化学习计划与备考规划

🎯 战略部

从发现到运营的全流程战略指导。详见 strategy/ 目录。

文档	内容
高管简报	NEXUS 战略概览
快速上手	5 分钟上手指南
完整战略	运营纲领全文
智能体激活提示词	各智能体的激活指令
交接模板	智能体间的交接规范
Phase 0-6 Playbooks	发现 · 策略 · 基础 · 构建 · 加固 · 上线 · 运营
场景 Runbook	创业 MVP · 企业功能 · 事故响应 · 营销活动

工具集成

支持 18 种主流 AI 编程工具，通过 scripts/ 目录下的脚本实现格式转换和一键安装。

支持的工具

工具	安装位置	类型
OpenClaw ⭐	`~/.openclaw/agency-agents/`	全局，需转换
Claude Code	`~/.claude/agents/`	全局，直接复制
GitHub Copilot	`~/.github/agents/` + `~/.copilot/agents/`	全局，直接复制
Kiro (Amazon)	`~/.kiro/agents/`	全局，需转换
Antigravity	`~/.gemini/antigravity/skills/`	全局，需转换
Gemini CLI	`~/.gemini/extensions/agency-agents/`	全局，需转换
Qwen Code	`.qwen/agents/`	项目级，需转换
Cursor	`.cursor/rules/`	项目级，需转换
Trae	`.trae/rules/`	项目级，需转换
OpenCode	`.opencode/agents/`	项目级，需转换
Aider	`CONVENTIONS.md`	项目级，需转换
Windsurf	`.windsurfrules`	项目级，需转换
Codex CLI	`.codex/agents/`	项目级，需转换
WorkBuddy (腾讯)	`~/.workbuddy/skills/`	全局，需转换
CodeWhale (原 DeepSeek-TUI)	`~/.codewhale/skills/`	全局，需转换
Hermes Agent (NousResearch)	`~/.hermes/skills/`	全局，需转换
DeerFlow 2.0 (字节跳动)	`skills/custom/`	项目级，需转换
Qoder	`~/.qoder/agents/` 或 `.qoder/agents/`	全局/项目级，需转换

使用方法

# 第一步：转换格式（Claude Code 和 GitHub Copilot 可跳过此步）
./scripts/convert.sh                    # 转换为所有工具格式
./scripts/convert.sh --tool cursor      # 只转换 Cursor 格式

# 第二步：安装到本地
./scripts/install.sh                    # 自动检测并安装
./scripts/install.sh --tool cursor      # 安装到指定工具

# 检查智能体文件格式
./scripts/lint-agents.sh

各工具安装说明

⭐ OpenClaw（推荐）

OpenClaw 会将每个智能体拆分为三个文件，天然支持多智能体协作：

SOUL.md — 身份、记忆、沟通风格、关键规则
AGENTS.md — 核心使命、技术交付物、工作流程
IDENTITY.md — 名称与简介

./scripts/convert.sh --tool openclaw
./scripts/install.sh --tool openclaw

# 安装后重启 OpenClaw 网关
openclaw gateway restart

Claude Code

智能体直接从仓库复制到 ~/.claude/agents/，无需转换。

./scripts/install.sh --tool claude-code

在 Claude Code 中激活：

激活前端开发者模式，帮我审查这个组件。

GitHub Copilot

智能体直接从仓库复制到 ~/.github/agents/ 和 ~/.copilot/agents/，无需转换。

./scripts/install.sh --tool copilot

在 GitHub Copilot 中激活：

使用前端开发者智能体帮我审查这个组件。

Antigravity (Gemini)

转换为 Antigravity skill 格式并安装到 ~/.gemini/antigravity/skills/。

./scripts/convert.sh --tool antigravity
./scripts/install.sh --tool antigravity

Gemini CLI

转换为 Gemini CLI 扩展格式并安装到 ~/.gemini/extensions/agency-agents/。

./scripts/convert.sh --tool gemini-cli
./scripts/install.sh --tool gemini-cli

Qwen Code

转换为 Qwen Code SubAgent 格式并安装到项目目录 .qwen/agents/。

./scripts/convert.sh --tool qwen
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool qwen

在 Qwen Code 中激活：

使用前端开发者智能体帮我审查这个组件。

提示：安装后在 Qwen Code 中运行 /agents manage 刷新，或重启会话。

Cursor

每个智能体会变成一个 .mdc 规则文件，安装到项目目录 .cursor/rules/。

Cursor 使用 "智能匹配"模式（alwaysApply: false）：AI 根据每个规则的 description 字段自动判断是否相关，相关时自动引用完整内容。

安装：

# 第一步：转换格式（在仓库目录运行）
./scripts/convert.sh --tool cursor

# 第二步：安装到项目（在你的项目目录运行）
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool cursor

⚠️ 重要：建议精选安装

全部安装 186 个规则会导致 Cursor 需要扫描大量 description 来判断相关性，可能影响匹配准确度。推荐做法：

# 方法一：全量安装后删除不需要的
/path/to/agency-agents-zh/scripts/install.sh --tool cursor
# 然后手动删除 .cursor/rules/ 中不需要的 .mdc 文件，保留 10-20 个常用的

# 方法二：只复制你需要的智能体（转换后）
./scripts/convert.sh --tool cursor
mkdir -p /your/project/.cursor/rules
cp integrations/cursor/rules/engineering-frontend-developer.mdc /your/project/.cursor/rules/
cp integrations/cursor/rules/engineering-code-reviewer.mdc /your/project/.cursor/rules/
# ... 按需复制

安装后如何使用：

安装后 .cursor/rules/ 中的 .mdc 文件会自动被 Cursor 识别

在 Chat 或 Composer 中正常提问，Cursor 自动匹配相关智能体：

帮我审查这个组件的性能问题   → 自动匹配前端开发者
这段代码有安全漏洞吗         → 自动匹配安全审计员

也可以在 Cursor Settings（Cmd+,）→ Rules → Project Rules 中查看所有规则
还可以在 Chat 中用 @规则名 手动指定引用某个智能体

排查：如果看不到规则，确认 .cursor/rules/ 在项目根目录、文件扩展名是 .mdc、已重新打开项目。

Trae

转换为 Trae rule 文件并安装到项目目录 .trae/rules/。格式与 Cursor 同源（仅扩展名 .md 不同）。

./scripts/convert.sh --tool trae
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool trae

⚠️ 关于"装了但几乎不自动触发"（见 issue #59）：

转换出的 rule 默认 alwaysApply: false + 空 globs:，属于 "agent-requested rule"——Trae 模型读 description 自行决定是否加载。全装 268 条 rule 会让 description 互相稀释、几乎命中不到任何一条，这是设计行为不是 bug。

正确姿势：

精选安装（推荐）：只挑 10–20 条常用 rule 放进 .trae/rules/，自动匹配才会真正起作用。
@ 显式调用：对话里输入 @engineering-pc-host-engineer ... 强制加载某条 rule。
核心 rule 改 alwaysApply：把代码审查、git 工作流之类的 1–3 条改成 alwaysApply: true 长期生效。

详细说明见 integrations/trae/README.md。

OpenCode

转换为 OpenCode agent 文件并安装到项目目录 .opencode/agents/。

./scripts/convert.sh --tool opencode
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool opencode

Aider

所有智能体编译为单个 CONVENTIONS.md 文件，Aider 会自动读取。

./scripts/convert.sh --tool aider
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool aider

在 Aider 会话中激活：

使用前端开发者智能体帮我重构这个组件。

Windsurf

所有智能体编译为单个 .windsurfrules 文件。

./scripts/convert.sh --tool windsurf
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool windsurf

Codex CLI

转换为 OpenAI Codex CLI agent 文件（TOML 格式）并安装到项目目录 .codex/agents/。

./scripts/convert.sh --tool codex
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool codex

在 Codex 中使用时，智能体会作为 subagent 被调用。也可以在 AGENTS.md 中引用。

Kiro (Amazon)

Amazon 的 Spec 驱动 AI IDE，基于 Claude 模型。每个智能体转换为 JSON 配置 + 提示词文件，安装到 ~/.kiro/agents/（全局）。

./scripts/convert.sh --tool kiro
./scripts/install.sh --tool kiro

在 Kiro 中切换智能体：

/agent swap

或启动时直接指定：

kiro-cli --agent engineering-frontend-developer

WorkBuddy (腾讯)

腾讯推出的全场景 AI 桌面智能体，兼容 OpenClaw 技能，支持多模型切换。每个智能体转换为 SKILL.md 技能文件，安装到 ~/.workbuddy/skills/（全局）。

./scripts/convert.sh --tool workbuddy
./scripts/install.sh --tool workbuddy

安装后重启 WorkBuddy 即可在技能列表中看到所有智能体。

CodeWhale（原 DeepSeek-TUI）

专为 DeepSeek 优化、对国内网络友好的终端编程 Agent（Rust 实现，原名 DeepSeek-TUI）。每个智能体转换为 SKILL.md 技能文件，安装到 ~/.codewhale/skills/（全局），在 CodeWhale 里用 /skills 加载。

./scripts/convert.sh --tool codewhale
./scripts/install.sh --tool codewhale

安装后在 CodeWhale 中输入 /skills 即可看到并调用所有智能体。

Hermes Agent (NousResearch)

NousResearch 的开源 AI 智能体框架，支持技能系统、子代理编排、会话记忆。每个智能体转换为 SKILL.md 技能文件，按分类目录安装到 ~/.hermes/skills/（全局）。

./scripts/convert.sh --tool hermes
./scripts/install.sh --tool hermes

安装后推荐在 Hermes CLI 中通过 hermes skills 查看和管理所有技能，或在对话中自然语言激活。

⚠️ Discord 模式下不要一次性全量安装

Hermes 的 Discord 集成会把每一个 skill 注册成 Discord 斜杠命令，Discord API 对 bot 所有命令的 JSON 序列化总长度有 8000 字符硬上限，超过后会返回 error code 50035（见 issue #45）。本仓库有近 200 个 skill，一次装全会直接炸 Discord。

解决办法：在 Discord 中使用时请按分类分批安装，用 --category 参数（可多次传入）：
# 只装 marketing 分类
./scripts/install.sh --tool hermes --category marketing

# 同时装 engineering 和 design
./scripts/install.sh --tool hermes --category engineering --category design
可选分类：academic, blender, design, engineering, finance, game-development, godot, hr, legal, marketing, paid-media, product, project-management, roblox-studio, sales, spatial-computing, specialized, supply-chain, support, testing, unity, unreal-engine。

Hermes CLI 本身没有此限制，全量安装可以继续使用。

DeerFlow 2.0 (字节跳动)

字节跳动的开源 SuperAgent 框架，支持子代理、沙箱、持久记忆。每个智能体转换为 SKILL.md 技能文件。

./scripts/convert.sh --tool deerflow
./scripts/install.sh --tool deerflow

默认安装到当前目录的 skills/custom/。可通过环境变量自定义路径：

DEERFLOW_SKILLS_DIR=/path/to/deerflow/skills/custom ./scripts/install.sh --tool deerflow

安装后在 DeerFlow 的任务中，相关技能会自动加载。

Qoder

转换为 Qoder SubAgent 格式（Markdown + YAML frontmatter）并安装到 ~/.qoder/agents/（全局）或项目目录 .qoder/agents/。

./scripts/convert.sh --tool qoder
./scripts/install.sh --tool qoder

在 Qoder 中使用：

自动触发：用自然语言描述任务，Qoder 根据 description 自动选择智能体
手动触发：输入 /agent-name（如 /engineering-frontend-developer）

官方文档：https://docs.qoder.com/zh/extensions/subagent

修改智能体后重新生成

添加新智能体或编辑现有智能体后，重新生成集成文件：

./scripts/convert.sh               # 重新生成所有工具
./scripts/convert.sh --tool cursor  # 只重新生成指定工具

🇨🇳 中国市场原创智能体

除翻译外，本项目包含 50 个原创智能体，专为中国平台和业务场景打造：

平台运营：小红书、抖音、微信公众号/视频号/小程序、B站、快手、微博、知乎
企业协作：飞书、钉钉集成开发
垂直领域：跨境电商、政务ToG、医疗合规、高考志愿、留学规划、Qt 工业上位机、通用机械设计、畜禽养殖档案核对
业务支撑：私域流量、直播电商、库存预测、合同审查、发票管理

在上方智能体阵容中标有 ⭐ 的即为原创智能体。

实战案例

场景一：出海产品 MVP

你的团队：

前端开发者 — 构建 React 应用
后端架构师 — 设计 API 和数据库
增长黑客 — 规划用户获取
快速原型师 — 快速迭代
现实检验者 — 上线前质量把关

场景二：小红书品牌推广（完整流程）

你的团队：

小红书运营专家 — 种草内容策略和达人合作
内容创作者 — 产出种草笔记
品牌守护者 — 品牌调性把关
数据分析师 — 追踪投放数据、出复盘报告
增长黑客 — 设计转化和裂变路径

贡献

欢迎参与！翻译智能体、改进内容、新增中国平台智能体都行。详见 CONTRIBUTING.md。

交流 · Community

_{微信扫码关注}

微信公众号 「AI不止语」（微信搜索 AI_BuZhiYu）— 技术问答 · 项目更新 · 实战文章

渠道	加入方式
QQ 2群	点击加入（群号 1071280067）
微信群	关注公众号后回复「群」获取入群方式

姊妹项目

项目	定位	一句话
本项目（agency-agents-zh）	🎭 专家角色库	268 个即插即用 AI 专家，含 53 中国原创（小红书 / 抖音 / 飞书 / 钉钉 / Qt 上位机 / 机械设计）
agency-orchestrator	🚀 编排引擎	一句话 → 268 专家协作，几分钟出方案（10 家 LLM / 7 免费）
superpowers-zh	🧠 工作方法论	20 个 skills 教 AI 怎么干活（TDD / 调试 / 代码审查等）
ai-coding-guide	📖 实战教程	66 个 Claude Code 技巧 + 9 款工具最佳实践 + 配置模板
shellward	🛡️ 安全中间件	8 层防御 + DLP 数据流 + 注入检测，零依赖（含 MCP Server）
🆕 ai-shortfilm-prompts	🎬 视频提示词	Mx-Shell《丧尸清道夫》5 段式方法论 + Skill，Seedance / 小云雀 / Sora / 可灵 / 即梦通用
🆕 local-agent-toolkit	🛠️ Agent 本地三件套	给 agent 配上记忆 / 技能管理 / 运行追踪，零依赖、数据不出本机（engram · skillet · tracelet，npx 即用）
🆕 codepet	🐾 桌面养成桌宠	码宠 CodePet —— 你写代码 / 用 Claude Code，它就涨经验、升级、换状态、跳舞。全本地、隐私优先、开源

致谢

原始英文版：msitarzewski/agency-agents（MIT 协议）
感谢原作者 @msitarzewski 创建了这个优秀的项目

许可证

MIT License — 自由使用，商业或个人均可。

268 个 AI 专家角色，18 种工具支持，即装即用

⭐ Star 本项目 · 提交 Issue · 贡献代码

基于 agency-agents 翻译并本土化

⭐ Star 趋势

a2aproject/A2A

Agent2Agent (A2A) is an open protocol enabling communication and interoperability between opaque agentic applications.

Agent2Agent (A2A) Protocol

🌐 Language

Agent2Agent (A2A) Protocol

An open protocol enabling communication and interoperability between opaque agentic applications.

The Agent2Agent (A2A) protocol addresses a critical challenge in the AI landscape: enabling gen AI agents, built on diverse frameworks by different companies running on separate servers, to communicate and collaborate effectively - as agents, not just as tools. A2A aims to provide a common language for agents, fostering a more interconnected, powerful, and innovative AI ecosystem.

With A2A, agents can:

Discover each other's capabilities.
Negotiate interaction modalities (text, forms, media).
Securely collaborate on long-running tasks.
Operate without exposing their internal state, memory, or tools.

DeepLearning.AI Course

Join this short course on A2A: The Agent2Agent Protocol, built in partnership with Google Cloud and IBM Research, and taught by Holt Skinner, Ivan Nardini, and Sandi Besen.

What you'll learn:

Make agents A2A-compliant: Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
Connect agents: Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
Orchestrate workflows: Build sequential and hierarchical workflows of A2A-compliant agents.
Multi-agent systems: Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
A2A and MCP: Learn how A2A complements MCP by enabling agents to collaborate with each other.

Why A2A?

As AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to:

Break Down Silos: Connect agents across different ecosystems.
Enable Complex Collaboration: Allow specialized agents to work together on tasks that a single agent cannot handle alone.
Promote Open Standards: Foster a community-driven approach to agent communication, encouraging innovation and broad adoption.
Preserve Opacity: Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property.

Key Features

Standardized Communication: JSON-RPC 2.0 over HTTP(S).
Agent Discovery: Via "Agent Cards" detailing capabilities and connection info.
Flexible Interaction: Supports synchronous request/response, streaming (SSE), and asynchronous push notifications.
Rich Data Exchange: Handles text, files, and structured JSON data.
Enterprise-Ready: Designed with security, authentication, and observability in mind.

Getting Started

📚 Explore the Documentation: Visit the Agent2Agent Protocol Documentation Site for a complete overview, the full protocol specification, tutorials, and guides.
📝 View the Specification: A2A Protocol Specification
Use the SDKs:
- 🐍 A2A Python SDK pip install a2a-sdk
- 🐿️ A2A Go SDK go get github.com/a2aproject/a2a-go
- 🧑‍💻 A2A JS SDK npm install @a2a-js/sdk
- ☕️ A2A Java SDK using maven
- 🔷 A2A .NET SDK using NuGet dotnet add package A2A
- 🦀 A2A Rust SDK cargo add a2a-lf
🎬 Use our samples to see A2A in action

Contributing

We welcome community contributions to enhance and evolve the A2A protocol!

Questions & Discussions: Join our GitHub Discussions.
Issues & Feedback: Report issues or suggest improvements via GitHub Issues.
Contribution Guide: See our CONTRIBUTING.md for details on how to contribute.
Private Feedback: Use this Google Form.
Partner Program: Google Cloud customers can join our partner program via this form.

What's next

Protocol Enhancements

Agent Discovery:
- Formalize inclusion of authorization schemes and optional credentials directly within the AgentCard.
Agent Collaboration:
- Investigate a QuerySkill() method for dynamically checking unsupported or unanticipated skills.
Task Lifecycle & UX:
- Support for dynamic UX negotiation within a task (e.g., agent adding audio/video mid-conversation).
Client Methods & Transport:
- Explore extending support to client-initiated methods (beyond task management).
- Improvements to streaming reliability and push notification mechanisms.

About

The A2A Protocol is an open source project under the Linux Foundation, contributed by Google. It is licensed under the Apache License 2.0 and is open to contributions from the community.

SimoneAvogadro/android-reverse-engineering-skill

Claude Code skill to support Android app's reverse engineering

Android Reverse Engineering & API Extraction — Claude Code skill

A Claude Code skill that decompiles Android APK/XAPK/JAR/AAR files and extracts the HTTP APIs used by the app — Retrofit endpoints, OkHttp calls, hardcoded URLs, authentication patterns — so you can document and reproduce them without the original source code.

First-class Kotlin support: modern Android apps are Kotlin/KMP, heavily obfuscated with R8. This skill recovers the original Kotlin class names from metadata R8 cannot strip, and extracts APIs from Ktor, Apollo (GraphQL) and Koin — not just the classic Retrofit/OkHttp stack. See Kotlin name recovery below.

Windows / PowerShell support (experimental): The *.ps1 scripts alongside the bash ones are a recent community contribution, still being stabilised. For any issues please open an issue on this repository (not on the contributors' upstream forks): the PowerShell scripts are maintained here by @SimoneAvogadro.

What it does

Capability	Description
Fingerprint first (Phase 0)	Triage an APK/XAPK in seconds — detect the framework (Flutter / React Native / Cordova / Xamarin / native-Kotlin), HTTP stack, obfuscation level and native libs before spending time on a full decompile
Decompile	APK, XAPK, JAR, and AAR files using jadx and Fernflower/Vineflower (single engine or side-by-side comparison)
Recover Kotlin names	Rebuild original `Repository` / `ViewModel` / `*UseCase` class names from R8-obfuscated binaries using Kotlin metadata that R8 cannot strip
Extract APIs	Retrofit, OkHttp, Volley and modern Kotlin/KMP stacks: Ktor, Apollo (GraphQL), Koin DI — endpoints, hardcoded URLs, auth headers, tokens and HMAC request-signing schemes
Trace call flows	From Activities/Fragments through ViewModels and repositories down to HTTP calls
Analyze structure	Manifest, packages, architecture patterns
Handle obfuscation	R8-resistant path/URL extraction plus strategies for navigating ProGuard/R8 output

Requirements

Required:

Java JDK 17+
jadx (CLI)

Optional (recommended):

Vineflower or Fernflower — better output on complex Java code
dex2jar — needed to use Fernflower on APK/DEX files

See plugins/android-reverse-engineering/skills/android-reverse-engineering/references/setup-guide.md for detailed installation instructions.

Installation

From GitHub (recommended)

Inside Claude Code, run:

/plugin marketplace add SimoneAvogadro/android-reverse-engineering-skill
/plugin install android-reverse-engineering@android-reverse-engineering-skill

The skill will be permanently available in all future sessions.

From a local clone

git clone https://github.com/SimoneAvogadro/android-reverse-engineering-skill.git

Then in Claude Code:

/plugin marketplace add /path/to/android-reverse-engineering-skill
/plugin install android-reverse-engineering@android-reverse-engineering-skill

Usage

Slash command

/decompile path/to/app.apk

This runs the full workflow: dependency check, decompilation, and initial structure analysis.

Natural language

The skill activates on phrases like:

"Decompile this APK"
"Reverse engineer this Android app"
"Extract API endpoints from this app"
"Follow the call flow from LoginActivity"
"Analyze this AAR library"

Manual scripts

The scripts can also be used standalone:

# Check dependencies
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/check-deps.sh

# Install a missing dependency (auto-detects OS and package manager)
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/install-dep.sh jadx
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/install-dep.sh vineflower

# Fingerprint an APK/XAPK BEFORE decompiling (Phase 0 triage):
# framework, HTTP stack, obfuscation level, native libs, notable SDKs
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/fingerprint.sh app.apk

# Decompile APK with jadx (default)
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/decompile.sh app.apk

# Decompile XAPK (auto-extracts and decompiles each APK inside)
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/decompile.sh app-bundle.xapk

# Decompile with Fernflower
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/decompile.sh --engine fernflower library.jar

# Run both engines and compare
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/decompile.sh --engine both --deobf app.apk

# Find API calls — defaults to a full scan across every supported stack
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/ --retrofit
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/ --urls

# Modern Kotlin/KMP stacks and obfuscation-resistant extraction
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/ --ktor    # Ktor client
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/ --apollo  # Apollo / GraphQL
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/find-api-calls.sh output/sources/ --paths   # quoted path literals that survive R8 inlining

Kotlin name recovery (R8 deobfuscation)

Most real-world Kotlin/KMP apps ship through R8, so the decompiled classes come out as a.b.c. R8 renames the JVM symbols but cannot strip the Kotlin metadata strings — the Kotlin runtime (reflection, coroutines) needs the original fully-qualified names at runtime. This skill mines those @DebugMetadata / @Metadata annotations to rebuild an obfuscated → real class-name map. On a typical app it recovers ~100 % of the *Repository / *ViewModel / *UseCase / *Impl classes you actually want to read.

# 1. Build the mapping from the decompiled sources
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/recover-kotlin-names.sh output/sources/ output/names/
#    → output/names/mapping.tsv, mapping.json, by_package/

# 2. Query it: resolve an obfuscated name, search by real name, or grep
#    the sources with each hit annotated with its recovered class name
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ LoginRepository
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ -o a.b.c
bash plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/lookup-name.sh output/names/ --grep 'login' output/sources/

Repository Structure

android-reverse-engineering-skill/
├── .claude-plugin/
│   └── marketplace.json                    # Marketplace catalog
├── plugins/
│   └── android-reverse-engineering/
│       ├── .claude-plugin/
│       │   └── plugin.json                 # Plugin manifest
│       ├── skills/
│       │   └── android-reverse-engineering/
│       │       ├── SKILL.md                # Core workflow (Phase 0–5)
│       │       ├── references/
│       │       │   ├── setup-guide.md
│       │       │   ├── jadx-usage.md
│       │       │   ├── fernflower-usage.md
│       │       │   ├── api-extraction-patterns.md
│       │       │   ├── kotlin-name-recovery.md
│       │       │   ├── third_party_hosts.txt   # denylist for first/third-party bucketing
│       │       │   └── call-flow-analysis.md
│       │       └── scripts/
│       │           ├── check-deps.sh       # Bash
│       │           ├── check-deps.ps1      # PowerShell
│       │           ├── install-dep.sh
│       │           ├── install-dep.ps1
│       │           ├── decompile.sh
│       │           ├── decompile.ps1
│       │           ├── fingerprint.sh          # Phase 0 — pre-decompile triage
│       │           ├── recover-kotlin-names.sh # R8 → real Kotlin class names
│       │           ├── lookup-name.sh          # query the recovered name map
│       │           ├── find-api-calls.sh
│       │           └── find-api-calls.ps1
│       └── commands/
│           └── decompile.md                # /decompile slash command
├── LICENSE
└── README.md

References

Acknowledgments

Thanks to the contributors who have shaped this skill:

@tajchert — Phase 0 fingerprinting, R8-resistant Kotlin name recovery (recover-kotlin-names.sh, lookup-name.sh), and Ktor / Apollo / Koin / HMAC extraction patterns (#16)
@philjn — Native Windows / PowerShell support (check-deps.ps1, install-dep.ps1, decompile.ps1, find-api-calls.ps1) and split/bundled APK detection in decompile.sh (#8)
@txhno — Migration to the maintained ThexXTURBOXx/dex2jar fork (#12)
@muqiao215 — Decompile partial-success handling, Fernflower timeout safeguard, intermediate-artifact directory (#10)
@kevinaimonster — Chinese localization (SKILL.md discovery keywords) (#4)

Disclaimer

This plugin is provided strictly for lawful purposes, including but not limited to:

Security research and authorized penetration testing
Interoperability analysis permitted under applicable law (e.g., EU Directive 2009/24/EC, US DMCA §1201(f))
Malware analysis and incident response
Educational use and CTF competitions

You are solely responsible for ensuring that your use of this tool complies with all applicable laws, regulations, and terms of service. Unauthorized reverse engineering of software you do not own or do not have permission to analyze may violate intellectual property laws and computer fraud statutes in your jurisdiction.

The authors disclaim any liability for misuse of this tool.

License

Apache 2.0 — see LICENSE

obra/superpowers

An agentic skills framework & software development methodology that works.

Superpowers

Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.

How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

Next up, once you say "go", it launches a subagent-driven-development process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan you put together.

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.

Commercial Services

If you're using Superpowers in enterprise and could benefit from commercial support, additional tooling, or managed spending, please don't hesitate to drop us a line at sales@primeradiant.com.

Installation

Installation differs by harness. If you use more than one, install Superpowers separately for each one.

Claude Code

Superpowers is available via the official Claude plugin marketplace

Official Marketplace

Install the plugin from Anthropic's official marketplace:
```
/plugin install superpowers@claude-plugins-official
```

Superpowers Marketplace

The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code.

/plugin marketplace add obra/superpowers-marketplace

Install the plugin from this marketplace:

/plugin install superpowers@superpowers-marketplace

Antigravity

Install Superpowers as a plugin from this repository:

agy plugin install https://github.com/obra/superpowers

Antigravity runs the plugin's session-start hook, so Superpowers is active from the first message. Reinstall with the same command to update.

Codex App

Superpowers is available via the official Codex plugin marketplace.

In the Codex app, click on Plugins in the sidebar.
You should see Superpowers in the Coding section.
Click the + next to Superpowers and follow the prompts.

Codex CLI

Superpowers is available via the official Codex plugin marketplace.

Open the plugin search interface:
```
/plugins
```
Search for Superpowers:
```
superpowers
```
Select Install Plugin.

Cursor

In Cursor Agent chat, install from marketplace:
```
/add-plugin superpowers
```
Or search for "superpowers" in the plugin marketplace.

Devin CLI

Install the plugin from this repository:
```
devin plugins install obra/superpowers
```
Update to the latest version with:
```
devin plugins update superpowers
```

Factory Droid

droid plugin marketplace add https://github.com/obra/superpowers

Install the plugin:

droid plugin install superpowers@superpowers

Gemini CLI

Install the extension:

gemini extensions install https://github.com/obra/superpowers

Update later:
```
gemini extensions update superpowers
```

GitHub Copilot CLI

copilot plugin marketplace add obra/superpowers-marketplace

Install the plugin:

copilot plugin install superpowers@superpowers-marketplace

Grok Build CLI

Superpowers is available via the official Grok plugin marketplace.

Install the plugin from xAI's official marketplace:

grok plugin install superpowers@xai-official --trust

Or open the marketplace in the TUI, search for Superpowers, and install it:
```
/marketplace
```

Kimi Code

Superpowers is available in Kimi Code's plugin marketplace.

Open Kimi Code's plugin manager:
```
/plugins
```
Go to Marketplace > Superpowers and install it.

Or install directly from this repository:

/plugins install https://github.com/obra/superpowers

Detailed docs: docs/README.kimi.md

OpenCode

OpenCode uses its own plugin install; install Superpowers separately even if you already use it in another harness.

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Detailed docs: docs/README.opencode.md

Pi

Install Superpowers as a Pi package from this repository:

pi install git:github.com/obra/superpowers

For local development, run Pi with this checkout loaded as a temporary package:

pi -e /path/to/superpowers

The Pi package loads the Superpowers skills and a small extension that injects the using-superpowers bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility Skill tool is required. Subagent and task-list tools remain optional Pi companion packages.

Hermes Agent

Install Superpowers as a Hermes plugin from this repository:

hermes plugins install obra/superpowers --enable

Restart any active Hermes sessions after installing. Note: Hermes has no post-compaction hook, so a very long session that compacts over its first turn loses the bootstrap — start a fresh session if skills stop triggering.

The Basic Workflow

brainstorming - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
using-git-worktrees - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
writing-plans - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
subagent-driven-development or executing-plans - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
test-driven-development - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
requesting-code-review - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
finishing-a-development-branch - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.

Community

Superpowers is built by Jesse Vincent and the rest of the folks at Prime Radiant.

Discord: Join us for community support, questions, and sharing what you're building with Superpowers
Issues: https://github.com/obra/superpowers/issues
Release announcements: Sign up to get notified about new versions

What's Inside

Skills Library

Testing

test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
verification-before-completion - Ensure it's actually fixed

Collaboration

brainstorming - Socratic design refinement
writing-plans - Detailed implementation plans
executing-plans - Batch execution with checkpoints
dispatching-parallel-agents - Concurrent subagent workflows
requesting-code-review - Pre-review checklist
receiving-code-review - Responding to feedback
using-git-worktrees - Parallel development branches
finishing-a-development-branch - Merge/PR decision workflow
subagent-driven-development - Fast iteration with two-stage review (spec compliance, then code quality)

Meta

writing-skills - Create new skills following best practices (includes testing methodology)
using-superpowers - Introduction to the skills system

Philosophy

Test-Driven Development - Write tests first, always
Systematic over ad-hoc - Process over guessing
Complexity reduction - Simplicity as primary goal
Evidence over claims - Verify before declaring success

Read the original release announcement.

Contributing

The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support.

Fork the repository
Switch to the 'dev' branch
Create a branch for your work
Follow the writing-skills skill for creating and testing new and modified skills
Submit a PR, being sure to fill in the pull request template.

Skill-behavior tests use the drill eval harness from superpowers-evals, cloned into evals/ — see evals/README.md for setup. Plugin-infrastructure tests live at tests/ and run via the relevant run-*.sh or npm test.

See skills/writing-skills/SKILL.md for the complete guide.

Updating

Superpowers updates are somewhat coding-agent dependent, but are often automatic.

License

MIT License - see LICENSE file for details

Visual companion telemetry

Because skills and plugins don't provide any feedback to creators, we have no idea how many of you are using Superpowers. By default, the Prime Radiant logo on brainstorming's optional visual companion feature is loaded from our website. It includes the version of Superpowers in use. It does not include any details about your project, prompt, or coding agent. We don't see your clicks or anything about what you're building. This helps us have a rough idea of how many folks are using Superpowers and which version of Superpowers they're using. It's 100% optional. To disable this, set the environment variable SUPERPOWERS_DISABLE_TELEMETRY to any true value. Superpowers also honors Claude Code's DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC opt-outs.

expo/skills

A collection of AI agent skills for working with Expo projects and Expo Application Services

Expo Skills

Official AI agent skills from the Expo team for building, deploying, upgrading, and debugging Expo apps.

How It Works

Skills give AI agents focused Expo knowledge: when to use Expo APIs, how to structure common workflows, and which Expo, EAS, React Native, iOS, and Android constraints matter. Expo documentation, Expo CLI, and EAS CLI remain the source of truth; these skills help agents apply them correctly.

Installation

For Claude Code or Codex, install the plugin so updates are handled by the official plugin marketplace. For Cursor, OpenCode, and other AI coding agents, use the skills CLI.

Path	Best for
Plugin install	Claude Code or Codex, with updates handled by their official plugin marketplaces.
Skills CLI	Cursor, OpenCode, GitHub Copilot, Windsurf, Gemini, Cline, AMP, Factory Droid, Antigravity, Kiro CLI, and other AI coding agents.

Skills CLI

Install all Expo skills with the skills CLI:

npx skills@latest add expo/skills --skill '*'

This selects every Expo skill without selecting every agent. The CLI will still ask where to install them; to target one agent directly, add --agent <agent>.

For most agents, this is the only install command you need. Run it from the project root, then restart or refresh your agent session so it can discover the installed SKILL.md files.

Claude Code Plugin

Install from the official Claude Code plugin marketplace:

claude plugin install expo@claude-plugins-official

You can also run /plugin install expo@claude-plugins-official inside Claude Code.

Codex Plugin

Install from the OpenAI-curated Codex marketplace:

codex plugin add expo@openai-curated

You can also open /plugins in Codex and install expo from the OpenAI-curated marketplace.

Updating

Claude Code and Codex plugin installs are updated through their official plugin marketplaces.

For skills CLI installs, update installed skills with:

npx skills@latest update

To update a single Expo skill, pass its name:

npx skills@latest update expo-router

Try It

After installing, ask your agent Expo-specific questions like:

"Build a native-feeling Expo Router screen with tabs, modals, and animations."
"Set up Tailwind CSS v4 and NativeWind v5 in this Expo app."
"Create an EAS workflow that builds previews on pull requests."
"Help me upgrade this app to the latest Expo SDK."
"Check whether this EAS Update rollout is healthy."

Agents choose the right skill from the task context and each skill's description.

Skills Included

Skills come in two groups so the free vs paid boundary is clear. Each skill's description carries the same label, and every services skill opens with a costs/plan-limits note.

Framework (open source)

Free, open-source Expo SDK and React Native skills.

Skill	Use it for
`expo-project-structure`	Folder structure for a new Expo app: `src/` layout, routes-only `app/`, screens, server code, platform-specific files.
`expo-router`	Expo Router navigation: file-based routes, links, native stacks, modals, sheets, native tabs, and headers.
`expo-native-ui`	Native-feeling screen styling, semantic colors, controls, icons, media, animations, and visual effects.
`expo-ui`	`@expo/ui` native components: universal cross-platform first, with SwiftUI and Jetpack Compose for platform-specific needs.
`expo-data-fetching`	API calls, React Query, SWR, caching, offline support, and Expo Router data loaders.
`expo-tailwind-setup`	Tailwind CSS v4, `react-native-css`, and NativeWind v5 setup.
`expo-dom`	Expo DOM components for gradually using web code in native apps.
`expo-web-to-native`	Migrating an existing web/React app (Next.js, Vite, CRA) to a native iOS/Android app with Expo.
`expo-module`	Expo native modules and views with Swift, Kotlin, TypeScript, config plugins, and autolinking.
`expo-brownfield`	Adding Expo or React Native to an existing iOS or Android app.
`expo-dev-client`	Development clients (local builds are free; EAS Build/TestFlight is a paid step).
`expo-examples`	The `expo/examples` repo of `with-*` integrations to adapt or scaffold a new project from.
`expo-app-clip`	iOS App Clip targets, AASA files, associated domains, and Smart App Banners.
`expo-upgrade`	Expo SDK upgrades, dependency conflicts, deprecated packages, and cache cleanup.
`expo-skill-feedback`	Share what worked or fell short across Expo, its skills, docs, CLIs, or MCP, and control opt-in usage telemetry.

Services & paid distribution

Skills whose core purpose uses paid Expo Application Services (EAS).

Skill	Use it for
`eas-app-stores`	Production builds, App Store, Play Store, TestFlight, eas.json profiles, versioning, and store metadata.
`eas-hosting`	Deploying Expo websites and Expo Router API routes to EAS Hosting: secrets, custom domains, Cloudflare Workers.
`eas-workflows`	EAS Workflow YAML files and CI/CD automation.
`eas-observe`	EAS Observe setup and launch, route, event, and version metrics.
`eas-update-insights`	EAS Update health, crash rates, launch counts, payload size, and rollout gates.
`eas-simulator`	Run and drive your app on a remote iOS simulator or Android emulator on EAS cloud - from the CLI or an agent, with a live browser preview (iOS only).

Experimental

Skills for Expo APIs that are not finalized. Content may change or be retired; skills graduate to the groups above when the underlying API stabilizes. These ship in the separate expo-experiments plugin (install it alongside expo), or individually via the skills CLI.

Skill	Use it for
`expo-migrate-module`	Migrating a Swift Expo module from the Modules API 1.0 definition DSL to the 2.0 macro API.

Expo MCP Server

Skills teach an agent how Expo work gets done. The Expo MCP server gives it live access to actually do that work: read the latest Expo docs on demand, install compatible dependencies with npx expo install, trigger and monitor EAS builds and workflows, pull crash data from TestFlight, and screenshot a running app in the simulator.

The expo plugin bundles this MCP configuration, so Claude Code and Codex plugin installs wire it up automatically. For other agents, or to add it on its own, follow the Expo MCP setup guide.

FAQ

Which AI coding agents are supported?

Use npx skills@latest add expo/skills --skill '*' for Cursor, OpenCode, GitHub Copilot, Windsurf, Gemini, Cline, AMP, Factory Droid, Antigravity, Kiro CLI, and similar AI coding tools.

Should I install the skills or the plugin?

Use the plugin for Claude Code or Codex; it stays updated through the plugin marketplace. Use npx skills@latest add expo/skills --skill '*' for Cursor, OpenCode, and other AI coding agents.

What is the source of truth?

Expo documentation, Expo CLI, and EAS CLI are the source of truth. These skills teach agents how to apply Expo guidance in real projects.

Usage telemetry & feedback

Automatic usage telemetry is off by default. When enabled (Claude Code only), it sends anonymous usage events: the skill name, platform, and a hash of a random local install id. Never code, prompts, file paths, or personal data.

Turn on: ask your agent to "enable Expo skills telemetry", or set EXPO_SKILLS_TELEMETRY=1.
Turn off: ask it to disable telemetry, or set EXPO_SKILLS_TELEMETRY=0 / DO_NOT_TRACK=1. CI never sends.
Feedback: every skill includes instructions to submit specific, actionable feedback with submit-expo-feedback; this is independent of automatic usage telemetry.

Submission details and telemetry controls live in expo-skill-feedback.

License

MIT

basecamp/omarchy

Beautiful, Modern & Opinionated Linux

Omarchy

Omarchy is a beautiful, modern & opinionated Linux distribution by DHH.

License

Omarchy is released under the MIT License.

kunchenguid/firstmate

Talk to one agent. Ship with a crew.

firstmate

Talk to one agent. Ship with a crew.

What it is

You can run one coding agent easily. But the moment you want three project tasks done in parallel - fixes, investigations, plans, audits - you become a tab-juggler: babysitting sessions, copy-pasting context between repos, forgetting which terminal had the failing test.

firstmate flips the model. You talk to a single agent - the first mate - and it runs the crew for you: spawning autonomous agents in a visible session backend, giving each a clean git worktree, supervising them to completion, and handing you finished PRs, approved local merges, or standalone investigation reports. For larger fleets, you can opt in to persistent secondmates: second mates that are still ordinary direct reports, but run from their own isolated firstmate homes on this machine or another SSH-reachable host.

firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI. firstmate is an agent distro for running a crew of agents. An agent distro is a portable directory of instructions, skills, tooling, policies, and state conventions that turns a general-purpose agent into a specialized one. There is no app to install: the cloned repo is the distro - AGENTS.md, bundled firstmate skills, and helper scripts that any terminal coding agent can follow. Launching a supported harness inside it instantiates your first mate - and makes you the captain.

Features

One liaison - you talk only to the first mate; it dispatches, supervises, escalates only real decisions, and reports plain outcomes.
A visible crew - every crewmate works in its own tmux window, experimental herdr/zellij tab, cmux workspace, or Orca terminal you can watch or type into; the first mate reconciles.
Disposable worktrees - each task runs in a clean treehouse git worktree, or an Orca-managed worktree when backend=orca, so parallel work on one repo never collides.
Two task shapes - ship tasks deliver authorized changes; scout tasks leave standalone investigation reports when the intake contract warrants separate research.
Explicit project modes - each project ships via no-mistakes, direct-PR, or local-only, with an optional +yolo autonomy flag.
Optional secondmates - opt in to persistent second mates that run from isolated firstmate homes with their own FM_HOME, state, projects, and session lock, either locally or as a whole home on an SSH-reachable host, with guarded updates and recovery that never turns an unavailable remote route into a local replacement.
Event-driven, zero-token supervision - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you; verified primary harnesses also get a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live.
Optional Relay - opt in with one local .env pairing token so firstmate can answer your public mentions on X and Discord alike, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days for genuine milestones and the final outcome without changing non-Relay behavior; a final reply promised in a thread becomes durable state that is reconciled from disk, so a restart or a compacted conversation cannot lose it; dry-run preview records would-be replies and dismissals locally before go-live.
Strict project boundary - the first mate is read-only over your projects except for the narrow guarded and captain-approved operations authorized by hard rule 1, including fleet sync's guarded safe branch pruning; crewmates make every other project change behind the configured merge authority.
Restart-proof - all state lives on disk and in the active session backend (tmux by hard default, herdr or cmux when selected or auto-detected, zellij/orca when explicitly selected); kill the session anytime and the next one reconciles, including confirmed-dead secondmate agents, and carries on.

Full detail on every feature lives in docs/architecture.md.

Quick Start

Requirements

A verified primary agent harness: Claude Code, Grok, Pi, pi-signed, Codex, or OpenCode.
Git and the GitHub CLI, authenticated through gh auth login.
The CLI and dependencies for your selected runtime backend; tmux is the reference default.

The first mate detects and offers to install supported missing tools after you approve. Backend-specific setup is linked in Documentation.

Recommended harnesses

Claude Code, Grok, and Pi are equal co-primary recommendations for running the primary firstmate session, with pi-signed supported as Pi's distinct signed-wrapper identity. Claude Code uses a tracked Stop hook for tokenless watcher re-arm and rewake, Grok uses background-notify wake cycles, and Pi uses its tracked primary watcher extension. All three have verified turn-end guard paths when launched with their documented setup. Pick whichever one matches your subscription and workflow.

Codex and OpenCode are also verified and supported as primary harnesses; Codex uses bounded foreground checkpoints, and OpenCode uses a TUI plugin, so both carry more harness-specific supervision tradeoffs than the three co-primaries.

Install and launch

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

Then launch one of the co-primary harnesses; AGENTS.md takes over from there:

Claude Code

claude

Grok

grok --trust

pi
# or, when the signed wrapper is installed
FM_PI_HARNESS=pi-signed pi-signed

For Grok, --trust is needed once per clone so project hooks and the turn-end guard load; /hooks-trust inside Grok works too. For Pi, approve the project trust prompt once per clone on first launch so the tracked .pi/extensions/*.ts files auto-load. Pi's /calm toggle hides supported transcript chrome, including canonically classified Firstmate operational user rows, and uses a Calm-only animated working boat during active runs while preserving all model context and session data. The hidden operational inputs remain ordinary user-role messages with unchanged delivery, ordering, authority, persistence, and exports. The preference persists for the effective Firstmate home, and toggling it off restores ordinary rendering. Calm's current behavior and supported limits are separate from its version-scoped maintainer evidence.

Talk to it

> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode

# firstmate checks its toolchain (asking your consent before installing anything),
# clones the project under projects/ and spawns two isolated workers in the active backend.
# Minutes later:

  PR ready for review, captain: https://github.com/you/xyz/pull/42
  (fix flaky login test - risk: low - CI green)

> alright merge it

More backends

Setup guides for tmux (the default) and every other supported backend (herdr, zellij, Orca, cmux) are linked in Documentation below.

How It Works

            you (the captain)
                  │  chat: requests, decisions, "merge it"
                  ▼
 ┌─────────────────────────────────────┐
 │ firstmate            (this repo)    │
 │ reads projects/ + firstmate routes  │
 │ writes guarded backlog/briefs/state │
 └──┬──────────────┬───────────────┬───┘
    │ backend sends / status files │
    ▼              ▼               ▼
 ┌────────┐   ┌────────┐      ┌────────┐
 │fm-task1│   │fm-task2│  ... │fm-taskN│   tmux windows, herdr/zellij tabs, cmux workspaces, or Orca terminals
 │crewmate│   │crewmate│      │crewmate│   one autonomous agent each
 └───┬────┘   └───┬────┘      └───┬────┘
     ▼            ▼               ▼
  treehouse worktree, Orca worktree, or isolated secondmate home
     │
     ├─ ship: project mode ► PR/local merge ► teardown
     │
     └─ scout: report at data/<id>/report.md ► decision inventory ► relay findings ► teardown

You chat with the first mate. It routes each request to a crewmate in its own session endpoint and git worktree, supervises the fleet with a zero-token event-driven watcher, and brings you finished PRs, approved local merges, or investigation reports. Optional secondmates extend this to persistent local or whole-home remote second mates, dispatch profiles let you steer which harness handles which task, and opt-in Relay lets the same fleet answer public mentions. codex-app is not a runtime backend yet; docs/codex-app-backend.md owns the Codex App boundary.

Full architecture - the supervision engine, worktree isolation, secondmates, dispatch profiles, project modes, optional Relay, fleet sync, and self-update - is in docs/architecture.md.

Built-in skills

Firstmate ships these user-invocable built-in skills. Claude and grok use the slash form shown here; codex uses the same names with $, such as $afk.

Skill	What it does
`/afk`	Enter away-mode supervision: the sub-supervisor self-handles routine notifications in bash, escalates captain-relevant events and bounded declared-external-wait rechecks as batched digests, and actively alerts if delivery gets stuck while you step away
`/ahoy`	Recap visible session events since the prior real captain message plus visibly unanswered captain decisions, then guide the captain through any open decisions one at a time in agent-judged impact order; fall back to Bearings when invoked as the session's first real captain message
`/bearings`	Generate a concise four-section chat digest from bounded local fleet and registered-secondmate state; use `/bearings file` to also replace today's dated report in `data/`, and add `include PRs` when live PR enrichment is wanted
`/updatefirstmate`	Self-update the running firstmate and its secondmates to the latest from origin with fast-forward-only pulls, then re-read instructions and nudge secondmates
`/stow`	Sweep the session for uncaptured durable knowledge, curate tiered startup memory with decay and cold archival, enforce each home's budget or surface the required decision, cascade to registered second mates, and report what is safe to reset

Bearings invocation examples:

/bearings returns the fresh four-section digest in chat only.
/bearings include PRs keeps chat-only mode and opts into live PR enrichment.
/bearings file replaces today's data/status-report-<YYYY-MM-DD>.md from scratch and links it from the four-section chat digest.
/bearings file include PRs combines the dated report with live PR enrichment.

Agent-only reference skills live under .agents/skills/ and are loaded by firstmate at the trigger points named in AGENTS.md.

Two-tier skill layout

Firstmate's skills live in two separate places with different audiences:

.agents/skills/ - agent-loaded skills (this section's table, plus firstmate's agent-only reference skills). Every one of these assumes a live firstmate home and is meaningless, or actively misleading, installed anywhere else, so each carries metadata.internal: true in its frontmatter. That flag hides them from installer discovery (tools like the skills.sh npx skills add installer) without affecting how firstmate itself loads them - frontmatter metadata is inert to the agent's own skill loader.
skills/ - public, installer-facing skills meant to be installed standalone into any project, independent of firstmate. Each one is a self-contained skill with no dependency on firstmate's paths, tools, or vocabulary. Today that is skills/stow, a generic session-knowledge-sweep skill that routes findings by explicit instruction first, then existing local conventions, then a private .stow-notes.md fallback, and curates tiered entries through decay, local archival, and user-approved on-demand offload proposals. It intentionally shares no code with the firstmate-internal .agents/skills/stow it is named after, so the two can evolve independently.

Documentation

docs/architecture.md - maintainer architecture for the crew, supervision, worktrees, secondmates, and project modes.
docs/configuration.md - environment variables, FM_HOME, runtime backend selection, optional Relay and its X and Discord setup steps, the files you set, and harness support.
docs/remote-secondmates.md - current setup, routing, transfer, recovery, and safety behavior for whole-home remote second mates.
docs/calm.md - current Pi /calm behavior and supported presentation limits.
docs/wedge-alarm.md - configure the active alert for an away-mode escalation delivery that gets stuck.
docs/tmux-backend.md - current setup and limits for the tmux reference backend.
docs/herdr-backend.md - current setup, safety boundaries, and limits for the experimental Herdr backend.
docs/zellij-backend.md - current setup and limits for the experimental Zellij backend.
docs/orca-backend.md - current setup and limits for the experimental Orca backend.
docs/cmux-backend.md - current setup, socket security, and limits for the experimental cmux backend.
docs/codex-app-backend.md - the current blocked Codex App backend boundary and rollout contract.
docs/verification/runtime-backends.md - active maintainer verification for runtime backend guarantees.
docs/gitlab-merge-watch.md - maintainer verification for GitLab merge watching on arbitrary instances.
docs/turnend-guard.md - the primary session's current "no turn ends blind" backstop, scope, loop safety, and compatibility limits.
docs/verification/supervision.md - active maintainer verification for session-start, guard, continuity, and wedge integrations.
docs/supervision-protocols/ - rendered primary-harness watcher protocols for Claude, Codex, OpenCode, Pi and pi-signed, Grok, and unknown harness fallback.
docs/scripts.md - the bin/ toolbelt reference.
docs/documentation-audiences.md - documentation audiences and the machine-checked placement boundary.
AGENTS.md - the distro's always-loaded operating contract and routing index for conditional procedures.
CONTRIBUTING.md - how to contribute, including the dev/test commands.

Contributing

Contributions are welcome - see CONTRIBUTING.md for the workflow, repo conventions, and how to run the tests.

License

MIT - see LICENSE.

czlonkowski/n8n-skills

n8n skillset for Claude Code to build flawless n8n workflows

n8n-skills

Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server

Watch the Introduction Video

🎯 What is this?

This repository contains 14 complementary Claude Code skills — plus an always-on router skill and a hooks enforcement layer — that teach AI assistants how to build production-ready n8n workflows using the n8n-mcp MCP server, and how to deploy the self-hosted n8n that runs them.

Why These Skills Exist

Building n8n workflows programmatically can be challenging. Common issues include:

Using MCP tools incorrectly or inefficiently
Getting stuck in validation error loops
Not knowing which workflow patterns to use
Misconfiguring nodes and their dependencies

These skills solve these problems by teaching Claude:

✅ Correct n8n expression syntax ({{}} patterns)
✅ How to use n8n-mcp tools effectively
✅ Proven workflow patterns from real-world usage
✅ Validation error interpretation and fixing
✅ Operation-aware node configuration

📚 The 14 Skills

1. n8n Expression Syntax

Teaches correct n8n expression syntax and common patterns.

Activates when: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors.

Key Features:

Core variables ($json, $node, $now, $env)
Critical gotcha: Webhook data is under $json.body
Common mistakes catalog with fixes
When NOT to use expressions (Code nodes!)

2. n8n MCP Tools Expert (HIGHEST PRIORITY)

Expert guide for using n8n-mcp MCP tools effectively.

Activates when: Searching for nodes, validating configurations, accessing templates, managing workflows.

Key Features:

Tool selection guide (which tool for which task)
nodeType format differences (nodes-base.* vs n8n-nodes-base.*)
Validation profiles (minimal/runtime/ai-friendly/strict)
Smart parameters (branch="true" for IF nodes)
Auto-sanitization system explained

Most Important: Teaches correct MCP tool usage patterns and parameter formats

3. n8n Workflow Patterns

Build workflows using 5 proven architectural patterns.

Activates when: Creating workflows, connecting nodes, designing automation.

Key Features:

5 proven patterns (webhook processing, HTTP API, database, AI, scheduled)
Workflow creation checklist
Real examples from 2,653+ n8n templates
Connection best practices
Pattern selection guide

4. n8n Validation Expert

Interpret validation errors and guide fixing.

Activates when: Validation fails, debugging workflow errors, handling false positives.

Key Features:

Validation loop workflow
Real error catalog
Auto-sanitization behavior explained
False positives guide
Profile selection for different stages

5. n8n Node Configuration

Operation-aware node configuration guidance.

Activates when: Configuring nodes, understanding property dependencies, setting up AI workflows.

Key Features:

Property dependency rules (e.g., sendBody → contentType)
Operation-specific requirements
AI connection types (8 types for AI Agent workflows)
Common configuration patterns

6. n8n Code JavaScript

Write effective JavaScript code in n8n Code nodes.

Activates when: Writing JavaScript in Code nodes, troubleshooting Code node errors, making HTTP requests with this.helpers (the $helpers global), working with dates.

Key Features:

Data access patterns ($input.all(), $input.first(), $input.item)
Critical gotcha: Webhook data under $json.body
Correct return format: [{json: {...}}]
Built-in functions (this.helpers.httpRequest() — the bare $helpers global is undefined in the task-runner sandbox; prefer the HTTP Request node for non-trivial/authenticated calls — DateTime, $jmespath())
Top 5 error patterns with solutions (covering 62%+ of failures)
10 production-tested patterns

7. n8n Code Python

Write Python code in n8n Code nodes with proper limitations awareness.

Activates when: Writing Python in Code nodes, need to know Python limitations, working with standard library.

Key Features:

Important: Use JavaScript for 95% of use cases
Python data access (_input, _json, _node)
Critical limitation: No external libraries (requests, pandas, numpy)
Standard library reference (json, datetime, re, etc.)
Workarounds for missing libraries
Common Python patterns for n8n

8. n8n Code Tool

Write code for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) — a different node from the regular Code node with a different contract.

Activates when: Building a Code Tool attached to an AI Agent, troubleshooting "Wrong output type returned" or "No execution data available" errors, deciding between unstructured query parsing and specifyInputSchema.

Key Features:

Critical distinction: Code Tool ≠ Code node (different node type, different return format, different sandbox)
Return format: a string (use JSON.stringify() for structured output) — NOT [{json:{...}}]
Input binding: query (JS) / _query (Python) — $fromAI() does NOT work here
Unstructured vs structured input modes (specifyInputSchema → DynamicStructuredTool)
Sandbox limits: no $input, $helpers, $json, $getWorkflowStaticData, no state across calls
Three signature error strings with causes and fixes
When to use Code Tool vs toolWorkflow vs HTTP Request Tool

9. n8n Error Handling

Make failures loud, structured, and recoverable.

Activates when: Building webhook/API or unattended workflows, wiring error outputs, setting retries, designing 4xx/5xx responses, or chasing silent failures.

Key Features:

Per-node error output: the two-step onError: continueErrorOutput + wire main[1] trap
retryOnFail self-healing for flaky network calls
4xx/5xx response-shape mapping (and the responseCode-defaults-to-200 gotcha)
Error Trigger workflows for unattended runs

10. n8n Binary & Data

Handle files, images, and binary data correctly.

Activates when: Working with files, images, PDFs, attachments, uploads/downloads, vision input, or passing a file to/from an AI agent tool.

Key Features:

$binary vs $json — file contents never live in $json
Keeping binary alive across JSON transforms with Merge
The agent-tool binary boundary (pre-stage to storage, pass keys/URLs)
CDN/URL requirement for showing images in chat surfaces

11. n8n Sub-workflows

Build reusable, composable sub-workflows.

Activates when: Extracting shared logic, building multi-step or reused workflows, or any workflow over ~10 nodes.

Key Features:

Execute Workflow Trigger with "Define Below" typed inputs (not passthrough)
mode: all vs each and waitForSubWorkflow (the only true parallelization)
Verb-first prefix naming for discovery (MCP can't filter by tags)
Stateless vs stateful design; N+1 split-by-input-shape

12. n8n AI Agents

Design n8n AI agents the right way.

Activates when: Building any @n8n/n8n-nodes-langchain.* node — AI Agent, LLM chain, Text Classifier — or working with tool calling, $fromAI, memory, structured output, RAG, or chat bots.

Key Features:

Agent vs LLM Chain vs Text Classifier; the model/memory/tools/outputParser slots
Tool names & descriptions ARE the prompt; $fromAI parameter anatomy
Structured output with autoFix; memory + sessionId; human-in-the-loop review
Chat shell+core+sub-agent topology with anti-loop filtering

13. n8n Multi-Instance

Target the right n8n instance when an account has more than one.

Activates when: The n8n_instances tool is available, the user mentions multiple instances/environments (prod vs staging, several clients), or a call returns an unexpected NOT_FOUND or wrong/empty data.

Key Features:

n8n_instances list/switch shapes and the real error envelope (UNKNOWN_INSTANCE, MULTI_INSTANCE_DISABLED, …)
Switching in its own turn; the per-session binding that persists across reconnects/deploys
Verifying current before credential writes — the server fail-closes only the ambiguous case (INSTANCE_AMBIGUOUS); an explicit wrong switch still writes the secret silently
Recovering from a misroute (NOT_FOUND ≈ wrong instance, not a deletion) and copying objects between instances

14. n8n Self-Hosting (deployment/ops)

Deploy a production self-hosted n8n end-to-end to a fresh Linux VM.

Activates when: Self-hosting, installing, or deploying n8n on your own server/VPS (Hetzner, DigitalOcean, EC2, bare metal) — single or queue mode — or updating/backing-up/hardening it. Not for n8n Cloud, and not for building workflows.

Key Features:

Docker Compose behind Caddy with automatic HTTPS; asks single vs queue mode first
Single (SQLite) and queue (main + Redis + Postgres + workers) templates, secret-free and domain-free
Generates fresh secrets on the box; secure defaults (explicit encryption key, no published internal ports, telemetry off, env-access blocked, execution pruning)
DNS/ports preflight, end-to-end verify (cert + reachability), and Day-2 (update / backup / restore)

This is the pack's one deployment skill; it triggers on its own description and is not part of the workflow-building router/hooks flow.

🪝 Enforcement Layer (hooks + router)

Beyond the capability skills, the plugin ships an always-on enforcement layer so the right guidance surfaces at the moment of decision — not only when a query happens to match a skill description.

Router skill (using-n8n-mcp-skills) — loaded into every session by a SessionStart hook. It routes you to the right skill, summarizes every n8n-mcp tool, and states the cross-cutting rules. It re-fires on resume/clear/compact so it survives context compaction.
PreToolUse hooks — before high-impact n8n-mcp calls, a short reminder points at the relevant skill. Looking up a Set, Code, Merge, Loop Over Items, DateTime, Data Table, or AI Agent node via get_node fires a node-specific reminder (and re-fires each time, because a re-lookup usually means you're reconsidering the same decision). Calls to n8n_instances and n8n_manage_credentials fire one-shot reminders pointing at the multi-instance and credential-discipline skills.
PostToolUse hook — after validate_workflow, it inspects the workflow's node types and routes you to the skills that own the remaining risks, with the reminder that validation passing is necessary, not sufficient.

Hooks run only in the Claude Code / Codex plugin install. On Claude.ai (individual skill uploads) the skills still activate by description — the pack degrades gracefully, just without the proactive nudges. Every hook fails open and never blocks a tool call.

🚀 Installation

Prerequisites

n8n-mcp MCP server installed and configured (Installation Guide)
Claude Code, Claude.ai, or Claude API access
.mcp.json configured with n8n-mcp server

Claude Code

Method 1: Plugin Installation (Recommended)

# Install directly as a Claude Code plugin
/plugin install czlonkowski/n8n-skills

Method 2: Via Marketplace

# Add as marketplace, then browse and install
/plugin marketplace add czlonkowski/n8n-skills

# Then browse available plugins
/plugin install
# Select "n8n-mcp-skills" from the list

Method 3: Manual Installation

# 1. Clone this repository
git clone https://github.com/czlonkowski/n8n-skills.git

# 2. Copy skills to your Claude Code skills directory
cp -r n8n-skills/skills/* ~/.claude/skills/

# 3. Reload Claude Code
# Skills will activate automatically

Claude.ai

Download individual skill folders from skills/
Zip each skill folder (or grab prebuilt zips from the latest release)
Upload via Settings → Capabilities → Skills

API / SDK

See docs/INSTALLATION.md for detailed instructions.

💡 Usage

Skills activate automatically when relevant queries are detected:

"How do I write n8n expressions?"
→ Activates: n8n Expression Syntax

"Find me a Slack node"
→ Activates: n8n MCP Tools Expert

"Build a webhook workflow"
→ Activates: n8n Workflow Patterns

"Why is validation failing?"
→ Activates: n8n Validation Expert

"How do I configure the HTTP Request node?"
→ Activates: n8n Node Configuration

"How do I access webhook data in a Code node?"
→ Activates: n8n Code JavaScript

"Can I use pandas in Python Code node?"
→ Activates: n8n Code Python

"Why does my Code Tool throw 'Wrong output type returned'?"
→ Activates: n8n Code Tool

Skills Work Together

When you ask: "Build and validate a webhook to Slack workflow"

n8n Workflow Patterns identifies webhook processing pattern
n8n MCP Tools Expert searches for webhook and Slack nodes
n8n Node Configuration guides node setup
n8n Code JavaScript helps process webhook data with proper .body access
n8n Expression Syntax helps with data mapping in other nodes
n8n Validation Expert validates the final workflow

All skills compose seamlessly!

📖 Documentation

Installation Guide - Detailed installation for all platforms
Usage Guide - How to use skills effectively
Development Guide - Contributing and testing
MCP Testing Log - Real tool responses used in skills

🧪 Testing

Each skill includes 3+ evaluations for quality assurance:

# Run evaluations (if testing framework available)
npm test

# Or manually test with Claude
claude-code --skill n8n-expression-syntax "Test webhook data access"

🤝 Contributing

Contributions welcome! Please see DEVELOPMENT.md for guidelines.

Development Approach

Evaluation-First: Write test scenarios before implementation
MCP-Informed: Test tools, document real responses
Iterative: Test against evaluations, iterate until 100% pass
Concise: Keep SKILL.md under 500 lines
Real Examples: All examples from real templates/tools

📝 License

MIT License - see LICENSE file for details.

🙏 Credits

Conceived by Romuald Członkowski

Website: www.aiadvisors.pl/en
Part of the n8n-mcp project

The hooks enforcement layer adapts patterns from the official n8n Skills project (Apache-2.0), retargeted for n8n-mcp and rewritten in our own voice. See NOTICES.

🔗 Related Projects

n8n-mcp - MCP server for n8n
n8n - Workflow automation platform

📊 What's Included

14 complementary skills that work together
525+ n8n nodes supported
2,653+ workflow templates for examples
10 production-tested Code node patterns
Comprehensive error catalogs and troubleshooting guides

Ready to build flawless n8n workflows? Get started now! 🚀

💼 Need it built for you?

Work with AiAdvisors — automation audits, builds, and operations by the team behind n8n-mcp and n8n-skills.

conversun/fnos-apps

飞牛 fnOS NAS 第三方应用商店 — 115 款自托管应用的 .fpk 安装包 | Plex, Emby, Jellyfin, qBittorrent, Immich, Sonarr, Radarr, Vaultwarden, ZeroClaw AI, OpenClaw 等 | 每日自动同步上游版本

fnOS Apps

面向飞牛 fnOS 的第三方应用打包仓库。自动跟踪上游版本，构建可直接安装的 .fpk 包。

⭐️ 如果觉得本项目对你有帮助，请右上角点个 Star！

应用一览

💡 推荐先安装 fnOS Apps 应用中心，可一键管理以下所有应用的安装与更新。

📦 应用中心

	App	端口	说明	来源	下载
	fnOS Apps	`8011`	第三方应用中心，一键安装与更新	GitHub	Release

🤖 AI

App	端口	说明	来源	下载
CoPaw	`8088`	基于 AgentScope 的个人 AI 助手工作站，支持多渠道聊天、本地大模型和定时任务	GitHub	Release
CowAgent	`9899`	AI 超级助手，支持微信/飞书/钉钉/QQ/Web 等多平台接入，基于大语言模型的智能对话	GitHub	Release
ZeroClaw	`42617`	轻量级 AI 智能体运行时，Rust 编写，<5MB 内存占用	GitHub	Release
PicoClaw	`18790`	超轻量 AI 智能体框架，Go 编写，10MB 内存占用	GitHub	Release
Nanobot	`18780`	超轻量 AI 智能体，Web 管理面板，默认账号 `admin/nanobot`	GitHub	Release
LocalAI	`8185`	本地 AI 推理，兼容 OpenAI API	官网	Release
LibreChat	`3085`	AI 聊天界面，支持多模型	官网	Release
Open WebUI	`8080`	AI 聊天界面，支持多模型对话	GitHub	Release
Ollama	`11434`	本地大语言模型运行引擎	官网	Release
MaxKB	`8083`	AI 知识库问答系统，支持 RAG 和多模型对接	GitHub	Release

🎬 媒体服务

App	端口	说明	来源	下载
Plex	`32400`	媒体服务器，支持硬件转码	官网	Release
Emby	`8096`	媒体管理与流式传输	官网	Release
Jellyfin	`8097`	开源媒体系统，内置 FFmpeg	官网	Release
Navidrome	`4533`	音乐流媒体服务器	官网	Release
Koel	`8060`	个人音乐流媒体，默认账号 `admin@koel.dev/KoelIsCool`	GitHub	Release
Immich	`2283`	自托管照片/视频备份，支持人脸识别	GitHub	Release
Kavita	`5000`	漫画/电子书阅读	GitHub	Release
tinyMediaManager	`5800`	影视元数据管理	官网	Release
MetaTube	`8091`	JAV 元数据刮削服务器，搭配 Emby/Jellyfin 使用，内置 20+ 数据源	GitHub	Release
PhotoPrism	`2342`	AI 驱动的照片管理	官网	Release
Jellyseerr	`5055`	Jellyfin/Plex 媒体请求管理	GitHub	Release
Tautulli	`8181`	Plex 使用统计与监控	官网	Release
Seerr	`5055`	Overseerr 社区分支，媒体请求管理	GitHub	Release
Ente	`8510`	端到端加密照片备份	官网	Release
Sunshine	`47990`	游戏串流服务器，配合 Moonlight 使用	GitHub	Release
Frigate	`8971`	AI 视频监控，支持实时物体检测	官网	Release
Komga	`25600`	漫画/电子书媒体服务器，支持 OPDS	GitHub	Release
Koodo Reader	`8930`	现代电子书管理器与阅读器	GitHub	Release
Jellystat	`3004`	Jellyfin 使用统计与分析	GitHub	Release
Ombi	`3579`	媒体请求与用户管理	GitHub	Release
Wizarr	`5690`	Plex/Jellyfin 用户邀请管理	GitHub	Release
Medusa	`8081`	电视剧自动下载管理	GitHub	Release
Bililive-go	`8680`	多平台直播录制工具，支持 Bilibili、斗鱼、虎牙等	GitHub	[Release][r-bililive-go]
HandBrake	`5800`	开源视频转码工具，支持 GPU 硬件加速	GitHub	Release
Suwayomi	`4567`	免费开源漫画阅读服务器，支持多来源扩展	GitHub	Release

⬇️ 下载工具

App	端口	说明	来源	下载
qBittorrent	`8085`	BitTorrent 客户端，默认账号 `admin/adminadmin`	官网	Release
Transmission	`9091`	轻量级 BitTorrent 客户端	官网	Release
Gopeed	`9999`	高速下载器，支持 HTTP/BT/Magnet	官网	Release
Syncthing	`8384`	文件同步工具，P2P 架构	官网	Release
Alist	`5246`	网盘聚合工具，挂载阿里云盘/百度盘等	GitHub	Release
Rclone	`5572`	云存储同步工具，支持 50+ 存储后端	官网	Release
Cloudreve	`5212`	国产云盘系统	官网	Release
SABnzbd	`8780`	Usenet 下载客户端	官网	Release
CopyParty	`3923`	便携文件共享服务器	GitHub	Release

📚 内容管理

App	端口	说明	来源	下载
ANI-RSS	`7789`	动漫 RSS 自动追番，默认账号 `admin/admin`	GitHub	Release
AutoBangumi	`7892`	RSS 自动追番下载整理，默认账号 `admin/adminadmin`	GitHub	Release
Audiobookshelf	`13378`	有声书和播客服务器	官网	Release
MoviePilot	`3000`	影视自动化管理	GitHub	Release
OpenList	`5244`	文件列表/WebDAV	GitHub	Release
KodBox	`8500`	私有云存储/在线文档协作	官网	Release
ChineseSubFinder	`19035`	中文字幕自动下载	GitHub	Release
FreshRSS	`8082`	自托管 RSS 阅读器	官网	Release
Miniflux	`8084`	极简 RSS 阅读器	官网	Release
Linkwarden	`3005`	协作式书签管理	官网	Release
Wiki.js	`3110`	现代化 Wiki 引擎	官网	Release
Mealie	`9925`	食谱管理与膳食计划	官网	Release
Paperless-ngx	`8000`	文档数字化管理，OCR 支持	官网	Release
AppFlowy	`8501`	Notion 开源替代品，协作文档平台	官网	Release
Reactive Resume	`3200`	在线简历制作工具	GitHub	Release
LANraragi	`3000`	自托管漫画/存档管理服务器，自动元数据刮削	GitHub	Release

🎵 媒体自动化

App	端口	说明	来源	下载
Sonarr	`8989`	电视剧自动下载管理	官网	Release
Radarr	`7878`	电影自动下载管理	官网	Release
Lidarr	`8686`	音乐自动下载管理	官网	Release
Readarr	`8787`	电子书自动下载管理	官网	Release
Prowlarr	`9696`	索引器管理，整合 Sonarr/Radarr 等	官网	Release
Bazarr	`6767`	字幕自动下载管理	官网	Release
Jackett	`9117`	Torrent 索引器代理，Prowlarr 替代	GitHub	Release

🔧 系统工具

App	端口	说明	来源	下载
Sun-Panel	`3002`	服务器/NAS 导航面板	官网	Release
Homepage	`3003`	高度可定制的应用仪表盘	官网	Release
Homarr	`7575`	服务器仪表盘与应用管理	官网	Release
Certimate	`8090`	SSL 证书管理	GitHub	Release
Vaultwarden	`8880`	密码管理（Bitwarden 兼容）	GitHub	Release
Nginx	`8888`	HTTP 服务与反向代理	官网	Release
Nginx UI	`9000`	Nginx 可视化管理面板，内置 Nginx 引擎	GitHub	Release
Gotify	`8070`	自托管推送通知服务	官网	Release
DDNS-GO	`9876`	动态 DNS 解析客户端	GitHub	Release
WolGoWeb	`9095`	网络唤醒 (Wake-on-LAN) 管理	GitHub	Release
AdGuardHome	`3080`	全网广告拦截与 DNS 管理	官网	Release
Uptime Kuma	`3001`	自托管服务监控	GitHub	Release
Beszel	`18090`	轻量级服务器监控	GitHub	Release
FileBrowser	`8089`	Web 文件管理器	官网	Release
Stirling-PDF	`18080`	自托管 PDF 工具箱	官网	Release
Actual Budget	`5006`	自托管个人财务管理	官网	Release
Lucky	`16601`	DDNS/反向代理/端口转发多功能工具	官网	Release
1Panel	`10086`	开源服务器管理面板	官网	Release
Grafana	`3010`	可视化监控仪表盘	官网	Release
Prometheus	`9090`	时序数据库与监控系统	官网	Release
Loki	`3100`	日志聚合系统，Grafana 生态	GitHub	Release
Glances	`61208`	系统监控，Web UI 版 htop	GitHub	Release
n8n	`5678`	工作流自动化工具	官网	Release
Ntfy	`2586`	自托管推送通知服务	官网	Release
Gitea	`3033`	轻量级 Git 代码托管	官网	Release
Duplicati	`8200`	加密备份工具	官网	Release
IT-Tools	`8280`	开发者工具箱	官网	Release
Mattermost	`8065`	企业即时通讯，Slack 替代	官网	Release
Home Assistant	`8123`	智能家居中枢平台	官网	Release
Nginx Proxy Manager	`81`	反向代理可视化管理	GitHub	Release
DPanel	`8807`	轻量级 Docker 管理面板	GitHub	Release
Netdata	`19999`	实时系统性能监控	官网	Release
Node-RED	`1880`	可视化流程自动化工具	官网	Release
Forgejo	`3005`	社区驱动的 Git 代码托管	官网	Release
ClamAV	`3310`	开源杀毒引擎	官网	Release
EZBookkeeping	`8580`	轻量级个人记账应用，支持多币种、多账户和预算管理	GitHub	[Release][r-ezbookkeeping]
Penpot	`9001`	开源设计和原型工具，Figma 的自托管替代方案	官网	[Release][r-penpot]
SurveyKing	`1991`	开源问卷调查和在线考试系统，支持多种题型、逻辑跳转和数据导出	官网	[Release][r-surveyking]
NVIDIA Driver	—	NVIDIA GPU 驱动（R580 LTS）+ nvidia-container-toolkit，仅 x86	官网	Release

🌐 网络工具

App	端口	说明	来源	下载
SmartDNS	`6580`	本地 DNS 加速与优选	GitHub	Release
MosDNS	`5354`	DNS 转发与分流	GitHub	Release
Pi-hole	`8053`	全网广告拦截 (DNS)	官网	Release
WG-Easy	`51821`	WireGuard VPN 管理界面	GitHub	Release
Headscale	`8480`	Tailscale 自托管控制服务器	GitHub	Release
NetBird	`8820`	Zero Trust VPN 平台	官网	Release
Tailscale	`8088`	Mesh VPN 客户端	官网	Release
Cloudflare Tunnel	`14333`	Cloudflare 内网穿透隧道，通过 Web 界面管理 Tunnel Token 配置	GitHub	[Release][r-cloudflared]
EasyTier	`11210`	简单安全的去中心化异地组网方案，支持 Web 管理和子网代理	GitHub	[Release][r-easytier]
Mihomo	`9097`	Clash.Meta 内核 + MetaCubeXD dashboard，含开箱即用配置模板、TUN 模式与 LAN 混合代理	GitHub	Release

🌐 浏览器

	App	端口	说明	来源	下载
	Firefox	`5801`	远程浏览器，支持中文	GitHub	Release
	Chromium	`5802`	远程浏览器，支持中文	GitHub	Release

反馈与请求

新应用请求：Open App Request
问题反馈：Open Bug Report

快速开始

安装

下载对应 App 的 Release 页面中的 .fpk 文件
在 fnOS 应用中心选择「手动安装」
上传 .fpk 并完成安装

本地构建

# 构建单个应用（以 plex 为例）
cd apps/plex && ./update_plex.sh

# 通用格式
cd apps/<app> && ./update_<app>.sh

构建产物统一输出到仓库根目录 dist/。

项目结构

fnos-apps/
├── apps/                    # 各应用的 fnOS 包定义与构建脚本
├── shared/                  # 通用生命周期脚本与向导模板
├── scripts/
│   ├── build-fpk.sh         # 通用 fpk 打包器
│   ├── new-app.sh           # 新应用脚手架
│   ├── apps/<app>/          # 每个应用的构建合约
│   └── ci/resolve-release-tag.sh
└── .github/workflows/       # 入口 workflow + 可复用构建 workflow

新增应用（维护者）

./scripts/new-app.sh <app-slug> "<display-name>" <port>
# example
./scripts/new-app.sh jellyfin "Jellyfin" 8097

推荐流程：

在 apps/<app>/ 完成 fnOS 清单和启动脚本
在 scripts/apps/<app>/ 完成版本探测与 app.tgz 组装
CI 自动发现新应用，无需手动创建 workflow 文件

CI/CD 设计

单一入口 build-apps.yml 自动发现 apps/ 下所有应用，动态矩阵构建
统一使用 scripts/build-fpk.sh 打包，减少各应用行为漂移
统一使用 reusable-build-app.yml 实现版本检查、矩阵构建、发布
标签策略由 scripts/ci/resolve-release-tag.sh 管理，支持 -r2/-r3 修订版自动递增
日常构建由定时任务和手动触发驱动，push 触发仅构建变更的应用

变更记录

项目变更记录请查看 CHANGELOG.md。

致谢

应用图标来自 Dashboard Icons（MIT License）

安全与透明

本仓库仅下载并重打包官方发布内容，不修改上游业务逻辑
当前应用均按非 root 用户运行（提升默认安全性）
构建脚本、CI 流程与发布记录均公开可审计

GitHub Shell Daily Trending Repositories

msitarzewski/agency-agents

🎭 The Agency: AI Specialists Ready to Transform Your Workflow

🆕 There's an app now

🚀 What Is This?

⚡ Quick Start

Option 1: Install the app (Recommended)

Option 2: Use with Claude Code

Option 3: Use as Reference

Option 4: Use with Other Tools (GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Kimi Code, Codex, Osaurus, Hermes, Mistral Vibe)

🎨 The Agency Roster

💻 Engineering Division

🎨 Design Division

💰 Paid Media Division

💼 Sales Division

📢 Marketing Division

📊 Product Division

🎬 Project Management Division

🧪 Testing Division

🔒 Security Division

🛟 Support Division

🥽 Spatial Computing Division

🎯 Specialized Division

💵 Finance Division

🎮 Game Development Division

Cross-Engine Agents (Engine-Agnostic)

Unity

Unreal Engine

Godot

Blender

Roblox Studio

📚 Academic Division

🌍 GIS Division

🏥 Healthcare Division

🎯 Real-World Use Cases

Scenario 1: Building a Startup MVP

Scenario 2: Marketing Campaign Launch

Scenario 3: Enterprise Feature Development

Scenario 4: Paid Media Account Takeover

Scenario 5: Full Agency Product Discovery

Scenario 6: Smart Campus Digital Twin

🤝 Contributing

Add a New Agent

Improve Existing Agents

Share Your Success Stories

📖 Agent Design Philosophy

🎁 What Makes This Special?

Unlike Generic AI Prompts:

Unlike Prompt Libraries:

Unlike AI Tools:

🎨 Agent Personality Highlights

📊 Stats

🔌 Multi-Tool Integrations

Supported Tools

⚡ Quick Install

Tool-Specific Instructions

Regenerating After Changes

🗺️ Roadmap

🌐 Community Translations & Localizations

🔗 Related Resources

📜 License

🙏 Acknowledgments

💬 Community

🚀 Get Started

nvm-sh/nvm

Node Version Manager

Table of Contents

Intro

About

Installing and Updating

Install & Update Script

Additional Notes

Installing in Docker

Installing in Docker for CICD-Jobs

Troubleshooting on Linux

Troubleshooting on macOS

Ansible

Verify Installation

Important Notes

Git Install

Calling `nvm use` automatically in a directory with a `.nvmrc` file