Have a team of coding agents make a GPU kernel or workload faster: profile, find the gap to speed of light, propose, build, test, judge, stack and audit, against a frozen evaluator.

GitHub stars
20

Install

/plugin install kar@kernel-autoresearch

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gauravjain14/kernel-autoresearch-plugin.

Contents

Discovered from source

Skills 1

kar: a team of agents closing the gap to speed of light

A run is split into lanes, several at once:

  • survey: read the code and the profile through one lens (structure, memory, instructions, latency), measure with ncu, nsys, SASS and bound probes, report findings with numbers;
  • plan: turn findings into hypotheses with predicted gains, the arithmetic, and a bound test each;
  • build: implement one hypothesis, test it like a user would, then submit (the harness judges) or abandon;
  • stack: port wins judged on an older best onto the current one;
  • audit: read a new best for hazards no test reaches, and prove them with tests that then gate every kernel.

The floor of every shape comes from a roofline: the task's compulsory bytes and flops at this GPU's measured bandwidth and peaks, plus the fixed cost of a call. The judge runs lint, a 20 s smoke call, correctness on scored and nearby shapes, a stress suite (concurrent streams, fresh threads, held results, more seeds), the team's registered tests, then an A/B against the current best inside one GPU job. Agents read the PTX ISA, CUDA guides and tuning guides through docs. GPU jobs run locally, on Modal (modal:H200:3) or over ssh. An external judge is optional.

