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/SerenityOS/serenity 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.

GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• BSD-2-Clause licensed
• CI configured
• Tests present

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

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

What it runs against: a local clone of SerenityOS/serenity — 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 SerenityOS/serenity | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | Catches relicense before you depend on it | | 3 | Default branch master 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 |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of SerenityOS/serenity. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/SerenityOS/serenity.git
#   cd serenity
#
# 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 SerenityOS/serenity and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "AK/ByteString.h" \\
  && ok "AK/ByteString.h" \\
  || miss "missing critical file: AK/ByteString.h"
test -f "AK/Vector.h" \\
  && ok "AK/Vector.h" \\
  || miss "missing critical file: AK/Vector.h"
test -f "AK/Error.h" \\
  && ok "AK/Error.h" \\
  || miss "missing critical file: AK/Error.h"
test -f "AK/RefCounted.h" \\
  && ok "AK/RefCounted.h" \\
  || miss "missing critical file: AK/RefCounted.h"
test -f ".gn" \\
  && ok ".gn" \\
  || miss "missing critical file: .gn"

# 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/SerenityOS/serenity"
  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).

SerenityOS is a complete, from-scratch Unix-like operating system for 64-bit x86, ARM, and RISC-V written in C++ with a custom kernel, POSIX-compatible userland, and a modern web browser (with JavaScript JIT, WebAssembly, and CSS engine). It solves the problem of creating a cohesive, aesthetically unified OS that prioritizes developer experience and security while maintaining late-1990s UI sensibilities. Monorepo organized as: Kernel/ (core OS), Userland/Applications/ (GUI apps like Browser, HackStudio), Userland/Libraries/ (LibC, LibJS, LibGUI, LibWeb), Userland/Services/ (WindowServer, AudioServer, RequestServer daemons), and AK/ (container/utility library shared across all components). Meta/ contains build scripts and documentation.

Operating systems enthusiasts, kernel developers, and compiler/systems engineers who want to understand modern OS design from first principles; contributors interested in building browser engines, Unix utilities, or desktop GUIs without corporate constraints. Also hobbyists who enjoy studying a complete, runnable educational OS.

Actively developed with substantial implementation: 47MB+ of C++, 2+ MB JavaScript (for LibJS engine), established CI/CD via GitHub Actions, comprehensive clang-tidy and clang-format configs, and frequent commits visible in the main branch. It is a serious, non-toy project that boots and runs real applications, but remains in active development with known missing POSIX features rather than production-grade.

Single-project maintenance model (not a distributed team) means contributor availability fluctuates; breaking changes in the kernel/ABI can cascade across userland components with limited deprecation cycles. No visible dependency management (builds are largely from scratch), reducing external risk but increasing the maintenance burden for the maintainers and requiring deep systems knowledge from contributors.

Active development across multiple areas: browser rendering and JavaScript compliance (test262 suite tracking visible), security hardening (W^X, ASLR, pledge/unveil), POSIX compatibility expansion, and ARM/RISC-V port work. GitHub Actions CI validates each commit; no specific release cycle apparent but steady weekly progress.

git clone https://github.com/SerenityOS/serenity.git
cd serenity
# Install build dependencies (Ubuntu/Debian): sudo apt install build-essential cmake ninja-build git
Meta/serenity.sh build
Meta/serenity.sh run

The Meta/serenity.sh script handles toolchain setup, cross-compilation, and emulation.

Daily commands: After building: Meta/serenity.sh run launches QEMU with the generated disk image. Boots to login screen; default credentials typically user/password. For faster iteration: Meta/serenity.sh run-gdb attaches debugger, or Meta/serenity.sh rebuild-toolchain && Meta/serenity.sh build for incremental changes.

• AK/ByteString.h — Core string type used throughout SerenityOS; understanding this is essential for text handling in kernel and userspace
• AK/Vector.h — Primary dynamic array container used pervasively across the codebase; foundational to memory management patterns
• AK/Error.h — Error handling abstraction (likely Error/Optional types); critical for understanding control flow and failure modes
• AK/RefCounted.h — Reference counting mechanism for lifetime management; essential for understanding object ownership in SerenityOS
• .gn — GN build configuration entry point; required to understand how the entire OS is compiled and linked
• AK/CMakeLists.txt — Build configuration for the AK (AngelKit) library; defines compilation flags and dependencies for core abstractions
• .github/workflows/ci.yml — Continuous integration pipeline; shows how code is tested and validated before merge

