kernel-radar 📡

An on-demand roadmap + competitor radar for the RL-Kernel project (and any GitHub roadmap issue).

One command turns a live GitHub roadmap into:

• a roadmap dashboard (HTML) — phase progress, done / in-progress / to-do / untracked gaps, a self-deriving critical path, and explicit dependency edges;
• a gap analysis — what's marked done vs. actually merged, work that landed as a PR but left its issue open, and untracked directions;
• a competitor diff — live-discovers RL-Kernel-similar projects (RLHF rollout, batch-invariant, vLLM PPO, …), tracks anchors like verl-project/vexact, and maps their releases/PRs/commits onto your themes;
• an optional document-derived plan — feed it docs and it extracts planning candidates.

It is tool-agnostic: the engine is a small stdlib-only Python program, and the installer wires it into Claude Code, Codex, opencode, and Cursor.

---

Install

Pick your tool with --target: claude, codex, opencode, cursor, or all (comma-separated for several, e.g. --target codex,cursor).

Linux / macOS / WSL — copy the line for your tool:

# Claude Code
curl -fsSL https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.sh | bash -s -- --target claude
# Codex
curl -fsSL https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.sh | bash -s -- --target codex
# opencode
curl -fsSL https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.sh | bash -s -- --target opencode
# Cursor
curl -fsSL https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.sh | bash -s -- --target cursor
# all four at once
curl -fsSL https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.sh | bash -s -- --target all

Windows PowerShell — copy the line for your tool:

iwr https://raw.githubusercontent.com/RL-Align/kernel-radar/main/install.ps1 -OutFile install.ps1
# Claude Code
.\install.ps1 --target claude
# Codex
.\install.ps1 --target codex
# opencode
.\install.ps1 --target opencode
# Cursor
.\install.ps1 --target cursor
# all four at once
.\install.ps1 --target all

From a clone (works offline, cross-platform):

git clone https://github.com/RL-Align/kernel-radar && cd kernel-radar
python3 install.py --target all      # or: --target claude,cursor

Preview the resolved paths without writing anything: python3 install.py --list.

Where things go

Part	Location
Shared engine (all tools point here)	~/.kernel-radar/engine/ (override with $KERNEL_RADAR_HOME)
Claude Code skill	~/.claude/skills/kernel-radar/SKILL.md
Codex skill	~/.codex/skills/kernel-radar/
opencode command	~/.config/opencode/command/kernel-radar.md
Cursor rule	./.cursor/rules/kernel-radar.mdc (project-scoped — see note)

Override any target dir with --claude-dir, --codex-dir, --opencode-dir, --cursor-dir.

Cursor note: Cursor rules are per-project. By default the rule lands in the current directory's .cursor/rules/. Run the installer from the repo you want it in, or pass --cursor-dir /path/to/project/.cursor/rules.

---

Use it

Step 1 — Set a GitHub token (recommended)

Without a token the tool still runs, but roadmap status degrades to checkbox-only and the competitor search hits GitHub's anonymous rate limit (60 requests/hour). With a token you get full gap reconciliation and reliable discovery.

Create a token (one time, ~1 minute):

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Repository access: Public Repositories (read-only) — that's all this tool needs; no account or private-repo permissions required.
3. Set an expiry, generate, and copy the github_pat_… value.

(A classic token with only the public_repo scope also works.)

Set it in your shell — for the current session:

export GITHUB_TOKEN=github_pat_xxx        # macOS / Linux / WSL  (GH_TOKEN also works)

$env:GITHUB_TOKEN = "github_pat_xxx"      # Windows PowerShell

Persist it so every new terminal (and your agent tool) sees it:

echo 'export GITHUB_TOKEN=github_pat_xxx' >> ~/.bashrc && source ~/.bashrc   # or ~/.zshrc

[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "github_pat_xxx", "User")   # then reopen the terminal

The token is read from the environment only — it is never written to reports or echoed. Treat it like a password; don't commit it.

Step 2 — Run the skill

From your agent tool (it runs the whole pipeline for you):

• Claude Code: ask for “kernel-radar” or run /kernel-radar
• Codex: invoke the kernel-radar skill
• opencode: /kernel-radar
• Cursor: ask the agent to run kernel-radar (the rule auto-attaches)

Or run the engine directly, no agent needed:

python3 ~/.kernel-radar/engine/radar.py                       # roadmap + competitors + dashboard
python3 ~/.kernel-radar/engine/radar.py --docs ./docs         # also fold in your documents
python3 ~/.kernel-radar/engine/roadmap.py --repo OWNER/NAME   # target a different GitHub project

Step 3 — Read the output

Reports are written to <project>/kernel-radar-reports/<DATE>/, and <project>/kernel-radar-reports/latest.html always points at the newest dashboard:

• dashboard.html / latest.html — the visual roadmap + competitor dashboard (open in a browser, or your agent can publish it as an artifact);
• roadmap.md — gap analysis (done vs. actually merged, untracked directions, dependency/critical-path status);
• competitor-diff.md — how similar projects are moving and where to adjust direction;
• doc-plan.md — planning candidates extracted from any docs you passed.

Override the output location with --output-root DIR or $KERNEL_RADAR_OUTPUT_ROOT. Re-run any time you want a fresh snapshot — the roadmap issue, critical path, and dependency graph are re-derived each run.

---

Configure

Everything tunable lives in ~/.kernel-radar/engine/references/watchlist.yaml:

• seed_repos — always-compare anchors (e.g. verl-project/vexact, vllm, sglang);
• search_queries — how new similar projects are discovered (the primary source);
• discover.* — discovery breadth, star floors, noise filters;
• themes — the lenses competitor activity is mapped onto;
• lookback_days, pr_detail_limit, keep_runs — recency window, per-PR detail depth, report retention.

The roadmap issue is auto-discovered (open issue labelled/titled roadmap); the critical path and dependency graph are re-derived every run, so restructuring or renumbering the roadmap needs no code change.

---

Uninstall

python3 install.py --uninstall --target all

(The shared engine at ~/.kernel-radar is left in place; delete it manually if nothing else uses it.)

---

Development

The engine is stdlib-only (Python 3.8+), no third-party dependencies. PyYAML is optional (a built-in fallback parses the watchlist otherwise).

for t in tests/test_*.py; do python3 "$t"; done   # 15 unit tests, no network
python3 install.py --list                          # installer dry-run

CI runs the same on Python 3.8 / 3.10 / 3.12 (.github/workflows/ci.yml).

Layout

engine/       tool-agnostic core (radar/roadmap/competitors/docs_plan/build_dashboard + watchlist)
SKILL.md      canonical agent instructions (single source; {{ENGINE}} filled at install time)
adapters/     per-tool extras (Codex agents/openai.yaml); frontmatter is generated by install.py
install.py    cross-platform installer (renders each tool's manifest from SKILL.md)
install.sh    curl|bash entry (delegates to install.py)
install.ps1   PowerShell entry
tests/        unit tests

License

MIT — see LICENSE.