wantdo
one prompt to a running team/kar:kar "<what, which GPU, rules>" [--from FOLDER], or the steps below
is this machine readykar doctor [--backend SPEC]
a task only/kar:kar-new <dir> "<request>"
a team on an existing task or run`/kar:kar-run <task
join a run as one more agent/kar:kar-join <run folder>
where a run stands/kar:kar-status <run folder> (kar status RUN --board)
judge results and approvals/kar:kar-judge <run folder> (kar judge RUN status)
stop a teamkar stop RUN
the final, re-measured result/kar:kar-report <run folder> (kar report RUN)

One prompt to a running team, without slash commands (Codex, Grok, any agent)

  1. kar doctor (add --backend modal:H200:3 or ssh:host when the GPU is not this machine's); fix what it lists.
  2. kar new kar-tasks/<name> "<the user's request>" [--from FOLDER], then write the task files following kar-tasks/<name>/AGENTS.md (read source/ first if it is there). kar validate kar-tasks/<name> until TASK OK.
  3. Show the user reference.py, the scored shapes and the Assumptions in DESCRIPTION.md; get a yes. Ask the agent budget (default $25 at list prices).
  4. kar go --task kar-tasks/<name> --yes --detach --lanes 4 --agent-usd BUDGET [--agent codex] [--backend SPEC] [--judge kar-tasks/<name>/judge.toml]. It returns with a log file; the team runs in the background. The log names the run folder after the evaluator is proved.
  5. kar status RUN to follow, kar stop RUN to stop, kar run RUN --agent-usd MORE --detach to continue, kar report RUN for the final re-measured result. The best kernel is RUN/candidates/<best id>/kernel.py.

kar is the plugin's launcher, bin/kar in the plugin folder (two folders above this file); the engine ships inside the plugin. In Claude Code it is on PATH as kar (also ${CLAUDE_PLUGIN_ROOT}/bin/kar); in Codex, Grok or another agent, run it by its path. It needs Python 3.11+ with numpy, and says what to install if not. Inside a run an agent's only GPU access is its lane's command, ./lanes/<id>/kar (or the MCP server RUN/ws/kar-mcp), and it writes only in its lane folder. The workspace's AGENTS.md has the rules, METHOD.md the method, help/PITFALLS.md the measured traps.

Commands 7

Join the kar run at $ARGUMENTS as one agent of its team.

kar is this plugin's command, on the shell's PATH (else ${CLAUDE_PLUGIN_ROOT}/bin/kar).

  1. If no harness process serves the run ($ARGUMENTS/ws/queue/server.json missing or older than 15 seconds), start one in the background: kar serve $ARGUMENTS --detach.
  2. cd $ARGUMENTS/ws, read AGENTS.md and METHOD.md, then run ./kar next. It gives you a lane and its command (./lanes/<id>/kar). If it says the run is driven by kar run, tell the user and stop: that run hands out its own lanes.
  3. Do your lane's step exactly as ./lanes/<id>/kar next describes. Write only in your lane folder, use the GPU only through your lane's command, and hand back with your role's command. Subagents are welcome for reading.
  4. When your lane is done, run ./kar next for another lane if the user wants you to keep going.

Run kar judge $ARGUMENTS status (kar is this plugin's command, on the shell's PATH; else ${CLAUDE_PLUGIN_ROOT}/bin/kar) and summarize it for the user: the last judge results (score, which candidate, local estimate), quota left, the judge's measured noise and the runs needed to see a 1-2% change, and every request waiting for approval.

For each waiting request, tell the user what it is (check or scored submit, which candidate, why, the local gain since the last judged build) and ask whether to approve it. Only on an explicit yes, run kar judge RUN approve ID and report the result. Never approve a scored submit on your own.

Create a kar task folder from this request: $ARGUMENTS

kar is this plugin's command, on the shell's PATH (else ${CLAUDE_PLUGIN_ROOT}/bin/kar).

  1. Run kar new <dir> "<request>" with the folder and request from the arguments. It writes DESCRIPTION.md, AGENTS.md (the task-writing instructions) and a skeleton.
  2. Read <dir>/AGENTS.md and <dir>/DESCRIPTION.md, then write the task files yourself, following AGENTS.md.
  3. Run kar validate <dir> after each change until it prints TASK OK. Record every choice the request left open under "Assumptions" in DESCRIPTION.md.
  4. Tell the user to review reference.py (it defines correct) and the assumptions, and show the next command: /kar:kar-run <dir> --lanes 4.

Run kar report $ARGUMENTS (kar is this plugin's command, on the shell's PATH; else ${CLAUDE_PLUGIN_ROOT}/bin/kar). It re-checks and re-measures the best on the GPU, which takes a few minutes. Then summarize REPORT.md for the user: the final result with its interval, the integrity lines (any that are not ok or none come first), the trajectory of the best, the team's cost per agent, and any hazards the auditors raised. Say where the final kernel is: $ARGUMENTS/candidates/<best id>/kernel.py.

Start a kar team run in the background: $ARGUMENTS

kar is this plugin's command, on the shell's PATH (else ${CLAUDE_PLUGIN_ROOT}/bin/kar).

  1. If the user gave no --agent-usd or --gpu-h, ask what budget to use before starting (a team spends faster than one agent). Default to --lanes 4 if no team size is given.
  2. Start it in the background: kar run $ARGUMENTS --detach. It returns at once with a log file, and the team keeps running after this session ends.
  3. A few minutes later, read the log: it names the run folder (run folder ..., for a new run) and shows the evaluator being proved on the task. Report the run folder and the log file to the user.
  4. Tell the user how to follow it (/kar:kar-status <run folder>), how to stop it (kar stop <run folder>), and how to read the result (/kar:kar-report <run folder>).

Show the state of the kar run at $ARGUMENTS.

Run kar status $ARGUMENTS --board (kar is this plugin's command, on the shell's PATH; else ${CLAUDE_PLUGIN_ROOT}/bin/kar). Read $ARGUMENTS/ws/candidates/<id>/report.md of the newest candidates only if the user asks what changed. Summarize in a few lines: the best so far (% of speed of light and x baseline), what each lane at work is doing, what was kept and what died recently, and the budget used. Don't paste the whole board.

The user wants a GPU kernel or workload made faster by a kar team: $ARGUMENTS

kar is this plugin's command and is on the shell's PATH: run it as plain kar ..., one command per call, with no pipes, &, nohup or $(...) (if kar is not found, use ${CLAUDE_PLUGIN_ROOT}/bin/kar). Do these steps in order. Keep the user informed in a line or two per step; don't paste long outputs.

  1. Understand the request. What is optimized (files, a folder, an op described in words), on which GPU, under which rules (precision, size limits), against which judge if any (a leaderboard CLI, an evaluation script), with what budget. Ask only for what is missing and matters: the agent budget (default $25 at list prices; under about $15 a team has room for little more than its first round) and, if the target GPU is not this machine's, the backend (modal:H200:3, ssh:host:0,1).
  2. Check the machine: kar doctor (add --backend SPEC for a remote backend). Fix what you can; tell the user what you can't.
  3. Write the task. kar new TASK_DIR "REQUEST" [--from FOLDER] (TASK_DIR: kar-tasks/<short-name>). Then write the task files yourself with the file tools, following TASK_DIR/AGENTS.md; if there is TASK_DIR/source/, read it completely first and mirror what it measures (reference, inputs, shapes, score formula, rules, judge). Run kar validate TASK_DIR [--backend SPEC] after each change until it prints TASK OK.
  4. Show the user what "correct" means: reference.py, the scored shapes and the Assumptions in DESCRIPTION.md. Ask for a yes before going on (unless the user already gave it).
  5. The judge (only if the user has one): write TASK_DIR/judge.toml with a [judge] table: the check and submit command lines (with {file}), how to read a score (parse = "judge.py:parse" with a small parser in the task, or a score: N line), the quotas, policy = { check = "auto", submit = "ask" }. Confirm the commands with the user. Scored submissions always wait for the user's approval.
  6. Start the team in the background: kar go --task TASK_DIR --yes --detach --lanes 4 --agent-usd BUDGET [--backend SPEC] [--judge TASK_DIR/judge.toml] It returns at once with a log file; the team keeps running after this session ends. A few minutes later, read the log: it shows the evaluator being proved on the task and then names the run folder (run folder ...). If it says INIT FAILED, the reason is in the log: fix the task (step 3) and start again.
  7. Tell the user the run folder and the log, how to follow it (/kar:kar-status RUN), how to approve judge submissions (/kar:kar-judge RUN), how to stop it (kar stop RUN), how to continue it with more budget (/kar:kar-run RUN --agent-usd MORE), and how to get the final re-measured result (/kar:kar-report RUN).

Sponsors

Details

Marketplace
gauravjain14/kernel-autoresearch-plugin
Author
Gaurav Jain (gauravjain14)
Category
Community