Onboarding: facebook/hermes

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/facebook/hermes shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit today
• 15 active contributors
• Distributed ownership (top contributor 25% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live facebook/hermes repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebook/hermes.

What it runs against: a local clone of facebook/hermes — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in facebook/hermes | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch static_h exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>facebook/hermes</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebook/hermes. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebook/hermes.git
#   cd hermes
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of facebook/hermes and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "facebook/hermes(\\.git)?\\b" \\
  && ok "origin remote is facebook/hermes" \\
  || miss "origin remote is not facebook/hermes (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify static_h >/dev/null 2>&1 \\
  && ok "default branch static_h exists" \\
  || miss "default branch static_h no longer exists"

# 4. Critical files exist
test -f "API/hermes/CompileJS.cpp" \\
  && ok "API/hermes/CompileJS.cpp" \\
  || miss "missing critical file: API/hermes/CompileJS.cpp"
test -f "API/hermes/DebuggerAPI.h" \\
  && ok "API/hermes/DebuggerAPI.h" \\
  || miss "missing critical file: API/hermes/DebuggerAPI.h"
test -f "API/hermes/TracingRuntime.cpp" \\
  && ok "API/hermes/TracingRuntime.cpp" \\
  || miss "missing critical file: API/hermes/TracingRuntime.cpp"
test -f "API/hermes/cdp/CDPAgent.cpp" \\
  && ok "API/hermes/cdp/CDPAgent.cpp" \\
  || miss "missing critical file: API/hermes/cdp/CDPAgent.cpp"
test -f "API/hermes/cdp/tools/hermes-inspector-msggen/src/Command.js" \\
  && ok "API/hermes/cdp/tools/hermes-inspector-msggen/src/Command.js" \\
  || miss "missing critical file: API/hermes/cdp/tools/hermes-inspector-msggen/src/Command.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/facebook/hermes"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Hermes is a JavaScript engine optimized for fast startup and efficient bytecode execution in React Native apps. It provides ahead-of-time static optimization, compact bytecode representation, and reduced memory footprint compared to V8, making it ideal for mobile environments where startup time and app size matter. Mixed-language monorepo: API/ contains the C++ engine and AsyncDebuggerAPI, .circleci/ and .github/workflows/ define build pipelines for Linux/macOS/Windows/Android/iOS cross-compilation, .claude/ contains AI-assisted skills (IR instructions, GC safety, JSI features), and tools are built via CMake/Ninja producing ./bin/hermes CLI executable.

Who it's for

React Native developers and framework maintainers who need to deploy JavaScript apps on mobile platforms (iOS/Android) with sub-second startup times and minimal app bloat. Also used by Meta engineers optimizing React Native infrastructure.

Maturity & risk

Highly mature and production-ready. The repo shows significant scale (26M+ lines JavaScript, 17M+ C++), comprehensive CI/CD across .github/workflows/ (10+ build pipelines), established release process (npm hermes-engine package with semantic versioning tied to React Native releases), and clear version stability warnings in README requiring strict version matching with React Native.

Low risk for stability but version coupling risk is real—README explicitly warns 'Version mismatch can result in instant crash' requiring strict alignment with specific RN releases. Dependency surface is moderate (C++/Rust/Python toolchain required); primary risk is that custom builds diverging from official releases may break in subtle ways during RN integration.

Active areas of work

Active development with multi-platform build automation (Apple slices, hermesc for multiple OSes in .github/workflows/), debugger API expansion (AsyncDebuggerAPI.cpp), and tooling for performance analysis (.llms/skills/sh_perf_investigation.md suggests ongoing optimization focus). CI clearly runs on every commit given the dense workflow definitions.

Get running

mkdir hermes_workingdir && cd hermes_workingdir
git clone https://github.com/facebook/hermes.git
cmake -S hermes -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build ./build
echo "'use strict'; function hello() { print('Hello World'); } hello();" | ./bin/hermes

Daily commands: No npm/yarn dev server—this is a compiled engine. Build with cmake --build ./build, then invoke CLI via ./bin/hermes <script.js> or pipe JavaScript to stdin as shown in README. For React Native integration, use instructions in doc/ReactNativeIntegration.md or follow doc/BuildingAndRunning.md for debug vs. release builds.

Map of the codebase

• API/hermes/CompileJS.cpp — Core JavaScript compilation entry point that converts JS source to Hermes bytecode; essential for understanding the compilation pipeline.
• API/hermes/DebuggerAPI.h — Main debugger interface header defining the API contract for debugging support in Hermes; required reading for debugging feature work.
• API/hermes/TracingRuntime.cpp — Runtime tracing and profiling infrastructure; critical for performance optimization and instrumentation features.
• API/hermes/cdp/CDPAgent.cpp — Chrome DevTools Protocol agent implementation; central to inspector/debugger functionality used by React Native tooling.
• API/hermes/cdp/tools/hermes-inspector-msggen/src/Command.js — Message generator for CDP commands; foundational tool for auto-generating inspector protocol bindings.
• .circleci/config.yml — Build and test pipeline configuration; defines how all code changes are validated before merge.

Components & responsibilities

• CompileJS (C++, IR graph manipulation) — Transforms JavaScript source → Hermes bytecode via IR transformation passes
  • Failure mode: Compilation error → app fails to load; syntax errors or unsupported features rejected
• Runtime VM (C++ interpreter, register-based VM) — Executes bytecode, manages memory, maintains call stack, coordinates GC
  • Failure mode: Runtime error → app crash; out-of-memory → GC fail/crash; stack overflow
• DebuggerAPI (C++ debug protocol handlers) — Exposes breakpoint, stepping, and variable inspection interfaces to debugger clients
  • Failure mode: Debugger disconnect → loss of debugging session; breakpoint mismatch → incorrect pause location
• undefined — undefined

How to make changes

Add a new CDP domain/feature to the debugger

1. Define the new domain messages in devtools-protocol spec (or create a new domain JSON descriptor) (API/hermes/cdp/tools/hermes-inspector-msggen/src)
2. Create a new DomainAgent subclass (e.g., NewDomainAgent.cpp/h following pattern of DebuggerDomainAgent.cpp) (API/hermes/cdp/NewDomainAgent.h)
3. Implement domain-specific request handlers and event dispatching in the agent (API/hermes/cdp/NewDomainAgent.cpp)
4. Register the new agent in CDPAgent.cpp's coordinator initialization (API/hermes/cdp/CDPAgent.cpp)
5. Run msggen to auto-generate MessageTypes bindings: yarn build in hermes-inspector-msggen/ (API/hermes/cdp/tools/hermes-inspector-msggen/package.json)

Add a new compilation optimization pass

1. Create a new IR transformation pass file in the compiler directory (API/hermes/CompileJS.h)
2. Implement the IR pass following existing patterns (visit nodes, transform, return new IR) (API/hermes/CompileJS.cpp)
3. Integrate the pass into the compilation pipeline in CompileJS.cpp's compile() function (API/hermes/CompileJS.cpp)
4. Add test coverage in the build system (update API/CMakeLists.txt if needed) (API/CMakeLists.txt)

Add a new profiling or trace feature

1. Define new trace event types or metrics in SynthTrace.h header (API/hermes/SynthTrace.h)
2. Implement trace recording logic in SynthTrace.cpp or TracingRuntime.cpp (API/hermes/SynthTrace.cpp)
3. Add parser/interpreter support in SynthTraceParser.cpp to handle the new trace format (API/hermes/SynthTraceParser.cpp)
4. Integrate trace collection into the runtime via TracingRuntime.cpp hooks (API/hermes/TracingRuntime.cpp)

Why these technologies

• Chrome DevTools Protocol (CDP) — Standardized protocol for debugger/inspector communication; enables React Native DevTools and Chrome Inspector integration without proprietary protocol
• CMake build system — Cross-platform (Windows, macOS, Linux, Android, iOS) build configuration; essential for Hermes' multi-target deployment
• Babel + Flow (JavaScript codegen) — msggen tool auto-generates CDP bindings from protocol specs, reducing boilerplate and keeping inspector code in sync with Chrome protocol definitions
• Ahead-of-time (AOT) compilation to bytecode — Reduces startup time and memory footprint for React Native apps; core differentiator vs. V8/JSC interpreters

Trade-offs already made

• Bytecode interpretation vs. JIT compilation

  • Why: Hermes prioritizes startup speed and binary size (important for mobile) over peak runtime performance
  • Consequence: Slower execution than JIT-compiled engines (V8) but faster app launch and smaller APK/IPA sizes

• Static compilation pipeline (no dynamic eval)

  • Why: Enables aggressive static analysis and optimization passes; improves predictability and security
  • Consequence: Cannot dynamically generate or patch code at runtime; eval() and Function() constructor not supported

• Synchronous debugger API vs. async-first

  • Why: Simpler integration with existing React Native tooling expectations
  • Consequence: AsyncDebuggerAPI added later for non-blocking operations; dual API surface increases complexity

Non-goals (don't propose these)

• Does not support full ECMAScript spec features (e.g., WeakMap, Proxy, Reflect); targets stable ES2015+ subset
• Not a general-purpose server-side JS engine; optimized exclusively for React Native mobile app execution
• Does not provide Node.js compatibility or built-in modules (fs, net, etc.); runs app code only
• Not designed for JIT or dynamic optimization; static compilation is final

Traps & gotchas

1. Strict version alignment: Hermes is always released for a specific React Native version; mismatched versions cause instant crashes (not just incompatibilities). 2) Multi-platform C++ compilation: Windows requires 'Visual Studio 16 2019' with specific CMake flags (see README); Linux/macOS use Ninja—easiest to test on native platform first. 3) Custom builds for RN integration require exact procedure in doc/ReactNativeIntegration.md; skipping steps breaks linking. 4) Node >=18 required (from hermes-inspector-msggen package.json engines field). 5) CMake must find native tools (clang, ninja, python3) in PATH; no clear error messages if missing—check doc/BuildingAndRunning.md prerequisites.