Add a new container data structure to AK

1. Create a new header in AK/ following naming convention (e.g., AK/MyContainer.h) (AK/MyContainer.h)
2. Implement the container using existing AK patterns (inherit from or compose Vector, support move semantics) (AK/MyContainer.h)
3. Update AK/CMakeLists.txt to include the new header if it needs compilation (most AK types are header-only) (AK/CMakeLists.txt)
4. Add unit tests following the codebase convention in Tests/ (not shown in list, but referenced by CI) (.github/workflows/ci.yml)

Add a new encoding or format utility

1. Create encoder/decoder header in AK/ (e.g., AK/MyFormat.h) (AK/MyFormat.h)
2. Use existing string and buffer types (ByteString, ByteBuffer) for input/output (AK/ByteString.h)
3. Use error handling from AK/Error.h for invalid input conditions (AK/Error.h)
4. Run CI pipeline to validate against all supported platforms (x86, ARM, RISC-V) (.github/workflows/ci.yml)

Add a new stream type or I/O abstraction

1. Create new stream class in AK/MyStream.h inheriting from or composing existing stream types (AK/MyStream.h)
2. Implement read/write operations using ByteBuffer and error handling (AK/ByteBuffer.h)
3. Optionally add both .h and .cpp if buffering or complex state is needed (AK/ConstrainedStream.cpp)
4. Ensure thread safety if the stream will be used in multi-threaded contexts (consider AtomicRefCounted) (AK/AtomicRefCounted.h)

Extend numeric or math utilities

1. Add new math types or functions to AK/FixedPoint.h or AK/Complex.h (AK/FixedPoint.h)
2. Use Checked<T> for operations that could overflow to catch errors at compile/runtime (AK/Checked.h)
3. Test across 64-bit x86, ARM, and RISC-V via CI to ensure portable implementation (.github/workflows/ci.yml)

• C++17 — Modern language features for safe abstractions without garbage collection; suitable for low-level OS code
• GN Build System — Fast, scalable build for large projects; used by Chromium; enables easy cross-platform compilation (x86, ARM, RISC-V)
• Clang/GCC — Industry-standard compilers with excellent C++ support and platform portability
• GitHub Actions CI — Integrated workflow automation for testing across platforms and enforcing code quality before merge
• AK (AngelKit) container library — Custom, zero-dependency containers avoiding C++ STL; enables fine-grained control over allocation and behavior

• Custom AK library instead of STL

  • Why: SerenityOS is a from-scratch OS; STL may have dependencies or behaviors unsuitable for a bare-metal/kernel context
  • Consequence: More code to maintain, but complete control over semantics, allocation, and binary size

• No exceptions (Error type instead)

  • Why: Exceptions have runtime overhead; in kernel/low-level code, returning Result<T> is more predictable
  • Consequence: Explicit error handling everywhere, but fewer surprises in resource cleanup

• Multi-platform support (x86, ARM, RISC-V)

  • Why: Demonstrate portability; appeal to broader hardware audience
  • Consequence: Complex CI matrix; more testing required; occasional platform-specific code

• Header-only containers

  • Why: Avoid separate .cpp files for template code; faster compilation in simple cases
  • Consequence: Longer compilation times for large projects; code bloat if not careful with inlining

• Not a production-grade OS for mission-critical systems; it is a hobby/educational project
• Does not aim to match Linux kernel feature parity; prioritizes simplicity and '90s UX aesthetic
• Not designed for real-

Toolchain complexity: The build generates a cross-compilation toolchain on first run (binutils, GCC, or Clang targeting SerenityOS); this can take 30+ minutes on slow systems and requires ~5GB disk space. Syscall ABI stability: The kernel/userland syscall interface is NOT stable between commits; always rebuild both kernel and userland together. QEMU-specific: The emulation assumes QEMU; hardware differences on bare metal may cause driver/timing issues. No package manager yet: All userland is statically compiled; no dynamic linking (by design), making binary size larger but simplifying deployment.

