chore: טעינת פריימר CodeKeeper בפתיחת סשן דרך SessionStart hook

[amirbiron]

תבנית Pull Request

✨ תיאור קצר

הפלאגין codekeeper-memory מותקן ומופעל ברמת חשבון claude.ai, אבל סביבות ההרצה המרוחקות של Claude Code on the web לא טוענות פלאגינים מהמרקטפלייס — אין תיקיית ~/.claude/plugins, וההוק שלו אף פעם לא רץ. התוצאה: הוראות הסוכן מ-CodeKeeper לא הגיעו להקשר, בשקט מוחלט.

ה-PR רושם את אותה התנהגות ישירות ב-.claude/settings.json של הריפו, כך שהיא לא תלויה במנגנון הפלאגינים ורצה בכל סשן על CodeBot — מרוחק או מקומי.

📦 שינויים עיקריים

• קוד (Backend)
• בוט טלגרם
• מסד נתונים/מיגרציות
• תיעוד (docs/)
• DevOps/CI/CD

פירוט נקודות:

• הוספת .claude/settings.json עם SessionStart hook יחיד (קובץ חדש, 22 שורות, אין שינוי בקוד קיים)
• ההוק מסוג http — פונה ל-GET /api/agent/primer של שירות ה-MCP ומחזיר text/plain שנכנס להקשר הסשן
• אימות דרך $CODEKEEPER_PAT, שמוצהר ב-allowedEnvVars. שום ערך סודי לא נכנס לגיט — רק שם המשתנה
• timeout: 10 שניות, כדי ש-cold start של Render לא יתקע את פתיחת הסשן

למה http ולא סקריפט shell

הגרסה הראשונה שנשקלה העתיקה את session_start.sh מריפו הפלאגין. הגרסה הזו עדיפה:

• אין קוד שרץ, רק הצהרה — פחות מקומות להישבר
• 204 (אין הוראות מוגדרות) מטופל חינם: הוא 2xx עם גוף ריק, כלומר "הצלחה בלי הקשר" — בדיוק ההתנהגות שהסקריפט מימש ידנית
• תשובה שאינה 2xx היא שגיאה לא-חוסמת — הסשן נפתח כרגיל, אותה ערובה שה-exit 0 בסקריפט נתן

מה שנאבד: הודעות ה-stderr המפורטות של הסקריפט (למשל check CODEKEEPER_PAT). מודע ומקובל.

🧪 בדיקות

• Unit
• Integration
• Manual

מה נבדק:

• תקינות JSON וסכימה — jq -e על נתיב ההוק מחזיר את ה-URL, exit 0
• האנדפוינט חי — curl החזיר 401 עם www-authenticate: Bearer realm="CodeKeeper MCP", ולא 404. כלומר ה-URL נכון והנתיב קיים
• פורמט הטוקן — CODEKEEPER_PAT בסביבה מתחיל ב-ckmcp_ באורך 49, תואם את הפורמט ב-mcp_server/README.md
• שני משתני הסביבה מוגדרים בסביבת ההרצה המרוחקת

מה לא נבדק: שהטוקן בתוקף (לא בוטל), ושהשדה "הוראות לסוכן" בוובאפ אינו ריק. אם הוא ריק — האנדפוינט יחזיר 204 והכל יישאר שקט למרות שהתצורה תקינה. שתי הנקודות יתבררו רק בסשן הראשון אחרי ה-merge.

🧪 בדיקות נדרשות ב‑PR

• 🔍 Code Quality & Security ✅
• Unit Tests (3.11) ✅
• Unit Tests (3.12) ✅

(כל 20 ה-checks ירוקים)

📝 סוג שינוי

• chore/ci: תשתית/CI

✅ צ'קליסט

