SimpleKernel: Writing an OS Kernel with AI as the Implementer

The Learning Problem SimpleKernel Addresses

Most OS teaching projects present a complete codebase for a learner to read and modify. The friction is well known: you open a file in xv6 or similar and immediately face hundreds of lines of tightly coupled C, with no clear entry point for understanding a single subsystem in isolation. Modifying one module often breaks another, and the feedback loop is long.

SimpleKernel proposes a different structure. The project's primary artifacts are interface definitions, not implementations. Every subsystem is described in a header file that carries full Doxygen annotations: the class's responsibility, preconditions, postconditions, known implementing classes, and usage examples. The matching .cpp implementations are either supplied as reference code or expected to come from the learner with AI assistance.

The README states the intended learning path explicitly: read the interface, understand the contract, ask an AI tool to generate the .cpp, then run the GoogleTest suite to check whether the output satisfies the specification. If the tests fail, the reference implementation is there for comparison.

The project targets students and self-taught developers who already have access to a code-completion assistant and who want to understand OS subsystem design at the contract level before diving into implementation details.

How Interface Contracts Replace the Usual Starting Point

Each module in SimpleKernel is organized around a header file that declares pure virtual classes with detailed Doxygen comments. The interrupt subsystem, for example, exposes a class called InterruptBase with two pure virtual methods: Do, which handles a trap given a cause code and a TrapContext pointer, and RegisterInterruptFunc, which registers a handler for a given cause code. The Doxygen block documents what must be true before calling the class (the hardware interrupt controller must be initialized) and what holds afterward (interrupt functions can be registered).

The README shows this interface:

class InterruptBase {
public:
  virtual ~InterruptBase() = default;
  virtual void Do(uint64_t cause, cpu_io::TrapContext* context) = 0;
  virtual void RegisterInterruptFunc(uint64_t cause, InterruptFunc func) = 0;
};

The Doxygen comment in the full header is what the learner pastes into a code assistant as context. The AI then fills in the concrete implementation for the target architecture, for instance a PLIC-based handler for RISC-V 64 or a GICv3-based one for AArch64. The same interface declaration covers both hardware targets; only the .cpp files differ.

The interface hierarchy covers four layers: the architecture entry point in src/arch/arch.h, interrupt and exception handling in interrupt_base.h, memory management in virtual_memory.hpp, and task management through scheduler_base.hpp and mutex.hpp. Several components, including spinlock.hpp and the device manager, are header-only because the design requires inline performance or because the implementation is simple enough to keep in the header.

Setting Up the Dev Container and Running the First Build

The recommended path uses a Dev Container that bundles GCC 14 cross-compilers, CMake, and QEMU, so no local toolchain setup is required. You need Docker and either VS Code with the Dev Containers extension or the devcontainer CLI.

Clone the repository and open the container:

git clone https://github.com/simple-xx/SimpleKernel.git
cd SimpleKernel
npm install -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

Once inside the container, build and run the RISC-V 64 target:

cmake --preset build_riscv64
cd build_riscv64
make SimpleKernel
make run

The make run target launches QEMU with the compiled kernel image. After that, run the unit tests to check any implementation you have written or generated:

make unit-test

The AArch64 target follows the same pattern with the preset name changed to build_aarch64. The build uses CMakePresets.json at the repository root to define all configuration options, so switching between architectures does not require editing any CMake files directly.

Where the Interface-Driven Model Has Limits

The approach depends on the quality of the interface documentation. When a Doxygen comment is thin, for example, when postconditions are missing or the interaction between two subsystems is not spelled out, the AI-generated code may compile and even pass shallow tests while missing edge cases that only appear at runtime inside QEMU.

The README notes that the full interface refactor is still ongoing. A file named docs/TODO_interface_refactor.md tracks which modules have been ported to the new interface-driven style and which are still in progress. A learner who opens a module that has not yet been refactored will find mixed-style code that does not fit the clean read-interface-then-implement flow.

C++23 is a strict requirement. The toolchain bundled in the Dev Container handles this, but a learner who wants to work outside Docker must install GCC 14 or a clang equivalent that supports the C++23 features the project uses. The repository has no published binary releases, so there is no prebuilt kernel to run as a reference baseline.

The project is not a runtime for applications. There is no user-space layer and no system call table for running programs. It is purely a kernel-level learning environment for understanding how interrupt handling, memory management, task scheduling, and device drivers are structured in a 64-bit bare-metal kernel.

How SimpleKernel Differs from xv6

xv6 is the MIT teaching OS that ships with a fully functional implementation covering a Unix-like system call interface, a page-table virtual memory system, and a simple process scheduler, all in plain C. Learners read the source and the accompanying textbook, then modify components to understand their behavior.

SimpleKernel takes the opposite position: the interface definition is the artifact you study, not a completed implementation. xv6 does not expose a GoogleTest suite that validates student-written replacements; you learn by reading the reference code and observing behavior changes. SimpleKernel asks you to write or generate the implementation first and checks correctness automatically.

The two projects cover different hardware. xv6 targets RISC-V in its current form and the teaching value is tied to reading the complete source. SimpleKernel targets RISC-V 64 and AArch64 and the value is in understanding subsystem contracts before looking at implementation details. A learner who wants to study a complete, working OS kernel should read xv6. A learner who wants to practice defining and satisfying OS subsystem contracts with AI tools should look at SimpleKernel.

Architecture Support, Repository Health, and License

SimpleKernel supports two hardware architectures. RISC-V 64 uses U-Boot plus OpenSBI as the boot chain, SBI Call for the serial interface, and SBI Timer for clock management. AArch64 uses U-Boot plus ATF plus OP-TEE, PL011 for the serial port, GICv3 as the interrupt controller, and the Generic Timer for clocking.

The last push to the repository was on March 20, 2026. The repository is not archived. The CI/CD infrastructure, clang-format, and clang-tidy configurations are all present, which shows the project was structured for ongoing maintenance, but the gap since the last push means you should check the open issues page before starting a new module.

The repository carries a LICENSE file, but the metadata identifier shows NOASSERTION. The README displays a badge linking to the 996.ICU anti-996 license project, which is a statement of labor norms rather than a software license with usage terms. The actual terms of redistribution are not clear from the metadata alone; read the LICENSE file in the repository directly before integrating any code.

Editorial conclusion

SimpleKernel is worth trying if you want to learn OS subsystem design by generating and testing AI-written code against well-specified contracts on RISC-V 64 or AArch64. It is not appropriate for teams who need a production OS framework or for learners who want to read a complete, working implementation from the start. Before spending time with it, check docs/TODO_interface_refactor.md to see which interfaces have been finalized, since the interface refactor was still in progress as of the last push on March 20, 2026.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Simple-XX/SimpleKernel on GitHub