Hera — AI Coding Agent Architecture Reference. Install skill/reference for 18+ AI coding agents.
The most comprehensive architectural reference for building production-grade AI coding agents.
Verified from 9 open-source codebases with 770K+ combined GitHub stars.
Quick Start · Install · What's Inside · Agents · Architecture · Docs
# One command — auto-detects your agent
npx hera-skill
# Or specify your agent
npx hera-skill claude
npx hera-skill hermes
npx hera-skill cursor
What you get: Complete architecture reference, 28+ copy-paste templates, 18 reference files, 3 full working example agents, validation checklist, security patterns, and more — all verified from real production codebases.
Hera is a technical knowledge base that explains how production-grade AI coding agents work internally. Every pattern, every decision, every pitfall — verified against actual open-source codebases.
Important: Hera is a SKILL, not a product, framework, or competitor. It learns from other agents — it does not compete with them.
| Pi Agent |  | Two-loop agent, tree sessions, extensions, provider abstraction |
| ECC |  | 64 specialized agents, autonomous loops, self-debugging, hooks |
| OpenClaw |  | Agent-harness, branch compaction, context engineering |
| Aider |  | Edit formats, fuzzy match, architect mode, git-native patterns |
| OpenCode |  | Effect-TS, permission system, plugins, TypeScript errors |
| Kilo Code | | Scout mode, reference guidance, task coordination |
| GSD Core |  | Spec-driven development, multi-agent orchestration |
| RTK | | Token optimization (60–90% reduction) |
| Headroom | | Context compression (60–95% reduction, 6 algorithms) |
npx skills add ahmdd4vd/hera
npx hera-skill # Auto-detect
npx hera-skill claude # Specific agent
npx hera-skill --yes # Skip confirmation (CI/CD)
npx hera-skill --version-tag v2.10.0 # Pin version
curl -sSL https://raw.githubusercontent.com/ahmdd4vd/hera/main/install.sh | bash
git clone https://github.com/ahmdd4vd/hera.git && cd hera
./install.sh claude
Copy the right file to the right place. See agent mapping table below.
| Step | Description |
|---|---|
| 🔍 Auto-detect | Scoring-based detection finds your agent (files, dirs, commands, homeDirs) |
| ✅ Confirm | Interactive prompt shows detected agent — you confirm before anything happens |
| 💾 Backup | Existing files are backed up as .hera-backup before overwriting |
| 📥 Download | Files fetched from GitHub raw with content validation (min 50 chars, HTML rejection, markdown check) |
| 📍 Place | Each file goes to the correct location for your specific agent |
18 AI coding agents — one command to install for any of them
| Agent | Install Command | File | Location |
|---|---|---|---|
 Claude Code | npx hera-skill claude | CLAUDE.md | Project root |
 Hermes | npx hera-skill hermes | SKILL.md | ~/.hermes/skills/hera/ |
 Cursor | npx hera-skill cursor | hera.mdc | .cursor/rules/ |
 OpenCode | npx hera-skill opencode | AGENTS.md | Project root |
 Codex | npx hera-skill codex | AGENTS.md | Project root |
 Kilo Code | npx hera-skill kilo | SKILL.md | .kilo/skills/hera/ |
 Kiro | npx hera-skill kiro | SKILL.md | .kiro/skills/hera/ |
 Aider | npx hera-skill aider | AGENTS.md | Project root |
 Gemini CLI | npx hera-skill gemini | GEMINI.md | Project root |
 Pi | npx hera-skill pi | SKILL.md | ~/.pi/agent/skills/hera/ |
 GitHub Copilot | npx hera-skill copilot | SKILL.md | ~/.copilot/skills/hera/ |
 Devin | npx hera-skill devin | SKILL.md | ~/.config/devin/skills/hera/ |
 Antigravity | npx hera-skill antigravity | hera.md | .agents/rules/ |
 Amp | npx hera-skill amp | AGENTS.md | Project root |
 Trae | npx hera-skill trae | AGENTS.md | Project root |
 CodeBuddy | npx hera-skill codebuddy | SKILL.md | ~/.codebuddy/skills/hera/ |
 OpenClaw | npx hera-skill claw | CLAW.md | Project root |
 Factory Droid | npx hera-skill droid | AGENTS.md | Project root |