• הקוד עוקב אחרי הסגנון — קובץ JSON בלבד
• בדיקות רצות ועוברות
• אין סודות/מפתחות בקוד — רק שם משתנה סביבה
• אין מחיקות מסוכנות/פעולות על root
• הודעת הקומיט תואמת Conventional Commits
• עיינתי ב-mcp_server/README.md בריפו (סעיף "פריימר לסוכן"). באתר CodeBot Docs לא עיינתי — השינוי אינו נוגע לקוד או לטסטים
• אם נוספו/שונו משתני סביבה – עודכן docs/environment-variables.rst וגם services/config_inspector_service.py

הערה על הסעיף האחרון: CODEKEEPER_PAT ו-CODEKEEPER_PRIMER_URL אינם משתני סביבה של אפליקציית CodeBot — הם של סביבת הפיתוח של הסוכן. הם לא נקראים בשום מקום בקוד הריפו ולכן אין להם מקום ב-config inspector. אם המדיניות אומרת אחרת — אשמח לתקן.

🧩 השפעות/סיכונים

אפס השפעה על הריצה של הבוט או הוובאפ. הקובץ נקרא רק על ידי Claude Code בפתיחת סשן פיתוח.

התייחסות לשני הממצאים של Qodo

1. "אי-התאמה בשם משתנה הסביבה" — לא באג.
Qodo מצביע על mcp_server/README.md:103 שמשתמש ב-$CODEKEEPER_TOKEN. אבל זו דוגמת curl בלבד, ושם המשתנה שם הוא מקומי לדוגמה. השרת קורא את הערך בכותרת Authorization: Bearer <value> — הוא לא יודע ולא אכפת לו איך המשתנה נקרא אצל הלקוח. אין כאן חוזה לשבור. אומת בפועל: הערך שב-CODEKEEPER_PAT בפורמט ckmcp_… הנכון.

2. "סוד נשלח דרך הוק" — ממצא לגיטימי, ומקובל בכוונה.
זו בדיוק מטרת ה-PR: שליחת PAT לשירות של בעל הריפו כדי למשוך את הוראות הסוכן שלו. הטוקן נשלח ל-host אחד בלבד, מוצהר במפורש ב-allowedEnvVars, ולא נשמר בגיט.

הנקודה השווה מהממצא היא אחרת: מכיוון שהקובץ מגיע מהריפו, שינוי עתידי ב-url (למשל מ-fork או PR זדוני) יכול להפנות את הטוקן ליעד אחר. המיטיגציה הנכונה היא allowedHttpHookUrls ב-~/.claude/settings.json האישי — הוא מגביל לאילו כתובות הוקים מסוג http רשאים לפנות, והגדרות פרויקט לא יכולות לעקוף אותו. לא נכלל כאן כי מקומו בהגדרות המשתמש ולא בריפו. מומלץ להוסיף:

{ "allowedHttpHookUrls": ["https://codekeeper-mcp.onrender.com/*"] }

🔗 קישורים

• ריפו הפלאגין שממנו נגזרה ההתנהגות: https://github.com/amirbiron/codekeeper-plugin
• תיעוד האנדפוינט: mcp_server/README.md, סעיף "פריימר לסוכן — GET /api/agent/primer"
• Branch Protection & PR Rules

🧯 סיכון / החזרה לאחור (Rollback)

מחיקת .claude/settings.json מחזירה את המצב לקדמותו לחלוטין. אין מיגרציה, אין state, אין תלות של קוד בקובץ.

ביטול זמני בלי מחיקה: הסרת ההוק דרך /hooks, או הגדרת disableAllHooks: true בהגדרות המשתמש.

גם בכשל מלא של השירות החיצוני אין נזק — תשובה שאינה 2xx היא שגיאה לא-חוסמת והסשן נפתח כרגיל.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

This PR introduces a new configuration file .claude/settings.json, likely to define editor/assistant settings or project-specific tooling configuration; no application code, tests, or runtime behavior are modified.

File-Level Changes

Change	Details	Files
Add a new JSON settings configuration file for the Claude tooling/environment.	Create the .claude/settings.json configuration file in the repository root. Define initial settings structure and defaults to standardize tooling behavior for contributors. Ensure the file is tracked in version control so settings are shared across the team.	.claude/settings.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