• Intrusive containers (IntrusiveList, IntrusiveRedBlackTree) — SerenityOS avoids heap fragmentation and improves cache locality by embedding list/tree nodes directly in parent structures (AK/IntrusiveList.h); essential pattern for kernel memory efficiency.
• W^X (Write XOR Execute) memory protection — SerenityOS enforces that memory pages are either writable OR executable but never both; critical mitigation against code injection attacks visible in Kernel/Memory/ paging code.
• pledge() and unveil() syscalls — SerenityOS's process capability restriction system (inspired by OpenBSD) limits what a process can do post-startup; unique security design visible in Kernel/Syscalls/ and used throughout userland apps.
• Pre-emptive multithreading with round-robin scheduling — SerenityOS kernel enforces time-sliced task switching without requiring cooperative yields; core to responsiveness, implemented in Kernel/Process.cpp and Kernel/Scheduler.cpp.
• ASLR (Address Space Layout Randomization) — Kernel randomizes virtual address layout of processes on each execution; visible in Kernel/Memory/VMAllocator.cpp; hardens against return-oriented programming (ROP) exploits.
• Syscall table dispatching with ABI versioning — SerenityOS routes userland syscalls through a flat syscall number table; understanding this boundary (Kernel/Syscalls/index.html generated from syscall definitions) is essential for kernel/userland debugging.
• Custom JavaScript JIT compilation and inline caching — LibJS (Userland/Libraries/LibJS/) implements a hand-written JIT with inline caching for property access; not V8, but demonstrates modern JS compilation techniques on a hobby OS.

• torvalds/linux — Inspiration and reference implementation for POSIX syscalls, kernel architecture, and filesystem design that SerenityOS emulates selectively.
• apple/darwin-xnu — Alternative Unix kernel design with similar security features (pledge-like Sandbox/entitlements, W^X); referenced in SerenityOS security hardening.
• jynx-os/jynx — Another hobby OS written in modern C++ with emphasis on clean architecture; peer project for design comparison.
• WebKit/WebKit — Production browser engine that LibWeb/LibJS studies for HTML/CSS/JS spec compliance; SerenityOS tracks WebKit's test262 performance.
• SerenityOS/libjs-website — Separate repo tracking SerenityOS's JavaScript and WebAssembly spec compliance via live test262 results dashboards.

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 AK utility library core data structures

The AK directory contains critical utility classes (ByteString, ByteBuffer, Vector, HashMap, etc.) but the repo structure shows no corresponding test files in AK/. SerenityOS is a systems project where data structure correctness is critical. Adding tests for edge cases in AK/ByteString.cpp, AK/Array.h, AK/BinarySearch.h, and AK/Bitmap.h would catch regressions early and serve as documentation for expected behavior.

• [ ] Create AK/Tests/ directory structure mirroring AK/ layout
• [ ] Add unit tests for AK/ByteString.cpp covering UTF-8 edge cases, bounds, and mutations
• [ ] Add tests for AK/BinarySearch.h with various input types and empty/single-element cases
• [ ] Add tests for AK/Bitmap.h and AK/BitmapView.h for bit manipulation correctness
• [ ] Integrate tests into existing CI via .github/workflows/ci.yml if not already present

Add GitHub Actions workflow for clang-tidy compliance verification

The repo has .clang-tidy and AK/.clang-tidy configuration files present, indicating code quality standards are defined, but there's no dedicated workflow in .github/workflows/ to enforce these checks on PRs. This would prevent regressions in code style and catch common issues before merge. Similar to existing ci.yml, this would validate all changed files.

• [ ] Create .github/workflows/clang-tidy.yml following the pattern of existing workflows
• [ ] Configure the workflow to run clang-tidy on changed files using the .clang-tidy config
• [ ] Set up the workflow to post results as PR comments for developer feedback
• [ ] Add clang-tidy dependency installation (likely via existing .github/actions/setup/action.yml)
• [ ] Ensure the workflow runs on pull_request events and reports pass/fail status

