Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"name": "know-your-code",
"interface": { "displayName": "know-your-code" },
"plugins": [
{
"name": "know-your-code",
"source": { "source": "url", "url": "https://github.com/MinitJain/know-your-code.git", "ref": "main" },
"policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
"category": "Productivity"
}
]
}
5 changes: 4 additions & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
{
"name": "know-your-code",
"owner": { "name": "Minit Jain" },
"description": "Explain your diff before you push: a learning gate for AI-assisted coding.",
"owner": {
"name": "Minit Jain"
},
"plugins": [
{
"name": "know-your-code",
Expand Down
14 changes: 11 additions & 3 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
{
"name": "know-your-code",
"version": "0.1.0",
"version": "0.2.0",
"description": "Vibe code freely, but explain what changed and why before you git push or open a PR.",
"author": { "name": "Minit Jain" },
"author": {
"name": "Minit Jain"
},
"repository": "https://github.com/MinitJain/know-your-code",
"license": "MIT",
"keywords": ["learning", "git", "hooks", "education"]
"keywords": [
"learning",
"git",
"hooks",
"education"
],
"icon": "./assets/icon.png"
}
25 changes: 25 additions & 0 deletions .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"name": "know-your-code",
"version": "0.2.0",
"description": "Vibe code freely, but explain what changed and why before you git push or open a PR.",
"author": { "name": "Minit Jain", "url": "https://github.com/MinitJain" },
"homepage": "https://github.com/MinitJain/know-your-code",
"repository": "https://github.com/MinitJain/know-your-code",
"license": "MIT",
"keywords": ["learning", "git", "hooks", "education"],
"skills": "./skills/",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "know-your-code",
"shortDescription": "Explain your diff before you push",
"longDescription": "Blocks git push and gh pr create until you answer questions about what changed and why. Three levels: easy, medium, hard.",
"developerName": "Minit Jain",
"category": "Productivity",
"capabilities": ["Instructions", "Lifecycle hooks"],
"websiteURL": "https://github.com/MinitJain/know-your-code",
"defaultPrompt": ["kyc", "kyc explain", "kyc hard"],
"brandColor": "#3b82f6",
"composerIcon": "./assets/icon.png",
"logo": "./assets/icon.png"
}
}
21 changes: 21 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
name: test

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: JSON manifests are valid
run: for f in .claude-plugin/*.json .codex-plugin/plugin.json .agents/plugins/marketplace.json hooks/*.json; do jq empty "$f" || exit 1; done
- name: Versions match
run: test "$(jq -r .version .claude-plugin/plugin.json)" = "$(jq -r .version .codex-plugin/plugin.json)"
- name: Gate tests
run: bash tests/gate.test.sh
9 changes: 9 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# know-your-code

Before you run `git push` or `gh pr create`, the user must explain what changed and why.

1. Check for `.kyc/passed-$(git rev-parse HEAD)` at the repo root. If it exists, push.
2. If `.kyc/skip-$(git rev-parse HEAD)` exists, delete it, append `<date> skip <sha>` to `.kyc/log`, and push.
3. Otherwise follow [`skills/know-your-code/SKILL.md`](skills/know-your-code/SKILL.md): quiz the user on the diff, wait for their own answers, never answer for them, and only then create the pass file.

Agents with hooks (Claude Code, Codex, Cursor) enforce this with `hooks/gate.sh`. Everywhere else this file is the only guard, so follow it.
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

## 0.2.0 — 2026-11-02

- Codex plugin (`.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`). Same hooks as Claude Code.
- Cursor support: `hooks/cursor-hooks.json`; the gate reads Cursor's `beforeShellExecution` input and answers with a JSON deny.
- `AGENTS.md` fallback for agents without hooks.
- Gate block message carries the quiz rules, so agents without the skill still run a fair quiz.
- `/kyc` logic moved into `SKILL.md` so every agent gets the commands.
- README: demo GIF, fixed install line (`know-your-code@know-your-code`), agent support table.
- Icon, GitHub Actions test workflow.
- Gate catches more push forms: subshells, absolute paths, `sudo`, `env`, `command`, `time`, VAR=x prefixes, quoted `git -C` args; ignores `echo git push`. Portable regex (no `\x27`).
- Quiz diff base: upstream, then origin default branch; asks the user instead of quizzing from the first commit.

## 0.1.0 — 2026-11-02

- PreToolUse gate blocks `git push` / `gh pr create` until `.kyc/passed-<HEAD>` exists.
Expand Down
46 changes: 45 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,20 @@ I don't think I'm alone in that.

So I built a Claude Code plugin with guardrails: before you push, you explain what changed and why. Code stays fast. You keep learning.

![know-your-code blocks a git push until you explain the diff](assets/demo.gif)

### Install

**Claude Code** (send these as two separate prompts):

```
/plugin marketplace add MinitJain/know-your-code
/plugin install know-your-code
```
```
/plugin install know-your-code@know-your-code
```

Needs `git` and `jq` on your PATH. More agents: see [Other agents](#other-agents).

### How it works

Expand Down Expand Up @@ -41,13 +49,47 @@ Start easy. Graduate to hard.

### Commands

In Claude Code these are slash commands. In other agents, just say them ("kyc hard").

| Command | Does |
|---|---|
| `/kyc` | Quiz me on the current diff now |
| `/kyc explain` | Walk me through what changed and why |
| `/kyc easy` · `medium` · `hard` | Set difficulty |
| `/kyc off` | Skip the gate once (logged) |

### Other agents

The quiz is an [Agent Skill](https://agentskills.io) (`skills/know-your-code/SKILL.md`), so any agent that reads skills can run it. The gate is a hook, so it only works where the agent has hooks.

| Agent | Gate (blocks push) | Quiz skill | Hard-mode plan nudge | Status |
|---|---|---|---|---|
| Claude Code | ✅ `PreToolUse` | ✅ | ✅ | tested |
| Codex | ✅ `PreToolUse` | ✅ | ✅ | untested |
| Cursor | ✅ `beforeShellExecution` | via `AGENTS.md` | ❌ (Cursor prompt hooks can't add context) | untested |
| Others (Windsurf, Cline, …) | ❌ | via `AGENTS.md` | ❌ | soft rule only |

**Codex**

```bash
codex plugin marketplace add MinitJain/know-your-code
codex plugin add know-your-code@know-your-code
```

Then run `codex`, open `/hooks`, review and trust the hooks, and start a new thread. Codex skips hooks it hasn't trusted.

**Cursor**

```bash
git clone https://github.com/MinitJain/know-your-code ~/.know-your-code
```

Copy `hooks/cursor-hooks.json` to `~/.cursor/hooks.json` (or merge its `beforeShellExecution` entry into yours) and replace `KYC_DIR` with the absolute clone path, e.g. `/Users/you/.know-your-code`. Copy `AGENTS.md` into your project so the agent knows how to run the quiz.

**Anything else**

Copy `AGENTS.md` into your project. Without hooks nothing stops the push, so the agent follows the rule on its own.

### Why not just use Learning mode?

Claude Code's Learning mode nudges. It doesn't stop you. Other tools make you write every line by hand. know-your-code stays out of your way while you build, and only stands between you and shipping.
Expand All @@ -57,13 +99,15 @@ Claude Code's Learning mode nudges. It doesn't stop you. Other tools make you wr
- State lives in `.kyc/` at your repo root (self-gitignored).
- A pass is tied to the exact commit. New commit, new quiz.
- Needs `jq`. If `jq` is missing the gate fails open and warns.
- Catches `git push` and `gh pr create`, also inside chains like `git add . && git push`. Not caught: shell aliases (`gp`) and commands wrapped in `sh -c '...'`.
- It is an honor system: you can always delete the hook. The point is the habit, not the lock.

### Develop

```
claude --plugin-dir ~/know-your-code
bash tests/gate.test.sh
claude plugin validate .
```

### License
Expand Down
Binary file added assets/demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 2 additions & 12 deletions commands/kyc.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,6 @@ description: Quiz, explain, set level, or skip the know-your-code gate
argument-hint: "[explain | easy | medium | hard | off]"
---

Use the know-your-code skill. Argument: `$ARGUMENTS`
Use the know-your-code skill and follow its "Commands" section for: `kyc $ARGUMENTS`

- empty → run the quiz flow on the current diff now.
- `explain` → walk the user through the diff: what changed, why, data flow, risks. Plain words, grouped by file. No quiz, no pass file.
- `easy` | `medium` | `hard` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo <level> > .kyc/level`. Confirm in one line what that level does.
- `off` → ask the user for a one-line reason, then:
```bash
mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore)
touch .kyc/skip-$(git rev-parse HEAD)
echo "$(date -u +%FT%TZ) off $(git rev-parse HEAD) <reason>" >> .kyc/log
```
Tell them the next push of this commit goes through once, and it's logged.
- anything else → show the usage line from argument-hint.
Empty argument = run the quiz now. Unknown argument = show the usage line from argument-hint.
12 changes: 12 additions & 0 deletions hooks/cursor-hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{
"command": "bash \"KYC_DIR/hooks/gate.sh\"",
"matcher": "git|gh ",
"timeout": 15
}
]
}
}
44 changes: 30 additions & 14 deletions hooks/gate.sh
Original file line number Diff line number Diff line change
@@ -1,19 +1,29 @@
#!/usr/bin/env bash
# know-your-code gate: PreToolUse hook on Bash.
# Blocks `git push` / `gh pr create` until the user has explained the current HEAD.
# Exit 0 = allow, exit 2 = block (stderr goes back to Claude).
# know-your-code gate. Blocks `git push` / `gh pr create` until the user has explained the current HEAD.
# Claude Code + Codex: PreToolUse on Bash, command in .tool_input.command.
# Cursor: beforeShellExecution, command in top-level .command, wants JSON on stdout.
# Exit 0 = allow, exit 2 = block (reason on stderr).

input=$(cat)

# Fail open: a learning tool must never brick someone's shell.
command -v jq >/dev/null || { echo "know-your-code: jq missing, gate disabled" >&2; exit 0; }

cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
cmd=$(jq -r '.tool_input.command // .command // empty' <<<"$input")
cwd=$(jq -r '.cwd // empty' <<<"$input")

# Match push/PR anywhere in a chain (`git add . && git push`), allowing global
# flags like `git -C dir push`, but not `git commit -m "push"`.
if ! grep -Eq '(^|[;&|( ])git( +-[^ ]+( +[^- ][^ ]*)?)* +push( |$)|(^|[;&|( ])gh +pr +create( |$)' <<<"$cmd"; then
event=$(jq -r '.hook_event_name // empty' <<<"$input")
cursor_input=$(jq -r '.command // empty' <<<"$input")

# Match push/PR at a shell-command boundary (`git add . && git push`), allowing
# wrappers (sudo, env, command, exec, nohup, time), VAR=x prefixes, a path to the
# binary and quoted global-option args, but not text like `echo git push`.
# shortcut: `sh -c 'git push'` and shell aliases are not caught; needs a real shell parser.
q="'" # literal quote: `\x27` in an ERE is not portable across grep implementations
pre='(^|[;&|(){}])[[:space:]]*((sudo|env|command|exec|nohup|time)([[:space:]]+-[^[:space:]]+)*[[:space:]]+|[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*(/?[[:alnum:]_.-]+/)*'
end='([[:space:]]|$|[;&|(){}])'
git_push="${pre}git([[:space:]]+-[^[:space:]]+([[:space:]]+(\"[^\"]*\"|${q}[^${q}]*${q}|[^[:space:]]+))?)*[[:space:]]+push${end}"
gh_pr="${pre}gh[[:space:]]+pr[[:space:]]+create${end}"
if ! grep -Eq "$git_push|$gh_pr" <<<"$cmd"; then
exit 0
fi

Expand All @@ -32,10 +42,16 @@ if [ -f "$kyc/skip-$head" ]; then
fi

level=$(cat "$kyc/level" 2>/dev/null || echo medium)
cat >&2 <<EOF
⛔ know-your-code: explain before you ship (level: $level, HEAD ${head:0:7})
Do not retry the push. Use the know-your-code skill to quiz the user on this diff.
Only after they pass, create $kyc/passed-$head and push again.
To skip once (logged), the user runs: /kyc off
EOF
# Self-contained so agents without the skill loaded still run a fair quiz.
msg="⛔ know-your-code: explain before you ship (level: $level, HEAD ${head:0:7})
Do not retry the push. Use the know-your-code skill if you have it. Otherwise:
ask the user 3 questions about this diff (what changed, why this way, what breaks),
wait for their own answers, never answer for them, explain anything they get wrong.
Only after they pass: mkdir -p \"$kyc\" && touch \"$kyc/passed-$head\", then push again.
To skip once (logged), the user runs /kyc off (or says \"kyc off\" in other agents)"

if [ "$event" = beforeShellExecution ] || [ -n "$cursor_input" ]; then
jq -n --arg m "$msg" '{permission:"deny",user_message:"know-your-code: explain before you ship",agent_message:$m}'
fi
echo "$msg" >&2
exit 2
4 changes: 2 additions & 2 deletions hooks/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/gate.sh" }]
"hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/gate.sh\"" }]
}
],
"UserPromptSubmit": [
{
"hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh" }]
"hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh\"" }]
}
]
}
Expand Down
23 changes: 21 additions & 2 deletions skills/know-your-code/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,12 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it
## Quiz flow (gate blocked a push, or `/kyc`)

1. Find the diff being shipped:
- upstream exists: `git diff @{u}...HEAD`
- else: `git diff $(git merge-base HEAD origin/HEAD 2>/dev/null || git rev-list --max-parents=0 HEAD)...HEAD`
```bash
base=$(git merge-base HEAD @{u} 2>/dev/null || git merge-base HEAD origin/HEAD 2>/dev/null \
|| git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null)
git diff "$base"...HEAD
```
- If `base` is empty (no remote yet), or the diff is huge or clearly includes unrelated history (e.g. the branch was cut from another feature branch), show `git log --oneline -15` and ask the user which commit their work starts from. Never quiz from the repo's first commit.
- Uncommitted changes are not part of the push. Mention them, don't quiz them.
2. Read the diff and the code around it. Ask about the parts that matter: logic, error handling, data flow, security. Never ask about formatting, renames, or lockfiles.
3. Read the level file (`levels/<level>.md` next to this file) and follow it.
Expand All @@ -38,6 +42,21 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it
```
Then retry the original push/PR command.

## Commands

In Claude Code these are `/kyc ...`. In other agents the user just says "kyc easy", "kyc off" and so on.

- `kyc` → run the quiz flow on the current diff now.
- `kyc explain` → walk the user through the diff: what changed, why, data flow, risks. Plain words, grouped by file. No quiz, no pass file.
- `kyc easy` | `medium` | `hard` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo <level> > .kyc/level`. Confirm in one line what that level does.
- `kyc off` → ask for a one-line reason, then:
```bash
mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore)
touch .kyc/skip-$(git rev-parse HEAD)
echo "$(date -u +%FT%TZ) off $(git rev-parse HEAD) <reason>" >> .kyc/log
```
Tell them the next push of this commit goes through once, and it's logged.

## Rules

- Never create `passed-*` without the user answering. That defeats the whole tool. If the user says "just push", point them to `/kyc off`.
Expand Down
30 changes: 30 additions & 0 deletions tests/gate.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,21 @@ expect 2 "$repo" "git push" "git push blocked"
expect 2 "$repo" "git push -u origin main" "git push with args blocked"
expect 2 "$repo" "git add . && git push" "chained push blocked"
expect 2 "$repo" "git -C . push" "push with global flag blocked"
expect 2 "$repo" "git -C '/tmp/a b' push" "push with quoted global arg blocked"
expect 2 "$repo" "(git push)" "push in subshell blocked"
expect 2 "$repo" "/usr/bin/git push" "absolute git push blocked"
expect 2 "$repo" "sudo git push" "sudo git push blocked"
expect 2 "$repo" "gh pr create --fill" "gh pr create blocked"
expect 2 "$repo" "env -i git push" "env -i git push blocked"
expect 2 "$repo" "command git push" "command git push blocked"
expect 2 "$repo" "GIT_TRACE=1 time git push" "VAR=x time git push blocked"
expect 0 "$repo" "echo git push" "push text in echo allowed"
expect 0 "$repo" 'git commit -m "git push later"' "git push inside commit msg allowed"
expect 0 "$(mktemp -d)" "git push" "outside git repo allowed"

msg=$(jq -n --arg d "$repo" '{tool_input:{command:"git push"},cwd:$d}' | bash "$gate" 2>&1 >/dev/null)
grep -q 'mkdir -p ".*" && touch ".*passed-' <<<"$msg" && echo "ok block guidance quotes state path" || { echo "FAIL block guidance quotes state path"; fail=1; }

mkdir -p "$repo/.kyc" && touch "$repo/.kyc/passed-$(head)"
expect 0 "$repo" "git push" "passed HEAD allowed"

Expand All @@ -39,4 +51,22 @@ expect 0 "$repo" "git push" "skip allows once"
expect 2 "$repo" "git push" "skip consumed"
grep -q "skip $(head)" "$repo/.kyc/log" && echo "ok skip logged" || { echo "FAIL skip logged"; fail=1; }

# Cursor beforeShellExecution: top-level command, JSON deny on stdout
git -C "$repo" -c user.name=t -c user.email=t@t commit -q --allow-empty -m cursor
out=$(jq -n --arg d "$repo" '{hook_event_name:"beforeShellExecution",command:"git push",cwd:$d}' | bash "$gate" 2>/dev/null); code=$?
[ "$code" = 2 ] && [ "$(jq -r .permission <<<"$out")" = deny ] && echo "ok cursor push denied with JSON" || { echo "FAIL cursor push denied with JSON (code $code, out: $out)"; fail=1; }
out=$(jq -n --arg d "$repo" '{command:"git push",cwd:$d}' | bash "$gate" 2>/dev/null); code=$?
[ "$code" = 2 ] && [ "$(jq -r .permission <<<"$out")" = deny ] && echo "ok cursor wire input denied with JSON" || { echo "FAIL cursor wire input denied with JSON (code $code, out: $out)"; fail=1; }
out=$(jq -n --arg d "$repo" '{hook_event_name:"beforeShellExecution",command:"ls",cwd:$d}' | bash "$gate" 2>/dev/null); code=$?
[ "$code" = 0 ] && [ -z "$out" ] && echo "ok cursor non-push allowed" || { echo "FAIL cursor non-push allowed"; fail=1; }

# hard-plan.sh: nudge only on hard level with no plan for the branch
hp="$(dirname "$gate")/hard-plan.sh"
nudge() { jq -n --arg d "$repo" '{prompt:"add login",cwd:$d}' | bash "$hp"; }
[ -z "$(nudge)" ] && echo "ok no nudge on medium" || { echo "FAIL no nudge on medium"; fail=1; }
echo hard > "$repo/.kyc/level"
nudge | grep -q "know-your-code (hard)" && echo "ok nudge on hard without plan" || { echo "FAIL nudge on hard without plan"; fail=1; }
touch "$repo/.kyc/plan-$(git -C "$repo" rev-parse --abbrev-ref HEAD | tr / -).md"
[ -z "$(nudge)" ] && echo "ok no nudge once plan exists" || { echo "FAIL no nudge once plan exists"; fail=1; }

exit $fail
Loading