🧯 Dangerous deletes guard report

Policy: see .cursorrules — dangerous deletions are blocked unless wrapped safely.

Summary:

• Flagged findings (blocking): 0
  0
• Excluded matches (not blocking): 15
• Total matches (all files): 129

Flagged findings (file:line:snippet):
(none)

Excluded matches (by path pattern)

./node_modules/mermaid/dist/mermaid.js.map:4:  "sourcesContent": ["/**\n* Default values for dimensions\n*/\nconst defaultIconDimensions = Object.freeze({\n\tleft: 0,\n\ttop: 0,\n\twidth: 16,\n\theight: 16\n});\n/**\n* Default values for tr … [truncated]
./node_modules/mermaid/dist/mermaid.min.js.map:4:  "sourcesContent": ["/**\n* Default values for dimensions\n*/\nconst defaultIconDimensions = Object.freeze({\n\tleft: 0,\n\ttop: 0,\n\twidth: 16,\n\theight: 16\n});\n/**\n* Default values fo … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.core/chunk-KS23V3DP.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequence  … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm/chunk-2M32CCKP.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequence d … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm.min/chunk-4HFYJGYH.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequen … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm.min/chunk-4HFYJGYH.mjs:1:var r={name:"mermaid",version:"11.12.0",description:"Markdown-ish syntax for generating flowcharts, mindmaps, sequence diagrams, class diagrams, gantt charts, git graph … [truncated]
./node_modules/mermaid/dist/mermaid.min.js:1524:`,"getStyles"),c1e=RQe});var h1e={};dr(h1e,{diagram:()=>NQe});var NQe,f1e=N(()=>{"use strict";$ge();a1e();l1e();u1e();NQe={parser:Fge,db:n1e,renderer:o1e,styles:c1e}});var m1e,g1e=N(()=>{"use  … [truncated]
./node_modules/katex/package.json:153:    "build": "rimraf dist/ && mkdirp dist && cp README.md dist && rollup -c --failAfterWarnings && webpack && node update-sri.js package dist/README.md",
./node_modules/katex/src/fonts/Makefile:139:	rm -rf pfa ff otf ttf woff woff2
./Dockerfile:42:    rm -rf /var/lib/apt/lists/*
./Dockerfile:121:    rm -rf /var/lib/apt/lists/*
./webapp/static/js/md_preview.bundle.js.map:4:  "sourcesContent": ["// Markdown-it plugin to render GitHub-style task lists; see\n//\n// https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments\n// https://github.com/blog/1825-t … [truncated]
./docs/DOCUMENTATION_GUIDE.md:453:rm -rf _build
./docs/Makefile:24:	rm -rf $(BUILDDIR)
./README.md:842:find . -name "__pycache__" -exec rm -rf {} +

[coderabbitai]

📝 Walkthrough

Walkthrough

נוספה תצורת Claude Code עם הוק SessionStart. ההוק שולח בקשת HTTP ל-CodeKeeper, משתמש ב-CODEKEEPER_PAT, מגביל משתני סביבה ומגדיר timeout של 10 שניות.

Changes

אינטגרציית CodeKeeper

שכבה / קבצים	סיכום
תצורת הוק SessionStart .claude/settings.json	Claude Code שולח בקשת HTTP ל-CodeKeeper בתחילת סשן. התצורה כוללת אימות באמצעות CODEKEEPER_PAT, כותרות קבלה, timeout של 10 שניות והודעת סטטוס בעברית.

Estimated code review effort: 2 (Simple) | ~10 דקות

Poem

Claude Code כתב הוק בזמן,
CodeKeeper מקבל סשן מוכן.
PAT נשמר, וה-timeout מוגדר,
סטטוס בעברית מופיע ומסודר.
CodeKeeper forever 💫

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	הכותרת מתארת באופן ברור ומדויק את השינוי המרכזי: טעינת פריימר CodeKeeper באמצעות הוק SessionStart.
Description check	✅ Passed	התיאור מלא ומכסה את השינוי, המטרה, הבדיקות, הסיכונים, האבטחה ותוכנית החזרה לאחור.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch amirbiron-patch-30

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qodo-code-review]

PR Summary by Qodo

Add Claude Code settings to load CodeKeeper agent primer on session start

⚙️ Configuration changes 🕐 Less than 10 minutes

AI Description

• Add repo-level Claude Code settings to standardize agent startup behavior.
• Configure a SessionStart hook to fetch a CodeKeeper primer via HTTP.
• Use CODEKEEPER_PAT env var for auth to avoid committing secrets.

Diagram

graph TD
  A["Claude Code"] --> B[".claude/settings.json"] --> C["SessionStart hook"] --> D{{"CodeKeeper primer API"}}
  D --> E["Agent instructions"]

  subgraph Legend
    direction LR
    _cfg["Config file"] ~~~ _proc["Hook/step"] ~~~ _ext{{"External API"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep settings local (not committed)

• ➕ Avoids coupling the repo to a specific external service URL
• ➕ Reduces risk of surprising network calls for contributors
• ➖ Loses consistent team-wide agent initialization
• ➖ More setup friction for new contributors

2. Use a local primer file instead of HTTP

• ➕ Works offline; no external dependency at session start
• ➕ No token handling required for the primer content
• ➖ Primer updates require PRs/rollouts instead of centralized updates
• ➖ Cannot centralize dynamic policy updates

3. Support opt-in via environment flag

• ➕ Gives contributors control (e.g., disable hook in CI or constrained environments)
• ➕ Reduces disruption if the external service is down
• ➖ Slightly more configuration complexity
• ➖ May lead to inconsistent behavior across developers

Recommendation: Committing a repo-level Claude settings file is reasonable if the goal is consistent agent behavior across the team. Consider adding an opt-in/opt-out mechanism (or documenting how to disable the hook) to mitigate startup failures when the external service is unavailable, and ensure CODEKEEPER_PAT is documented as required developer setup.

Files changed (1) +22 / -0

Other (1) +22 / -0

settings.jsonAdd Claude Code SessionStart hook to fetch CodeKeeper primer +22/-0

Add Claude Code SessionStart hook to fetch CodeKeeper primer

• Introduces a new Claude Code settings file configuring a SessionStart hook that calls the CodeKeeper primer endpoint. Auth is provided via the CODEKEEPER_PAT environment variable (explicitly allowlisted) with a 10s timeout and a user-facing status message.

.claude/settings.json

[github-actions]

⏱️ Performance report

• Run: https://github.com/amirbiron/CodeBot/actions/runs/31233292533
• Artifact: perf-durations

(No performance test durations collected. Mark tests with @pytest.mark.performance.)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (1) 📜 Skill insights (0)

1. Env var name mismatch 🐞 Bug ≡ Correctness

Description

The new SessionStart hook sends Authorization: Bearer $CODEKEEPER_PAT, but the repo’s MCP primer
docs use $CODEKEEPER_TOKEN; users following the docs will not populate CODEKEEPER_PAT, so the
primer request will authenticate with an empty/placeholder token and fail (typically 401). This
breaks the intended “load agent primer on session start” behavior for default/documented setups.

Code

.claude/settings.json[R11-14]

+              "Authorization": "Bearer $CODEKEEPER_PAT",
+              "Accept": "text/plain"
+            },
+            "allowedEnvVars": ["CODEKEEPER_PAT"],

Relevance

●●● Strong

Trivial correctness fix (env var name consistency with docs); similar env/config correctness tweaks
have been accepted.

PR-#3155
PR-#2394

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The hook configuration explicitly uses CODEKEEPER_PAT, while the MCP primer documentation shows
CODEKEEPER_TOKEN in the Authorization header and notes the endpoint returns 401 without a valid
token; therefore users following the documented variable name will not satisfy the hook’s expected
env var.

.claude/settings.json[8-15]
mcp_server/README.md[98-111]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `.claude/settings.json` SessionStart hook uses `CODEKEEPER_PAT`, but the repo’s MCP primer documentation uses `CODEKEEPER_TOKEN`. This mismatch will cause the primer fetch to be unauthenticated for anyone who follows the documented env var name.

## Issue Context
`mcp_server/README.md` documents the primer curl example with `Bearer $CODEKEEPER_TOKEN` and states the endpoint returns `401` without a valid token. The committed Claude hook should use the same env var name (or docs should be updated) so the documented setup works.

## Fix Focus Areas
- .claude/settings.json[8-15]
- mcp_server/README.md[98-111]

## Proposed change
- Prefer standardizing on the documented name:
 - Change `Authorization` to `Bearer $CODEKEEPER_TOKEN`.
 - Change `allowedEnvVars` to `["CODEKEEPER_TOKEN"]`.
- Alternatively (if you prefer `CODEKEEPER_PAT`), update the primer docs to consistently instruct `CODEKEEPER_PAT` and remove `CODEKEEPER_TOKEN` from examples.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. CODEKEEPER_PAT sent via hook 📘 Rule violation ⛨ Security

Description

The new repository-tracked .claude/settings.json config defines a Claude Code SessionStart HTTP
hook that sends an Authorization: Bearer $CODEKEEPER_PAT header to an external endpoint, causing a
secret to be transmitted off-machine. This violates the requirement to not include secrets in AI
prompts/context/config files and also introduces a trust-boundary/supply-chain risk because repo
changes (including untrusted branches/forks) can redirect where a developer’s token is sent unless
the behavior is made explicitly opt-in or constrained.

Code

.claude/settings.json[R11-14]

+              "Authorization": "Bearer $CODEKEEPER_PAT",
+              "Accept": "text/plain"
+            },
+            "allowedEnvVars": ["CODEKEEPER_PAT"],

Relevance

●●● Strong

Team recently accepted multiple secret-leak hardening changes; token-forwarding hook likely flagged
and removed/opt-in.

PR-#3211
PR-#3183

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2443323 prohibits including secrets/keys in AI prompts or context/config files, and
the added Claude settings do exactly that by both whitelisting CODEKEEPER_PAT via allowedEnvVars
and configuring an outbound SessionStart HTTP hook that populates an Authorization header from
that env var, thereby transmitting the secret value to the configured remote URL on session start.
The MCP documentation context indicates this primer is fetched at session start and may require
Authorization, and the fact that .gitignore treats other agent/tooling artifacts as local-only
underscores that committing .claude/settings.json makes this credential-forwarding behavior apply
repo-wide and controllable by future repo edits.

Rule 2443323: Do not include secrets, keys, or PII in AI prompts or context files
.claude/settings.json[11-14]
.claude/settings.json[3-16]
mcp_server/README.md[98-120]
.gitignore[49-53]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A repository-tracked `.claude/settings.json` config enables an outbound `SessionStart` HTTP hook that sends `Authorization: Bearer $CODEKEEPER_PAT` to a remote endpoint. This causes a secret to flow through an AI tool context/config surface (prohibited by compliance) and expands the trust boundary because repo-controlled changes (including untrusted branches/forks) can alter where a developer’s token is sent unless the behavior is explicitly opt-in or constrained.

## Issue Context
The compliance requirement (PR Compliance ID 2443323) prohibits including secrets/keys in AI prompts or context/config files where they may be exposed or exfiltrated. Although the header value is referenced via `$CODEKEEPER_PAT`, the configuration explicitly allows it via `allowedEnvVars` and transmits it off-machine via the configured HTTP hook on session start. The MCP docs describe the primer as being read/fetched at agent session start (and requiring Authorization), which this hook automates; because the hook is committed (unlike other local agent artifacts such as `.cursor/`), it applies broadly to anyone using Claude Code in this repo.

## Fix Focus Areas
- .claude/settings.json[1-22]
- .gitignore[49-56]
- mcp_server/README.md[98-120]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 37 rules

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}