Document AK utility API with missing JSDoc-style header comments

AK is the foundational utility library used throughout SerenityOS, but critical headers like AK/Array.h, AK/Badge.h, AK/Checked.h, and AK/BitStream.h lack comprehensive API documentation comments. New contributors struggle to understand when to use each utility. Adding detailed comments with usage examples would improve onboarding and code clarity without changing logic.

• [ ] Add structured comments to AK/Array.h documenting template parameters, methods, and common patterns
• [ ] Document AK/Badge.h pattern explanation (friend-only access) with code examples
• [ ] Add comments to AK/Checked.h explaining overflow detection and when to use vs standard types
• [ ] Document AK/BinaryHeap.h, AK/COWVector.h, and AK/AsyncStream.h with usage examples
• [ ] Verify comments follow SerenityOS style (check against existing documented files like AK/ByteString.h)

• Add missing POSIX syscall wrappers in Userland/Libraries/LibC/ (e.g., getrandom(), eventfd()): grep the Kernel/Arch for implemented syscalls, then wrap them in LibC/sys/ with tests in Tests/LibC/.
• Improve CSS spec compliance in Userland/Libraries/LibWeb/CSS/: Study a failing test262-css case, implement the missing property handler in StyleComputer.cpp, add a test case to Tests/LibWeb/CSS/. The CSS state is tracked publicly on css.tobyase.de.
• Port Userland/Utilities/{simple_tool} from Linux to SerenityOS: Pick an unimplemented but straightforward Unix utility (like env or printf), write it using SerenityOS's AK containers and LibCore, add manual page to Userland/Man/man{1,2}/. No complex fork/exec required for starters.

SerenityOS shows generally good security practices with compilation tooling configurations (.clang-tidy, .clang-format), CI/CD automation, and use of safer container abstractions (Checked<>, Array wrappers). However, several low-severity concerns exist: missing security policy documentation, potential arithmetic overflow risks, and base64/binary parsing that requires hardening against malformed inputs. No hardcoded secrets or critical misconfigurations detected. The project would benefit from establishing a formal security policy, increasing fuzzing coverage for parsers, and migrating away from deprecated APIs. The modern C++ practices and build system safeguards provide a reasonable foundation for security.

• Low · Potential Insecure Deserialization in ByteReader/ByteBuffer — AK/ByteReader.h, AK/ByteBuffer.h. The AK library contains ByteReader and ByteBuffer classes that handle raw binary data deserialization. Without explicit validation of input bounds and types, these could be vulnerable to malformed input attacks. Fix: Implement strict bounds checking and type validation in deserialization routines. Add fuzzing tests to verify robustness against malformed inputs.
• Low · Missing SECURITY.md or Security Policy — Repository root. No visible security policy or responsible disclosure guidelines (SECURITY.md) in the repository. This makes it unclear how security researchers should report vulnerabilities. Fix: Create a SECURITY.md file documenting responsible disclosure procedures and security contact information.
• Low · Potential Integer Overflow in Arithmetic Operations — AK/Complex.h, AK/BigIntBase.h. Files like AK/Checked.h suggest overflow protection exists, but unchecked arithmetic in AK/Complex.h and other mathematical operations could lead to integer overflows if not properly validated. Fix: Ensure all arithmetic operations use the Checked<> wrapper or explicitly validate operands for overflow conditions. Add comprehensive unit tests for edge cases.
• Low · Base64 Encoding/Decoding Input Validation — AK/Base64.cpp, AK/Base64.h. AK/Base64.cpp handles base64 encoding/decoding which could be vulnerable if input validation is insufficient, potentially leading to buffer overflows or incorrect decoding. Fix: Verify strict input validation and bounds checking in base64 codec. Add fuzzing for malformed base64 inputs.
• Low · Potential Use of Deprecated or Unsafe Patterns — AK/DeprecatedFlyString.cpp. The presence of DeprecatedFlyString suggests legacy code patterns that may contain security vulnerabilities. Deprecated APIs often have known issues. Fix: Migrate away from deprecated APIs. Audit deprecated code for known security issues and update to safer alternatives.

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

• 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.