Architecture

Concepts to learn

• Bytecode and Ahead-of-Time (AOT) Optimization — Core to Hermes' fast startup—JavaScript is compiled to optimized bytecode at build time, not interpreted at runtime; understanding bytecode structure is essential for modifying CompileJS.cpp or IR instructions
• Incremental Garbage Collection (GC) — Hermes uses incremental GC to reduce pause times on mobile; the .claude/skills/gc-safe-coding/ skill documents constraints on mutable state and GC cycles critical for memory-safe changes
• Just-In-Time (JIT) Compilation vs. Interpretation — Hermes trades peak performance (no JIT) for predictable startup and code size; understanding why Hermes doesn't use JIT clarifies its design tradeoffs vs. V8
• Compact Bytecode Format — Hermes' bytecode is designed for minimal file size (critical for app distribution); modifications to instruction set or serialization affect bundle size—see binary-size-analysis skill
• Cross-Platform Native Build Systems (CMake/Ninja) — Hermes builds on Linux, macOS, Windows, iOS, and Android via unified CMake; understanding CMakeLists.txt and per-platform toolchains (clang, MSVC, Android NDK) is mandatory for build changes
• Debugger Protocol (Chrome DevTools Protocol) — AsyncDebuggerAPI implements protocol for React Native Inspector; hermes-inspector-msggen uses devtools-protocol 0.0.1383960 to auto-generate message types—critical for debugger feature additions
• Static Analysis and IR (Intermediate Representation) — Hermes performs static optimization passes on IR before bytecode generation; .claude/skills/add-ir-instruction/ documents how to extend the IR with new instruction types for optimization opportunities

