AGENTS.md

1# KernelSU Agent Guide
2 
3## Agent Quick Start
4 
5- For significant features or refactors, sketch an Plan first; keep it updated as you work.
6- Use Context7 to pull library/API docs when you touch unfamiliar crates, Android APIs, or JS deps.
7- Default to `rg` for searching and keep edits ASCII unless the file already uses non-ASCII.
8- Run the component-specific checks below before handing work off; do not skip failing steps.
9- When unsure which path to take, favor minimal risk changes that keep kernel/userspace contracts intact.
10 
11## Project Overview
12 
13KernelSU is a kernel-based root solution for Android with a kernel module, Rust userspace daemons, a Kotlin Manager app, and docs/web assets.
14 
15## Repository Structure
16 
17```bash
18/kernel/                      # Kernel module - C code for Linux kernel integration
19/userspace/ksud/              # Userspace daemon - Rust binary for userspace-kernel communication
20/userspace/meta-overlayfs/    # Meta-overlay filesystem implementation - Rust binary + scripts
21/manager/                     # Android manager app - Kotlin/Jetpack Compose UI
22/website/                     # Documentation website - VitePress
23/js/                          # JavaScript library for module WebUI
24/.github/workflows/           # CI/CD workflows for building and testing
25/scripts/                     # Build automation scripts (Python)
26```
27 
28## Core Concepts
29 
30- **supercall**: Kernel-side IOCTL interface exposed by the `[ksu_driver]` anon-inode and installed via the reboot kprobe hook in `kernel/supercalls.c`. It maps commands like allowlist/app-profile management, feature toggles, and sepolicy changes. Rust userspace reaches it through `userspace/ksud/src/ksucalls.rs` (scans or installs the FD, wraps IOCTLs), while the Manager JNI bridge mirrors the same IOCTLs in `manager/app/src/main/cpp/ksu.cc`.
31- **module**: A flashable ZIP unpacked by `userspace/ksud/src/module.rs` into `/data/adb/modules/` (`userspace/ksud/src/defs.rs`), with lifecycle scripts (`post-fs-data.sh`, `service.sh`, etc.) executed by ksud init events (`userspace/ksud/src/init_event.rs`). The Android Manager surfaces module state from ksud in `manager/app/src/main/java/me/weishu/kernelsu/ui/viewmodel/ModuleViewModel.kt`.
32- **metamodule**: A special module marked by `metamodule=1` in `module.prop` (see `userspace/meta-overlayfs/metamodule/module.prop`). ksud enforces a single active metamodule, creates `/data/adb/metamodule -> /data/adb/modules/<id>` symlink, and delegates mounting/meta install hooks via `userspace/ksud/src/metamodule.rs`; metamodule scripts run before regular modules in `userspace/ksud/src/init_event.rs`. The Manager UI highlights metamodules and warns on uninstall (`manager/app/src/main/java/me/weishu/kernelsu/ui/screen/Module.kt`).
33- **app profile**: Per-app policy struct defined in `kernel/app_profile.h` and validated/persisted in `kernel/allowlist.c` to control root grants and non-root behavior (e.g., cumulative umount policy). supercall IOCTLs `KSU_IOCTL_GET/SET_APP_PROFILE` live in `kernel/supercalls.c` and are consumed by ksud/Manager via the JNI bridge (`manager/app/src/main/cpp/ksu.cc`) and Kotlin model `Natives.Profile` (`manager/app/src/main/java/me/weishu/kernelsu/Natives.kt`).
34- **sucompat**: Exec/FS compatibility layer that reroutes `/system/bin/su` to ksud for allowed UIDs, keeping legacy “call su to root” flows working. The hooks live in `kernel/sucompat.c` and are registered by the syscall hook manager; feature toggle `KSU_FEATURE_SU_COMPAT` is exposed through supercalls and surfaced to the Manager via `manager/app/src/main/cpp/ksu.cc` (`is_su_enabled` / `set_su_enabled`).
35- **allowlist**: Kernel-managed list of UIDs permitted for root, persisted at `/data/adb/ksu/.allowlist` with default root/non-root profiles. Core logic is in `kernel/allowlist.c` (bitmap storage, persistence, default profile caching) and is initialized from `kernel/ksu.c`; supercall handlers in `kernel/supercalls.c` expose getters, deny-list checks, and “should umount modules” decisions. Manager reads and edits it through the JNI calls in `manager/app/src/main/cpp/ksu.cc` and Kotlin `Natives` façade.
36 
37## Component Workflows
38 
39### Kernel (`kernel/`)
40 
41- Kernel changes are C-only; keep interfaces aligned with supercall and allowlist expectations in userspace/Manager.
42- If you alter IOCTLs or profiles, update the corresponding wrappers in ksud (`ksucalls.rs`) and Manager JNI (`manager/app/src/main/cpp/ksu.cc`).
43 
44### Userspace Rust (`userspace/ksud`, `userspace/meta-overlayfs`)
45 
46For Rust projects in `userspace/ksud` and `userspace/meta-overlayfs`, ALWAYS run these commands in sequence after making code changes:
47 
481. `cargo ndk -t arm64-v8a check` (verify compilation)
492. `cargo ndk -t arm64-v8a clippy` (lints and warnings)
503. `cargo fmt` (format)
514. Fix any errors or warnings before considering the task complete.
52 
53### Android Manager App (`manager/`)
54 
55```bash
56cd manager
57# Must have ksud binaries first!
58mkdir -p app/src/main/jniLibs/arm64-v8a
59cp ../userspace/ksud/target/aarch64-linux-android/release/ksud app/src/main/jniLibs/arm64-v8a/libksud.so
60 
61# Then build
62./gradlew clean assembleRelease
63```
64 
65Important: Manager build REQUIRES ksud binaries to be present in `jniLibs` before building.
66 
67### Website (`website/`)
68 
69```bash
70cd website
71# Using bun (preferred)
72bun install
73bun run docs:build  # Production build
74```
75 
76### JavaScript Web UI (`js/`)
77 
78- JS packages back module WebUI pieces; follow existing package manager lockfile and run the relevant lint/test scripts before publishing changes.
79 
80## Common Pitfalls
81 
82- Only one metamodule can be active; keep meta hooks in sync with ksud expectations.
83- Manager JNI mirrors every supercall; kernel or ksud API changes must be reflected there to avoid runtime drift.
84- Do not skip the `cargo ndk` steps; plain `cargo check` will not validate Android targets.
85- Manager builds fail if `libksud.so` is missing; create it before any Gradle command.
86 
87## Git Commit
88 
89- Mirror existing history style: `<scope>: <summary>` with a short lowercase scope tied to the touched area (e.g., `kernel`, `ksud`, `manager`, `meta-overlayfs`, `docs`, `scripts`). Keep the summary concise, sentence case, and avoid trailing period.
90- Prefer one scope; if multiple areas change, pick the primary one rather than chaining scopes. For doc-only changes use `docs:`; for multi-lang string updates use `translations:` if that matches log history.
91- Keep subject lines brief (target ≤72 chars), no body unless necessary. If referencing a PR/issue, append `(#1234)` at the end as seen in history.
92- Before committing, glance at recent `git log --oneline` to stay consistent with current prefixes and capitalization used in this repo.
93