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/theseus-os/Theseus 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 all four use cases

• 10 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{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 theseus-os/Theseus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/theseus-os/Theseus.

What it runs against: a local clone of theseus-os/Theseus — 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 theseus-os/Theseus | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch theseus_main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 622 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "theseus-os/Theseus(\\.git)?\\b" \\
  && ok "origin remote is theseus-os/Theseus" \\
  || miss "origin remote is not theseus-os/Theseus (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 theseus_main >/dev/null 2>&1 \\
  && ok "default branch theseus_main exists" \\
  || miss "default branch theseus_main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "theseus_features/Cargo.toml" \\
  && ok "theseus_features/Cargo.toml" \\
  || miss "missing critical file: theseus_features/Cargo.toml"
test -f "kernel" \\
  && ok "kernel" \\
  || miss "missing critical file: kernel"
test -f "applications" \\
  && ok "applications" \\
  || miss "missing critical file: applications"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 622 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~592d)"
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/theseus-os/Theseus"
  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).

Theseus is a modern operating system written entirely in Rust from scratch that implements intralingual design principles—using the compiler and Rust's affine type system to enforce OS-level resource management at compile time rather than runtime. It shifts traditional OS responsibilities like memory safety, ownership tracking, and resource cleanup into the language itself, eliminating entire categories of kernel bugs and enabling new forms of fault recovery and live evolution. Monorepo structure: kernel/nano_core is the bootloader/minimal core; kernel/[other crates]/ implements subsystems (memory, scheduling, filesystems, etc.); applications/[crate]/ contains user-space programs (hello, cat, bm, etc.). The workspace uses glob patterns (kernel/[!.]/, applications/[!.]/) to auto-include crates. Build is orchestrated via Makefile with Cargo as the underlying build system. theseus_features manages global feature flags across all crates.

OS researchers, systems engineers, and embedded systems developers exploring novel OS architectures that leverage modern language safety guarantees. Contributors are academic researchers and engineers interested in moving kernel logic into compiler-enforced constraints rather than runtime checks.

Actively developed but experimental. The repo shows regular CI/CD setup (GitHub Actions for build, clippy linting, QEMU testing), well-organized monorepo structure with kernel/ and applications/ crates, and published academic papers describing the design. However, the README explicitly states 'not yet mature' and positions it for 'high-end embedded systems or edge datacenter environments' rather than general-purpose use. This is cutting-edge research infrastructure, not production-ready.

Moderate research risk: the intralingual design paradigm is novel and not battle-tested at scale; the codebase relies heavily on unstable Rust features (compiler plugins in compiler_plugins/ directory); submodule dependencies (libs/, ports/, tlibc/) are excluded from workspace, creating potential version management complexity. The project depends on a specific Rust toolchain with custom features defined in theseus_features/. No indication of security audit or formal verification despite OS-critical code.

Based on file structure, active work includes: performance evaluation (heap_eval/, channel_eval/ applications with benchmarking), core OS functionality (nano_core kernel crate), and utility applications (cat, cd, date, deps). GitHub Actions workflows show continuous integration on docs, clippy linting, and QEMU-based testing. The repo is under active development with focus on improving fault recovery and live evolution capabilities per the README.

On Ubuntu/Debian: (1) git clone --recurse-submodules --depth 1 https://github.com/theseus-os/Theseus.git && cd Theseus (2) curl https://sh.rustup.rs -sSf | sh (3) sudo apt-get install make gcc nasm pkg-config grub-pc-bin mtools xorriso qemu qemu-kvm wget (4) make run to build and boot in QEMU (exit with Ctrl+A then X).

Daily commands: Execute make run in the repository root. This invokes the Makefile which compiles the workspace (defaulting to kernel/nano_core for minimal boot) and launches QEMU. For alternative builds: cargo build --workspace builds all members; cargo build --package kernel/nano_core builds just the kernel core.

• Cargo.toml — Workspace root configuration defining all kernel and application crates; essential for understanding the modular architecture and feature flags that drive Theseus's intralingual design.
• theseus_features/Cargo.toml — Global Cargo features configuration that enables intralingual design across the entire OS by allowing compile-time language-safety guarantees to propagate from compiler to hardware.
• kernel — Core kernel crates directory containing the OS implementation leveraging Rust's affine types and safety guarantees for resource management.
• applications — User-space applications directory demonstrating the Theseus kernel API and showing how applications benefit from compile-time resource safety.
• Makefile — Build orchestration file controlling the compilation pipeline for the entire Theseus OS from source to bootable image.
• README.md — Project overview explaining the intralingual design philosophy, novel OS structure, and links to documentation essential for all contributors.
• .github/workflows/test.yaml — QEMU test automation pipeline validating OS correctness and preventing regressions in the affine-type-based resource management system.