Related repos

• facebook/react-native — Primary consumer of Hermes; React Native apps select Hermes as their JS engine and version must match exactly per README
• google/v8 — Alternative JavaScript engine that Hermes optimizes against; understanding V8's trade-offs (startup time vs. peak performance) clarifies Hermes' design goals
• rust-lang/rust — Hermes incorporates 1.2M lines of Rust (visible in language breakdown) for performance-critical subsystems; Rust components are compiled via rustc in the CMake pipeline
• facebook/jsi — JavaScript Interface (JSI) is Hermes' C++ bridge to React Native native modules; .claude/skills/modify-jsi-features/ indicates active JSI feature work
• WebKit/webkit — Safari's JavaScriptCore engine; Hermes shares similar mobile optimization goals (startup, memory) and occasionally benchmarks against JSC

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for CDP (Chrome DevTools Protocol) integration

The API/hermes/cdp directory contains CDPAgent.cpp/h and CDPDebugAPI.cpp/h files that implement Chrome DevTools Protocol support for debugging Hermes, but there's no visible test coverage in the repository structure. Given that debugging is critical for React Native developers and CDP is a complex protocol with many message types, adding unit tests would catch regressions early and improve reliability for contributors.

• [ ] Create test/cdp directory structure mirroring API/hermes/cdp
• [ ] Add unit tests for CDPAgent initialization, message routing, and lifecycle management
• [ ] Add integration tests for CDPDebugAPI covering protocol message handling using the devtools-protocol v0.0.1383960 dependency already in package.json
• [ ] Test error handling and edge cases in message serialization
• [ ] Add tests validating CDP message format compliance against the devtools-protocol spec