All agents → npx hera-skill all or ./install.sh all |
| # | Section | What You'll Learn |
|---|---|---|
| 1 | Package Structure | 4 packages and how they depend on each other |
| 2 | Core Types | Message, AgentState, AgentTool, AgentEvent definitions |
| 3 | Agent Loop | The main loop that calls LLM and executes tools |
| 4 | Agent Class | Stateful wrapper with message queueing |
| 5 | Agent Harness | Orchestration layer with session, hooks, compaction |
| 6 | Session System | Tree-based conversation storage with branching |
| 7 | Compaction | Auto-summarize old messages to fit context window |
| 8 | Message Conversion | How custom messages become LLM-compatible messages |
| 9 | Tool System | 7 built-in tools (read, write, edit, bash, grep, find, ls) |
| 10 | Extension System | Plugin system with lifecycle hooks and UI primitives |
| 11 | AI Layer | Provider abstraction, custom providers, fallback chain |
| 12 | System Prompt | How the system prompt is constructed |
| 13 | Skills & Templates | How skills and prompt templates are loaded |
| 14 | Event Architecture | Full event flow from user input to response |
| 15 | Design Patterns | 8 patterns used throughout the codebase |
| 16 | Implementation Guide | Step-by-step order to build your own agent |
| 17 | Pitfalls | 8 mistakes to avoid |
| 18 | Multi-Agent Knowledge | 10 patterns, 15 decision points, 15 anti-patterns |
| 19 | Innovation Patterns | FAST / SMART / NOT STUPID patterns |
| 20 | Architecture Diagrams | 6 Mermaid diagrams |
| 21 | Validation Checklist | 11 categories with 50+ checkboxes |
| 22 | Code Templates | 6 TypeScript + 6 Python templates |
| 23 | Security Patterns | Tool sandboxing, permissions, I/O sanitization |
| 24 | Error Handling | Retry, graceful degradation, error propagation |
| 25 | Testing Patterns | Unit, integration, E2E tests with mocks and fixtures |
| 26 | CLI Tools | hera init (scaffold) and hera validate (verify) |
| 27 | Example Agent | Complete working agent (TypeScript + Python) |
| 28 | Deployment | Local, Docker, cloud deployment with monitoring |
| 29 | GitHub Actions | CI/CD integration for automated validation |
| 30 | Production Patterns | Task routing, streaming, memory management |
| 31 | Spec-Driven Development | Pipeline from spec to code with multi-agent orchestration |
| 32 | Token Optimization | 6 strategies for 60–95% token reduction |
| File | Lines | Deep Dive Into |
|---|---|---|
references/hermes-architecture.md | 16,068 | Hermes Agent: multi-platform gateway (20+), self-improving skills with curator, provider-agnostic, MCP-native, cron scheduler |
references/aider-architecture.md | 15,320 | Aider: 6 edit formats, architect mode, repo map (tree-sitter + PageRank), fuzzy match, reflection loop |
references/claude-code-architecture.md | 14,279 | Claude Code: query loop (2,240 lines), 50+ tools, 7 permission modes, hook system, subagent system |
references/ecc-architecture.md | 8,990 | ECC Plugin: 64 specialized agents, 17 hooks, rules per language, 262 skills |
references/opencode-architecture.md | 8,291 | OpenCode Go: agent loop (758 lines), 11 providers, 10 tools, permission system |
references/kilocode-architecture.md | 5,417 | Kilo Code: Agent Manager, auto-generated SDK, gateway pattern, worktree isolation |
references/advanced-patterns.md | 911 | 8 production features: MCP, Skills, Memory, Plugins, Cost Tracking, Observability |
references/agent-loop-harness.md | — | Agent loop + class + harness extracted from SKILL.md §3–5 |
references/session-and-compaction.md | — | Session tree + compaction extracted from SKILL.md §6–7 |
references/ai-providers-layer.md | — | Provider abstraction extracted from SKILL.md §11 |
references/9router-architecture.md | — | 9router: unified multi-provider routing with OAuth |
references/multi-provider-routing.md | — | Multi-provider routing patterns, OAuth, fallback chains |
references/provider-model-catalog.md | — | Model catalog across all providers |
references/codex-architecture.md | — | Codex architecture deep analysis |
references/ecc-patterns.md | 400 | ECC patterns: agent harness, autonomous loops, self-debugging |
references/token-optimization.md | 479 | 6 compression strategies (60–95% reduction) |
references/spec-driven-development.md | 132 | Spec pipeline, multi-agent orchestration, context engineering |
references/innovation-patterns.md | 69 | FAST / SMART / NOT STUPID patterns from all repos |
| Template | Description |
|---|---|
minimal-agent-loop.ts | Two-loop agent with steering and follow-up |
minimal-tool.ts | Tool system with validation and parallel execution |
minimal-session.ts | Tree-based session with branching |
minimal-provider.ts | Provider abstraction with streaming |
minimal-harness.ts | Orchestration with hooks and compaction |
minimal-extension.ts | Plugin system with lifecycle hooks |
minimal-provider-fallback.ts | Fallback chain for reliability |
minimal-streaming.ts | Streaming with backpressure |
multi-provider-router.ts | Multi-provider routing |
mcp-server.ts | MCP server implementation |
mcp-client.ts | MCP client implementation |
mcp-stdio-sse-bridge.ts | MCP stdio-SSE bridge |
mcp-marketplace.ts | MCP marketplace |
antigravity-wrapper.ts | Antigravity agent wrapper |
| Template | Description |
|---|---|
minimal_agent_loop.py | Two-loop agent with steering |
minimal_tool.py | Tool system with validation |
minimal_session.py | Tree-based session |
minimal_provider.py | Provider abstraction |
minimal_harness.py | Orchestration with hooks |
minimal_extension.py | Plugin system |
minimal_provider_fallback.py | Fallback chain |
minimal_streaming.py | Streaming implementation |
multi-provider-router.py | Multi-provider routing |
| Template | Description |
|---|---|
api-key-validator.ts | API key validation and rotation |
tts-provider.ts | Text-to-speech provider |
stt-provider.ts | Speech-to-text provider |
image-provider.ts | Image generation provider |
embedding-provider.ts | Embedding provider |
web-search.ts | Web search provider |
web-fetch.ts | Web content fetching |
quota-tracker.ts | Usage quota tracking |
spoof-headers.ts | Header management |
tunnel.ts / tunnel-cloudflare.ts / tunnel-tailscale.ts | Tunnel providers |
updater.ts | Self-update mechanism |
multimodal-input.ts | Multi-modal input handling |
| Example | Language | Description |
|---|---|---|
examples/full-agent/ | TypeScript | Complete agent with tools, session, provider, tests |
examples/python-agent/ | Python | Complete agent with 29 tests, multi-provider, CLI |
examples/full-stack-agent/ | TypeScript | Full-stack agent with all features |
| 🔄 Two-Loop Agent Loop | Inner loop handles tool calls and mid-run user messages (steering). Outer loop handles follow-up messages that arrive after the agent would normally stop. |
| 🌳 Tree-Based Sessions | Conversations stored as a tree, not a linear log. Fork from any point and explore different paths. |
| 📦 Built-in Compaction | When context window gets too long, old messages are auto-summarized. Recent messages kept intact. |
| 📨 Queue-Based Steering | Inject messages while the agent is running. Three queue types: steer (mid-run), follow-up (after stop), next-turn (prepend). |
| 🔌 Provider Abstraction | Same API for 20+ providers (OpenAI, Anthropic, Google, Bedrock, etc.). Fallback chains ensure reliability. |
| ♾️ Autonomous Loops | Six loop patterns from ECC: sequential, infinite, PR loop, de-sloppify, multi-agent DAG, RFC-driven. |
| 📉 Token Optimization | Six compression strategies: command output, diff/search/log, live zone, adaptive. 60–95% reduction. |
SKILL.md includes 6 Mermaid diagrams that render on GitHub:
HERA_FRAMEWORK.md (663 lines) — A structural framework based on AGENTS.md hierarchy that keeps any agent project organized and maintainable.
| Feature | Details |
|---|---|
| 5 Project Templates | coding-agent, web-app, library, api-server, monorepo |
| 3 Real Examples | Pi Agent, OpenClaw, Aider architecture breakdowns |
| 8 Agent-Specific Guidance | Claude Code, OpenCode, Cursor, Kilo Code, OpenClaw, Hermes, Pi, Copilot |
| 16 Validation Checks | Structure, naming, hierarchy, consistency |
| 6 Anti-Patterns | Common mistakes with examples and fixes |
hera/
├── 📄 AGENTS.md Root contract (Hera Framework)
├── 📄 HERA_FRAMEWORK.md Structural framework (663 lines)
├── 📄 SKILL.md Architecture reference (2,412 lines, 32 sections)
├── 📄 CLAUDE.md Claude Code config
├── 📄 README.md This file
├── 📄 CHANGELOG.md Version history
├── 📄 CONTRIBUTING.md How to contribute
├── 📄 DEPLOYMENT.md Deployment guide
├── 📄 ERROR_HANDLING.md Error handling patterns
├── 📄 SECURITY.md Security patterns
├── 📄 TESTING.md Testing patterns
├── 📄 LICENSE MIT License
│
├── 📁 references/ Deep-dive reference files (18 files)
│ ├── hermes-architecture.md Hermes deep analysis (16,068 lines)
│ ├── aider-architecture.md Aider deep analysis (15,320 lines)
│ ├── claude-code-architecture.md Claude Code deep analysis (14,279 lines)
│ ├── ecc-architecture.md ECC deep analysis (8,990 lines)
│ ├── opencode-architecture.md OpenCode deep analysis (8,291 lines)
│ ├── kilocode-architecture.md Kilo Code deep analysis (5,417 lines)
│ ├── advanced-patterns.md 8 production features
│ ├── agent-loop-harness.md Agent loop + class + harness
│ ├── session-and-compaction.md Session tree + compaction
│ ├── ai-providers-layer.md Provider abstraction
│ ├── 9router-architecture.md Multi-provider routing
│ ├── multi-provider-routing.md Routing patterns with OAuth
│ ├── provider-model-catalog.md Model catalog
│ ├── codex-architecture.md Codex architecture
│ ├── ecc-patterns.md ECC patterns
│ ├── token-optimization.md Token optimization (6 strategies)
│ ├── spec-driven-development.md Spec-driven development
│ └── innovation-patterns.md Innovation patterns
│
├── 📁 templates/ Copy-paste ready code (30 files)
│ ├── TypeScript (14) Agent, tool, session, provider, harness, extension, MCP...
│ ├── Python (9) Agent, tool, session, provider, harness, extension...
│ └── Infrastructure (7+) TTS, STT, image, embedding, web search, tunnel, quota...
│
├── 📁 examples/ Full working agents
│ ├── full-agent/ TypeScript example agent
│ ├── python-agent/ Python example agent (29 tests)
│ └── full-stack-agent/ Full-stack example agent
│
├── 📁 docs/ Supplementary documentation
│ ├── PATTERNS.md Production patterns
│ ├── STREAMING.md Streaming patterns
│ ├── MEMORY.md Memory management
│ └── ROUTING.md Provider routing
│
├── 📁 cli/ CLI tools
│ ├── hera-init.ts Scaffold CLI
│ ├── hera-validate.ts Validation CLI
│ ├── hera-graph.ts Knowledge graph visualization
│ └── index.ts Main CLI entry (install subcommand)
│
├── 📁 bin/ Distribution
│ └── hera.cjs Standalone CLI (1,172 lines)
│
├── 📁 .github/ CI/CD
│ ├── workflows/ci.yml GitHub Actions CI pipeline
│ └── actions/validate/ Validation action
│
├── 📁 .cursor/rules/ Cursor config
│ └── hera.mdc
├── 📁 .agents/rules/ Antigravity config
│ └── hera.md
├── 📁 .agents/workflows/ Antigravity workflows
│ └── hera.md
├── 📁 .kiro/skills/hera/ Kiro config
│ └── SKILL.md
└── 📁 .kilo/skills/hera/ Kilo Code config
└── SKILL.md
 32 sections |
 18 files |
 14 TS + 9 PY + 7 infra |
 across all source files |
 TS + Python + Full-stack |
 770K+ combined stars |
 Full architecture analyses |
 Install in one command |
| Document | Description |
|---|---|
| SKILL.md | Main architecture reference (2,412 lines, 32 sections) |
| HERA_FRAMEWORK.md | Structural framework (663 lines) |
| AGENTS.md | Root contract for Hera Framework |
| CHANGELOG.md | Version history |
| CONTRIBUTING.md | How to contribute |
| DEPLOYMENT.md | Deployment guide |
| ERROR_HANDLING.md | Error handling patterns |
| SECURITY.md | Security patterns |
| TESTING.md | Testing patterns |
Hera — Architecture Reference for AI Coding Agents
Built by ahmdd4vd · Licensed under MIT
If Hera helped you build something awesome, consider giving it a ⭐
FAQs
Hera — AI Coding Agent Architecture Reference. Install skill/reference for 18+ AI coding agents.
The npm package hera-skill receives a total of 4 weekly downloads. As such, hera-skill popularity was classified as not popular.
We found that hera-skill demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.