A full AI engineering team as plain Markdown files.
Specialized AI agents — architect, reviewer, security expert, DevOps engineer, strategist, operator, and more — each a single Markdown skill file any agent runtime can load into any project. No lock-in. No configuration. Just drop them in.
They have opinions about your PR descriptions. They will not merge your branch if your commit says fix stuff. They are not polite about it.
I commit with intention. I branch with purpose. I review with honesty. I ship with confidence. I never push to main.
Each agent is a single .md file that describes a role, its responsibilities, standards, and how it communicates. Load one or all of them into Claude Code, Copilot, or any runtime that supports skill files. Or run them autonomously via the TypeScript CLI.
- Install the Society —
npm install --save-dev agenthood && npx agenthood init(ornpx skills add fworks-tech/agenthoodvia skills.sh) - Load into your runtime — point Claude Code, Copilot, or your agent framework at the skills directory
- Invoke any agent — ask the Reviewer to check your PR, ask the Auditor to scan your auth flow. They know their role. They have standards.
Every role a real software team needs — available as a skill file with impeccable standards.
| Agent | Role | |
|---|---|---|
| ✍️ | The Scribe | Commits, PRs, changelogs |
| 🏗️ | The Architect | System design, ADRs, tech decisions |
| 🛠️ | The Builder | Coding, implementation, refactoring, validation |
| 🔍 | The Reviewer | Code review, standards enforcement |
| 🧪 | The Tester | TDD, coverage, edge cases |
| 🐛 | The Debugger | Error triage, root cause analysis |
| 🔒 | The Auditor | Security, vulnerability scanning, dependency audit |
| 📦 | The Herald | Releases, versioning, changelogs |
| 📝 | The Librarian | Documentation, API references |
| 🚪 | The Doorman | Validation, branch protection, health checks |
| 🔮 | The Oracle | Institutional knowledge, authoring templates |
| 🌐 | The Envoy | Cross-provider translation, convention validation |
| 👁️ | The Sentinel | Integrity, cross-member contradiction detection |
| ⚖️ | The Warden | Code health, complexity enforcement |
| 🧭 | The Steward | Context economy, provider cache strategies |
| 🎯 | The Strategist | Goal refinement, requirement discovery |
| 🩺 | The Operator | Runtime health, deployments, rollback |
| 👁️ | The Inspector | Visual-reasoning benchmarking, pixel analysis |
| 📬 | The Mailman | Message delivery, scheduling, cross-posting |
npm install --save-dev agenthood
npx agenthood init # interactive setup (~1 minute)
npx agenthood check # verify everything is in placeMembers are loaded as context by your existing AI assistant. Works with Claude Code and Copilot.
Execute members as real LLM agents that reason, act, and remember across sessions.
# From the repo clone (when installed via npm, the runtime is pre-built)
npm run build # build the runtime (once)
npx agenthood list # see available agents
npx agenthood run the-scribe "write a commit message for the current diff"
npx agenthood run the-reviewer "review the changes in the last commit"
npx agenthood run the-architect "plan the implementation for issue #42"
npx agenthood verify # validate member SKILL.md integrity
npx agenthood status --watch # live project health monitoring
npx agenthood trace # list recent invocation traces
npx agenthood health # runtime health checks (exit 0/1/2)
npx agenthood eval the-reviewer --suite evals/benchmarks/review-pr.json # scored eval with baseline gating
npx agenthood rollback the-scribe # restore SKILL.md from lockfile
npx agenthood workflow review-pr # execute the review-pr workflowSet one of these in a .env file in your project root (loaded automatically by the runtime) — and add .env to your .gitignore so keys never get committed. The default provider follows the providers list in .agenthood/config.json (opencode primary, Groq among the fallbacks) — set the keys for the providers you want available:
| Variable | Provider | Free tier |
|---|---|---|
OPENCODE_API_KEY |
OpenCode / OpenCodeGo (default) | opencode.ai |
GROQ_API_KEY |
Groq (fallback) | console.groq.com |
ANTHROPIC_API_KEY |
Anthropic | — |
OPENAI_API_KEY |
OpenAI | — |
Or use Ollama for fully offline execution (no key required).
For a full walkthrough — install, commands, CI pipeline, and next steps — see the Academy Getting Started guide.
See the CHANGELOG.md for the full version history.
Agenthood Studio — a browser-based chat interface for all 19 Society members. Features configurable provider backend (Anthropic, OpenAI, Groq, Ollama, OpenCode), SSE streaming, turnstile CAPTCHA, session-scoped config persistence, Upstash Redis rate limiting, and structured logging with field-level redaction. Source
Agenthood is agent-agnostic. The skill files work with:
- Claude Code — via
.claude/skills/ - GitHub Copilot — via
.github/copilot-instructions.md
The TypeScript runtime (agenthood run) supports OpenCode (default, per .agenthood/config.json), Groq (free tier at console.groq.com), Anthropic, OpenAI, and Ollama for fully offline execution.
The Agenthood Studio playground exercises the same runtime through a browser UI — every chat request runs through agenthood/dist/llm with provider routing, failover, and streaming.
The framework runs on five core principles adapted from production AI agent systems. See the architecture docs for details on how agents coordinate, prioritize, fail over, and stay safe.
| Principle | Document |
|---|---|
| Multi-agent orchestration & agent roles | agent-system.md |
| Priority queues & concurrency slots | concurrency-and-queues.md |
| Agent mode vs Ask mode | operating-modes.md |
| Multi-LLM support & automatic failover | provider-failover.md |
| Tool registry, scoping & safety caps | built-in-tools.md |
| Agent memory tiers | memory — ResidualMemory, ShortTermMemory, LongTermMemory, EpisodicMemory, ProjectMemory, DecisionLog, ProvenanceStore, DecisionSearch, GraphSnapshot, MetricsCollector, InMemoryStore, PersonalisationStore, LanceDBStore |
| Decision intelligence & auditability | decision-intelligence.md — per-run decision records, causal chains (CAUSED/INFLUENCED/PRECEDENT_FOR), tamper-evident provenance (SHA-256 hash chain), precedent search, society-graph snapshots |
| Workflow engine & quality gates | workflows — WorkflowEngine, QualityGates, DiffImpactAnalyzer, WorkflowCheckpoint, GoalChain |
| Service-agnostic RAG (graph, vector, agentic) | rag — KnowledgeGraphStore, FixedSizeChunkStrategy + MarkdownHierarchicalChunkStrategy, Indexer, Retriever, AgenticRAG, TreeSitterParser, ProjectIngestion |
npm install && npm run build
make setup # activates git hooks and commit template
npm test # run all tests
npm run typecheck # strict TypeScript check
npm run lint # ESLintSee STRUCTURE.md for the full directory tree.
Structured learning path from "what is a prompt?" to "ship agents to production."
- Getting Started — install, first commit, CI, configuration
- Skills Reference — all members, their tools, and invocation
- Utility Skills — specialist skills beyond the members
- Level 1: GenAI & RAG Basics — LLMs, prompt engineering, RAG
- Level 2: AI Agent Essentials — memory, planning, multi-agent systems
- Level 3: Advanced Agent Skills — integration, performance, deployment
- Conventional Commits
- addyosmani/agent-skills
- opencode — default free LLM provider
- semantic-release
- commitlint
Open source. No sign-up. Works with any agent runtime. Membership is free. Standards are not.