Add GitHub Actions workflow for SynthTrace and TraceInterpreter validation

The API/hermes directory contains SynthTrace (synthetic execution trace) functionality (SynthTrace.cpp/h, SynthTraceParser.cpp/h, and TraceInterpreter.cpp/h) which is crucial for performance profiling and benchmarking React Native apps. There's no dedicated CI workflow visible for validating trace generation, parsing, and interpretation. A new workflow would ensure trace compatibility across commits and catch regressions in the tracing infrastructure.

• [ ] Create .github/workflows/trace-validation.yml
• [ ] Add build step for trace generation utilities
• [ ] Add validation tests for SynthTraceParser against sample trace files
• [ ] Add tests for TraceInterpreter correctness with various bytecode scenarios
• [ ] Include binary size analysis for trace-related artifacts (complement existing binary-size-analysis skill)

Implement missing test coverage for JSI (JavaScript Interface) feature modifications

The repository has a skill documented at .claude/skills/modify-jsi-features/SKILL.md indicating JSI is a key customization point, but there's no visible dedicated test directory for JSI modifications in the file structure. JSI is the bridge between native code and JavaScript in React Native, making robust testing essential. Adding structured tests would help contributors safely extend JSI without breaking the engine's core functionality.

• [ ] Create test/jsi directory with test harnesses for JSI modifications
• [ ] Add tests for common JSI extension scenarios (hosting objects, functions, async operations)
• [ ] Create test templates matching patterns described in .claude/skills/modify-jsi-features/SKILL.md
• [ ] Add integration tests validating JSI modifications work correctly with Hermes bytecode compilation
• [ ] Add documentation in test/jsi/README.md explaining how to test custom JSI extensions

Good first issues

• Add TypeScript type stubs for the C++ AsyncDebuggerAPI exported bindings—currently .h files lack JSDoc; would improve IDE experience for debugger integrations
• Write integration tests in .github/workflows/ validating hermesc bytecode output is identical across Linux/macOS/Windows (deterministic builds); currently matrix builds exist but no cross-platform bytecode comparison
• Document GC pause time benchmarks in a new doc/GCPerformance.md, parsing data from .llms/skills/sh_perf_investigation.md; would help contributors understand latency tradeoffs in GC changes

Top contributors

• @avp — 25 commits
• @marcoww6 — 20 commits
• @tsaichien — 17 commits
• @micleo2 — 16 commits
• @panagosg7 — 6 commits

Recent commits