• Kernel Core (memory, scheduling, IPC) (Rust, affine types, type system) — Manages system resources and task execution using affine types to guarantee memory safety and exclusive resource ownership at compile-time.
  • Failure mode: Compile-time rejection of unsafe resource patterns; no runtime crashes due to use-after-free or data races
• Task Scheduler (Rust, synchronization primitives (mutexes, channels)) — Coordinates execution of multiple user applications with type-safe synchronization and IPC primitives.
  • Failure mode: Deadlock detection or type-system enforcement of deadlock-free code at compile-time
• Memory Manager (Rust, linear types, lifetime tracking) — Allocates, tracks, and deallocates memory with affine-type guarantees of exclusive ownership.
  • Failure mode: Compile-time rejection of multiple simultaneous borrows or use-after-free; zero runtime overhead
• User Applications (shell, utilities, benchmarks) (Rust, library crates, kernel APIs) — Demonstrate kernel APIs and system capabilities; include shell (hull), filesystem utilities (cat, ls, mkdir), and performance evaluation tools.
  • Failure mode: Compile-time rejection of invalid resource usage; applications cannot crash the kernel

• `` → undefined — undefined

Add a New System Application

1. Create a new application directory under applications/ with the naming convention matching existing apps (e.g., applications/myapp/) (applications/example/Cargo.toml)
2. Define the application as a library crate in Cargo.toml with appropriate dependencies on kernel crates (applications/example/Cargo.toml)
3. Implement the application entry point in src/lib.rs, leveraging the kernel's type-safe APIs for task management, IPC, and filesystem access (applications/example/src/lib.rs)
4. The application will be automatically built by the workspace via the 'applications/[!.]*/' glob pattern in the root Cargo.toml

Enable Compile-Time OS Semantics with Features

1. Define a new feature flag in theseus_features/Cargo.toml that controls OS-level behavior (e.g., memory isolation, scheduler policy) (theseus_features/Cargo.toml)
2. Reference the feature in kernel crate Cargo.tomls using the theseus_features dependency and conditional compilation directives (kernel)
3. Use #[cfg(feature = "...")] in kernel modules to enable/disable intralingual type-system optimizations that reduce runtime overhead

Add a Shell Builtin Command

1. Implement a new command function in applications/hull/src/builtin.rs following the existing pattern for commands like 'cd' and 'kill' (applications/hull/src/builtin.rs)
2. Register the command in the builtin dispatcher and handle error cases consistent with the error handling strategy in applications/hull/src/error.rs (applications/hull/src/error.rs)
3. The hull shell will parse and dispatch the command via the wrapper layer (applications/hull/src/wrapper.rs) which manages job control and process lifecycle

Integrate a New Benchmarking Tool

1. Create a new application directory under applications/ (e.g., applications/my_benchmark/) modeled after applications/heap_eval/ (applications/heap_eval/src/lib.rs)
2. Implement benchmark logic leveraging kernel performance monitoring APIs and measuring latency/throughput using Theseus's affine-type guarantees (applications/heap_eval/src/shbench.rs)
3. Add QEMU test integration to .github/workflows/test.yaml to automate benchmark runs and track performance regressions

• Rust with affine types (linear types) — Closes semantic gap between compiler and hardware by shifting resource management responsibility to compile-time; eliminates garbage collection overhead and enables deterministic behavior.
• Workspace-based modular crates — Enables independent development of kernel subsystems and applications while sharing type-safety guarantees across boundaries; facilitates incremental compilation.
• Cargo features for compile-time configuration — Allows intralingual semantics—OS behavior is determined by language-level type constraints, not runtime checks—enabling zero-cost abstractions.
• QEMU for automated testing — Provides deterministic, reproducible testing environment for verifying the correctness of affine-type-based resource guarantees without hardware dependencies.

• Exclusively Rust, no C/assembly except bootloader

  • Why: Maximizes compiler-enforced safety and enables type-driven resource management across the entire OS.
  • Consequence: Steeper learning curve for contributors unfamiliar with Rust's ownership model; limits reuse of legacy OS code.

• Applications are library crates, not separate binaries

  • Why: Reduces duplication and allows kernel crates to optimize based on static knowledge of application requirements.
  • Consequence: Less isolation between apps at compile-time; all apps must be statically linked into the kernel image.

• Affine types as primary abstraction for resource management

  • Why: Eliminates reference counting and garbage collection at runtime, reducing non-determinism and overhead.
  • Consequence: Developers must think in terms of resource ownership and borrowing; no shared mutable state without explicit synchronization primitives.

• POSIX compatibility—Theseus has its own OS API optimized for type-safety, not POSIX
• Support for legacy C binaries or ABIs
• Dynamic linking or runtime module loading after boot
• General-purpose production OS (experimental research platform)

