The safety net the base runs for you

This page covers three automatic checks that the base runs without you asking. If you ever notice “something showed up that I did not type” or “the AI suddenly stopped at commit time”, the cause is almost always one of these three.

That is why this chapter exists at all. Once you have seen what each one does, you will recognize it the next time it fires and move on instead of getting stuck.

Where they live

There are three shell scripts in .claude/hooks/. Whether each one runs is decided by .claude/settings.json. The base ships them already wired up, so they work from the first session without any setup on your side.

File	When it fires	What it does in one line
`session-start.sh`	When a new Claude Code session opens	Hands the AI everything needed to know “where I left off”
`stop-reminder.sh`	When an AI response finishes	Reminds you to leave one line for the next session
`pre-commit-check.sh`	Just before the AI runs `git commit`	Runs typecheck and lint first to block broken code

One — the AI does not have to ask where you left off

That is what session-start.sh does. The script runs first when you open a fresh Claude Code window and quietly hands the AI the contents of these files:

.claude/session-state/archive/active.md: the “next thing to do” your last session left behind
the last 30 lines of .claude/session-state/progress/progress.md: recent progress log
.claude/state/feature_list.json: the feature ground truth your extension promised
the first 50 lines of docs/design/extension-spec.md: the extension spec
.claude/agent-memory/MEMORY.md: the project decision-cache index

What it looks like when it works: opening a new session, the very first message in the window is titled “세션 컨텍스트 자동 복원” (Session context auto-restore), followed by the contents of those files in one block. From there you can say “continue” and the AI picks up where it stopped.

The first time, it stays quiet: right after you clone the base, none of those files exist yet. The script notices that and exits without printing anything. The /start skill creates an empty template the first time you actually start work.

What it looks like when it is broken: you worked yesterday, but a new session opens with no “auto-restore” block. Nine times out of ten, somebody (you or the AI) removed the SessionStart entry from .claude/settings.json. Pull the original settings.json from the base and copy that one entry back in.

Two — a nudge to leave one line behind

That is stop-reminder.sh. After every AI response, it checks the length of active.md. If the file holds fewer than 20 non-whitespace characters, it prints a short note to you:

💡 다음 세션을 위해 한 줄 적어두면 이어서 시작하기 편해요:
   파일: .claude/session-state/archive/active.md
   예시: "popup UI 색상 결정 중. 다음엔 옵션 페이지 폼 만들기"

(Roughly: “Leaving one line for next time makes it easier to pick up. File: .claude/session-state/archive/active.md. Example: ‘Deciding popup UI colors. Next: build the options page form.’”)

This is the spot non-developers tend to skip the most. The habit of writing down “what comes next” is not built in, so people close the window at the end of a session. The auto-restore block then starts empty next time, and the AI has to ask where you left off all over again.

What it looks like when it works: the note shows up, and you write a one-liner into .claude/session-state/archive/active.md. The very first auto-restore block in the next session quotes that one line back to you.

When you can ignore it: if active.md already has enough in it, the note does not show up at all. And if the note does show up but you genuinely got nothing useful done in that session, closing the window is fine. This is a safety net, not an enforced rule.

Three — broken code does not get committed

That is pre-commit-check.sh. Right before the AI runs a git commit ... command, the hook runs typecheck and lint first. Both have to pass before the commit goes through; if either one fails, the commit is blocked and the last 30 lines of the failing output are printed alongside the block message.

This is the hook that helps non-developers most. The AI sometimes wires up the wrong type in one place and tries to commit on top of it anyway. Without this hook the broken state would land in your git history. This hook catches the moment in between.

What a passing run looks like:

🔍 commit 전 자동 검사 (typecheck + lint)…
✓ typecheck + lint 통과 — commit 진행

(Translation: “Running pre-commit checks (typecheck + lint)… typecheck + lint passed — proceeding with commit.”)

If you see those two lines, the commit went through.

What a blocked run looks like:

🔍 commit 전 자동 검사 (typecheck + lint)…
❌ typecheck 실패. commit이 차단됐어요. 아래 메시지를 AI에게 보여주고 고쳐달라고 하세요:

src/popup/index.tsx:14:7 - error TS2322: Type 'string' is not assignable to type 'number'.
...

(Translation: “Pre-commit checks (typecheck + lint)… typecheck failed. Commit blocked. Paste the message below to the AI and ask it to fix.”)

When that happens, copy the 30 lines as-is into the Claude Code window and ask “fix this”. The AI rewrites the spot it broke. Try the commit again afterwards and the second attempt usually goes through.

Other package managers: the hook looks for pnpm-lock.yaml, yarn.lock, or package-lock.json to decide which manager to run. The base defaults to pnpm, so most of the time you will see pnpm in the output.

Turning one off

If a particular safety net gets in your way, remove the matching entry from .claude/settings.json. The three are independent, so dropping one does not affect the other two.

{
  "hooks": {
    "SessionStart": [...],
    "Stop": [...],
    "PreToolUse": [...]
  }
}

For example, if the pre-commit gate annoys you, delete the whole "PreToolUse": [...] block. To turn it back on, copy that block from the base’s original settings.json.

The recommendation is to leave them on. All three guard the spots where non-developers most often lose context, so turning one off pushes that responsibility back onto you.

Should you add new hooks of your own

Almost never. The three the base ships already cover the worst spots in a non-developer workflow.

If you really do find a new spot worth automating, you would write your own shell script for it, and that lives outside the scope of this guide. The expert architecture page covers the same hook system at a denser, developer-facing pace, and that is the right place to start.

Now that you have seen what the safety net does on its own, the next chapter covers the spots where the workflow itself stops moving — when the AI repeats the same mistake twice, or when you cannot remember where you left off. Both come up in 08-when-ai-gets-stuck.md. Distribution comes after that, in 09-distribution.md.