• ce387c3 — fix: include macOS slice in universal hermes xcframework (#1958) (Saadnajmi)
• 7b12fec — Fix \P with case insensitive matching (micleo2)
• b780866 — Fix addRangeArrayPoolToBracket (micleo2)
• 33aabd8 — Remove unneccesary entries for Script_Extensions (micleo2)
• 9f83d64 — Sort & Merge Script_Extensions (micleo2)
• bec3fd4 — Deploy 0.312.1 to xplat (panagosg7)
• 179a562 — Release version to 0.36.1 (imdreamrunner)
• 27e1403 — Fix EMPTY_TRANSLATION_RESULT typing in flow-api-translator (panagosg7)
• ae26fa9 — Strip munged underscore members from declare stubs in flow-api-translator (panagosg7)
• 8a94652 — Fix flow-api-translator emitting => instead of : for declare hook return types (panagosg7)

Security observations

• High · Outdated devtools-protocol Dependency — package.json - dependencies.devtools-protocol. The package uses devtools-protocol version 0.0.1383960, which is an extremely old pinned version from 2019. This version likely contains multiple known security vulnerabilities and lacks security patches. The version numbering suggests this is not a standard semantic versioning release. Fix: Update to the latest stable version of devtools-protocol (currently 0.0.1171900+ or newer). Run 'npm audit' and address all reported vulnerabilities. Consider using caret ranges (^) instead of exact pinning to allow patch updates.
• Medium · Babel Build Tools Security — package.json - devDependencies (@babel/cli, @babel/core, @babel/preset-env, @babel/preset-flow). The project uses Babel CLI and core version ^7.20.0 from 2022. While not critical, these are dev dependencies used during the build process and should be kept current. Outdated build tools can introduce supply chain risks through compromised dependencies. Fix: Update all Babel dependencies to the latest version (currently 7.23.x or newer). Run 'npm audit' to identify and patch vulnerabilities in the build toolchain.
• Medium · Yargs Dependency Known Vulnerability — package.json - dependencies.yargs. yargs version ^17.6.2 is from late 2022 and may contain known vulnerabilities related to command injection or argument parsing issues that were discovered in this version range. Fix: Update yargs to version ^17.7.2 or latest 18.x. Run 'npm audit' to verify the specific vulnerability has been patched. Test the msggen CLI tool after upgrade to ensure compatibility.
• Medium · Missing Security Headers in CI/CD Configuration — .github/workflows/. GitHub Actions workflows in .github/workflows directory may lack security best practices such as permission scoping, dependency pinning, and secret masking. The publish.yml workflow is particularly sensitive. Fix: Audit all GitHub Actions workflows for: (1) Principle of least privilege in YAML permissions, (2) Use of pinned action versions with commit SHAs instead of tags, (3) Proper secret masking, (4) Dependency review before publishing.
• Medium · Node Engine Version Requirement Too Permissive — package.json - engines.node. The package specifies engines.node as '>=18', which allows any version 18 and above. This is too permissive and could allow execution on vulnerable EOL Node versions if version constraints are accidentally removed upstream. Fix: Specify a more specific version range such as '>=18.16.0 <21' or use a maintenance LTS version window like '>=18.17.0' to ensure security patches are included.
• Low · Jest Configuration Could Expose Source Maps — package.json - jest.transform, scripts.build. The Jest configuration uses Babel transformer which generates source maps (--source-maps flag in build script). Source maps in production can expose original source code and sensitive logic. Fix: Ensure source maps are not shipped in production builds. Configure separate build configurations for development (with source maps) and production (without). Add '.map' files to .gitignore and build artifact exclusions.
• Low · Missing License Verification for Dependencies — package.json and repository configuration. No license scanning or compliance verification process is evident in the configuration. This could lead to including dependencies with incompatible licenses (e.g., GPL) or unmaintained projects. Fix: Implement license scanning using tools like 'license-checker' or 'fossa'. Add pre-commit hooks to verify all dependencies have compatible licenses (MIT, Apache 2.0, BSD family).
• Low · No Dependency Lock File Security Practices Documented — .circleci/config.yml and .github/workflows/. While package.json is visible, no mention of package-lock.json or yarn.lock security practices is evident. The .circleci and CI/CD configurations should enforce lock file integrity checks. Fix: Ensure CI/CD pipelines use 'npm ci' instead of 'npm install'. Verify lock file integrity in CI before building. Regularly audit and update lock files on a scheduled basis

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.