{"owner":"tiann","repo":"KernelSU","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# KernelSU Agent Guide\n\n## Agent Quick Start\n\n- For significant features or refactors, sketch an Plan first; keep it updated as you work.\n- Use Context7 to pull library/API docs when you touch unfamiliar crates, Android APIs, or JS deps.\n- Default to `rg` for searching and keep edits ASCII unless the file already uses non-ASCII.\n- Run the component-specific checks below before handing work off; do not skip failing steps.\n- When unsure which path to take, favor minimal risk changes that keep kernel/userspace contracts intact.\n\n## Project Overview\n\nKernelSU is a kernel-based root solution for Android with a kernel module, Rust userspace daemons, a Kotlin Manager app, and docs/web assets.\n\n## Repository Structure\n\n```bash\n/kernel/                      # Kernel module - C code for Linux kernel integration\n/userspace/ksud/              # Userspace daemon - Rust binary for userspace-kernel communication\n/userspace/meta-overlayfs/    # Meta-overlay filesystem implementation - Rust binary + scripts\n/manager/                     # Android manager app - Kotlin/Jetpack Compose UI\n/website/                     # Documentation website - VitePress\n/js/                          # JavaScript library for module WebUI\n/.github/workflows/           # CI/CD workflows for building and testing\n/scripts/                     # Build automation scripts (Python)\n```\n\n## Core Concepts\n\n- **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`.\n- **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`.\n- **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`).\n- **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`).\n- **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`).\n- **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.\n\n## Component Workflows\n\n### Kernel (`kernel/`)\n\n- Kernel changes are C-only; keep interfaces aligned with supercall and allowlist expectations in userspace/Manager.\n- If you alter IOCTLs or profiles, update the corresponding wrappers in ksud (`ksucalls.rs`) and Manager JNI (`manager/app/src/main/cpp/ksu.cc`).\n\n### Userspace Rust (`userspace/ksud`, `userspace/meta-overlayfs`)\n\nFor Rust projects in `userspace/ksud` and `userspace/meta-overlayfs`, ALWAYS run these commands in sequence after making code changes:\n\n1. `cargo ndk -t arm64-v8a check` (verify compilation)\n2. `cargo ndk -t arm64-v8a clippy` (lints and warnings)\n3. `cargo fmt` (format)\n4. Fix any errors or warnings before considering the task complete.\n\n### Android Manager App (`manager/`)\n\n```bash\ncd manager\n# Must have ksud binaries first!\nmkdir -p app/src/main/jniLibs/arm64-v8a\ncp ../userspace/ksud/target/aarch64-linux-android/release/ksud app/src/main/jniLibs/arm64-v8a/libksud.so\n\n# Then build\n./gradlew clean assembleRelease\n```\n\nImportant: Manager build REQUIRES ksud binaries to be present in `jniLibs` before building.\n\n### Website (`website/`)\n\n```bash\ncd website\n# Using bun (preferred)\nbun install\nbun run docs:build  # Production build\n```\n\n### JavaScript Web UI (`js/`)\n\n- JS packages back module WebUI pieces; follow existing package manager lockfile and run the relevant lint/test scripts before publishing changes.\n\n## Common Pitfalls\n\n- Only one metamodule can be active; keep meta hooks in sync with ksud expectations.\n- Manager JNI mirrors every supercall; kernel or ksud API changes must be reflected there to avoid runtime drift.\n- Do not skip the `cargo ndk` steps; plain `cargo check` will not validate Android targets.\n- Manager builds fail if `libksud.so` is missing; create it before any Gradle command.\n\n## Git Commit\n\n- 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.\n- 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.\n- 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.\n- Before committing, glance at recent `git log --oneline` to stay consistent with current prefixes and capitalization used in this repo.\n"}}