Submodule management: libs/, ports/, tlibc/, libtheseus are excluded from workspace but may be pulled in as transitive dependencies; submodules must be initialized with git submodule update --init --recursive. Rust toolchain: Theseus requires a specific Rust version and nightly features (evidence: compiler_plugins/ directory suggests unstable features); if clippy or build fails, check rustup override in the repo. Feature flags: theseus_features must be included in every workspace build; building individual crates may fail if global features aren't propagated. QEMU interaction: exit sequence is Ctrl+A then X (non-standard; documented in README but easy to forget). No prebuilt binaries: the build process creates a bootable ISO via grub-pc-bin/mtools/xorriso; missing these will fail silently or with cryptic errors.

• [Intralingual Design](https://theseus-os.com/ (blog articles on intralingual design) or published papers linked in the README) — This is Theseus's core innovation: encoding OS-level resource management (memory safety, ownership, scheduling constraints) into the programming language's type system rather than enforcing them at runtime. Understanding this principle is essential to grasp why Theseus is structured the way it is.
• Affine Types (Linear Types) — Rust's affine type system (values can be used at most once) is the foundation for Theseus's compile-time resource tracking. Every kernel resource (memory regions, file handles, task tokens) leverages this to guarantee no use-after-free or double-free without runtime checks.
• [Compiler Plugins / Procedural Macros](https://docs.rust-embedded.org/ and https://doc.rust-lang.org/reference/procedural-macros.html) — Theseus uses custom compiler plugins (in compiler_plugins/) to extend Rust's syntax and type checking for OS-specific constraints (e.g., enforcing that certain kernel functions only run at specific privilege levels). These are critical to implementing intralingual design.
• Live Evolution / Hot Code Reload — Per the README, Theseus aims to enable 'arbitrary live evolution' (updating OS code without reboot). This is enabled by compiler-enforced resource ownership ensuring updated code won't deadlock or corrupt state.
• Microkernel vs. Monolithic Kernel Architecture — Understanding whether Theseus leans toward microkernel (small privileged core, services in userspace) or monolithic (everything in one protection domain) design informs where to add new subsystems. Intralingual design may enable a hybrid approach.
• Workspace Glob Patterns in Cargo — Theseus uses glob patterns like kernel/[!.]*/ to automatically include all crates in a directory. This is unconventional and critical to understand when adding new kernel subsystems or applications—follow the pattern or update Cargo.toml.
• [Fault Recovery & Resilience Without Redundancy](https://theseus-os.com/ or academic papers section in the README) — Per the README, a goal is 'fault recovery abilities for higher system availability without redundancy'. This is enabled by the compiler proving resource invariants statically, allowing the OS to recover from faults more aggressively than traditional systems.

• redox-os/redox — Alternative Rust OS with similar goals (safety via Rust) but different architecture (microkernel vs. Theseus's compiler-centric design). Primary comparison point for intralingual OS design.
• nanokernel/nanokernel — Minimal kernel research project exploring radical simplification of OS concepts; related in spirit to Theseus's philosophy of moving complexity to the compiler rather than runtime.
• torvalds/linux — The production OS benchmark. Understanding Linux's memory management and scheduling provides context for what Theseus aims to improve through compile-time guarantees.
• rust-lang/rust — The Rust compiler itself; Theseus uses compiler plugins and unstable features extensively, so tracking Rust's type system and ownership evolution is critical for Theseus maintenance.
• theseus-os/theseus-book — The official Theseus book (likely companion repo) documenting the OS design principles and intralingual architecture in detail; essential reading for understanding the 'why' behind the code.

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 hull shell application (applications/hull/)

The hull shell is a critical user-facing component with multiple modules (parse.rs, builtin.rs, job.rs, wrapper.rs, error.rs) but appears to lack dedicated unit tests. Given Theseus's focus on language safety and affine types, thorough tests would validate the shell's correctness and serve as a reference implementation for other applications. This is high-value because shell behavior directly impacts user experience.

• [ ] Create applications/hull/tests/integration_tests.rs for end-to-end shell command parsing and execution
• [ ] Add unit tests in applications/hull/src/parse.rs for the parser module (test malformed input, edge cases)
• [ ] Add unit tests in applications/hull/src/builtin.rs for builtin command implementations
• [ ] Add unit tests in applications/hull/src/job.rs for job control logic (background jobs, piping)
• [ ] Document test coverage in applications/hull/README.md (if exists) or add one

Extend CI/CD pipeline with architecture-specific build validation in .github/workflows/

The repo has check-clippy.yaml, docs.yaml, and test.yaml, but there's no explicit validation that the kernel builds for multiple target architectures (x86_64, ARM, etc.). Theseus's intraliingual design across different hardware should have CI validation to prevent architecture-specific regressions. This prevents silent failures when contributors modify low-level code.

• [ ] Create .github/workflows/build-multi-arch.yaml that builds kernel/nano_core for x86_64, aarch64, and riscv64 targets
• [ ] Add matrix strategy to test different feature combinations from theseus_features/
• [ ] Ensure the workflow runs on PR events and reports build failures prominently
• [ ] Document the new workflow in a .github/CONTRIBUTING.md file with architecture support requirements

Create missing documentation for applications/ directory structure and application development guide

The applications/ directory contains 15+ applications (hello, hull, cat, less, loadc, etc.) but there's no visible applications/README.md or development guide explaining how to create new applications, package structure, or required traits/interfaces. New contributors cannot easily understand how to contribute applications or what patterns to follow. This is specific and high-value for onboarding.

• [ ] Create applications/README.md documenting the application architecture and packaging conventions
• [ ] Document the interface between applications and kernel (e.g., required entry points, how applications access kernel services)
• [ ] Create applications/TEMPLATE/ or applications/example/README.md showing a minimal application scaffold with explanations of each required file
• [ ] Add a section in applications/README.md listing existing applications with their purpose (e.g., 'hull: interactive shell', 'cat: file viewer')
• [ ] Cross-reference from main README.md to applications/README.md for contributors wanting to add applications

• Add unit tests for applications/deps/src/lib.rs and other utilities in applications/ that lack visible test coverage in the file list. This improves confidence in userspace tooling.: Easy: applications/[name]/src/lib.rs, add #[cfg(test)] modules
• Expand documentation in kernel/nano_core/ boot sequence: the README is high-level but developers need a walkthrough of how intralingual design actually manifests in bootloader→kernel initialization. Create a doc comment guide showing the affine type enforcement at each stage.: Medium: kernel/nano_core/src/lib.rs or new doc markdown under a docs/ directory
• Implement a simple example application demonstrating intralingual resource ownership (e.g., applications/ownership_demo/) that shows how Rust's compiler prevents resource leaks at compile time. This makes the core philosophy tangible for new contributors.: Medium: Create applications/ownership_demo/ following applications/hello/ pattern

The Theseus OS codebase demonstrates a modern, well-structured Rust-based OS project with security-conscious design principles (leveraging Rust's safety guarantees and affine types for resource management). No critical vulnerabilities were identified in the provided configuration. The workspace structure appropriately segregates components and uses glob patterns to manage membership. Primary concerns are indirect: third-party dependencies in excluded directories require audit oversight, and CI/CD workflow configurations (not fully visible) should enforce strict security standards. The project's reliance on Rust and explicit separation of trusted vs. untrusted components provides a strong security foundation. Recommendations focus on complementary practices like dependency auditing, secure CI/CD configuration, and explicit documentation of the supply chain.

• Low · Workspace includes excluded third-party libraries — Cargo.toml - exclude configuration. The Cargo.toml explicitly excludes 'libs' and 'ports' directories from workspace members to allow selective dependency management. However, this approach relies on proper isolation and may lead to supply chain risks if third-party code is not regularly audited. The comments indicate third-party libs and ports are intentionally excluded but can still be pulled as dependencies. Fix: Implement a dependency audit process for third-party crates in 'libs' and 'ports'. Use cargo-audit in CI/CD pipelines to detect known vulnerabilities. Document third-party dependencies and their security posture in a DEPENDENCIES.md file.
• Low · Potential incomplete workspace configuration — Cargo.toml - members field. The Cargo.toml uses glob patterns for workspace members (kernel/[!.]/, applications/[!.]/) which excludes hidden directories but may inadvertently include unvetted crates if the directory structure is modified without careful review. Fix: Explicitly list critical kernel and application crates rather than relying solely on glob patterns. Document the rationale for any excluded crates and maintain a manifest of approved dependencies.
• Low · Limited visibility into build process security — Makefile (not provided). The Makefile exists but its content is not provided for analysis. Build scripts are common attack vectors if they contain hardcoded secrets, unsafe command execution, or insecure defaults. Fix: Review the Makefile for: (1) hardcoded credentials, (2) unsafe shell operations, (3) privilege escalation patterns, (4) arbitrary command execution from user input. Use secure build practices and container-based builds.
• Low · GitHub workflow configuration not fully provided — .github/workflows/*. Three workflow files exist (check-clippy.yaml, docs.yaml, test.yaml) but their content is not provided. GitHub Actions can introduce security risks if misconfigured (e.g., overly permissive permissions, insecure secret handling). Fix: Ensure all CI/CD workflows: (1) use least privilege for permissions, (2) pin action versions to specific commits, (3) use GitHub's OIDC token for cloud authentication instead of long-lived secrets, (4) audit third-party actions for trustworthiness, (5) scan dependencies in CI.

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.