DOING A TEST FOR THIS

<pasted_content id="2523"> Goal: test the quickstart at https://help.altimate.ai/code/getting-started/quickstart/ the way a new developer would, fix any step that breaks, and prove the fix.

1. Run docker info. If it fails, tell me what is missing and how to fix it. On Windows, use Docker inside WSL and set FIRSTRUN_DOCKER. Stop until it works.
2. Run pip install git+https://github.com/HighnessAtharva/firstrun.
3. Check that CLAUDE_CODE_OAUTH_TOKEN is set. If not, ask me to run claude setup-token and set it. Never print a secret.
4. Run firstrun https://help.altimate.ai/code/getting-started/quickstart/. While it runs, tell me in plain words which repo it uses and which step it is on.
5. Read runs/<id>/report.md. Tell me in 3 to 6 short sentences: which step broke, the error, the class Jev gave it, the fix, and whether a fresh container verified the fix.
6. If the fix is verified and patches the docs, show me the diff and the PR body. Ask "Open this PR on <repo>?" and wait for my yes. Open nothing before that.
7. After a yes, run firstrun pr <id> --json and run the gh commands it prints.
8. Last, print the line that starts with "share:" from the run output, so I can watch the replay. </pasted_content id="2523">

i had done it readyyy

REDACTED REDACTED here it is resume and do until completion

okay done it's set please continue

try now

check progress please complete skipped steps!

also everything that i run as long as repo is public on the website

<pasted_content id="2523"> it should be logged under runs because I should be able to see that in the previous runs or in the open real run. This should be put there.

You have to update this Altimate thing as an Altimate code thing because you did not really do it entirely. That's something that you need to do.

Also, in the first run item, in the original number, I do not see the run history anywhere. I see the landing page, but I do not see the run history. I need to see the run history as well.

I do not understand where CFO.ai comes in for each run, or I do not know where it comes in. I just don't understand why this is present here. Maybe you can tell me why this is here, because it feels very out of the picture. I cannot make sense of why CFO.ai is where it is on the website and what it is supposed to do. I'm not entirely sure myself.

You need to make sense of it and do more storytelling on that and any other regards on the website. The /runs is not navigable through the nav bar or anywhere on the page. It is there on one part of the page, but if I want to see all the runs, I should be able to see all the runs. I need to do that, look at the notes folder, and complete anything that is still pending. </pasted_content id="2523">

commit and push

let's get things merged ensure everything is right, all the local branches which are safe to delete apart from main let's delete them assuming that entire is not affected or there are no side effects

The neatlogs folks told me - During this hackathon, you're free to use all features as we've lifted plan restrictions! -look at the neatlogs docs to turn on AI evals and other stuff that we can use here strategically and well! it should be top notch and add superb value!

Try to run your agent as much as possible - neatlogs investigation and incidents will be looked at to judge so please go max mode with this but only sensibly!!! Tell me if you need anything

We can also use treg or jev somehow if possible to do something even crazier on top of this. Don't forget we also have data provider credits left over!!!!

Base directory for this skill: C:\Users\AtharvaShah.claude\skills\gtm-toolbelt

GTM Toolbelt

Each job has exactly one owner among five tools. Zernio publishes. OpenSEO runs SEO for a site. treg buys data. agent-reach reads social platforms for free. Firecrawl reads and crawls the open web. A workflow can chain them, but each step has exactly one owner, and the owner is the cheapest tool that passed the test on 2026-10-03.

Each Job Has One Owner and One Fallback

Two jobs belong to none of the five. Sending an email belongs to Gmail, through the gws-gmail skill, as a draft you approve. Substack DMs and note replies belong to NOTES/SCRIPTS/substack/dm.py and notes_reply.py.

Treg Owns Enrichment Because One Free Firecrawl Account Buys Only 50 Emails

Firecrawl's Alexandria layer resells Apollo, FullEnrich and Data Legion, so both tools sell the same records. treg won on four counts in the 2026-10-03 test.

1. treg charges $0.0048 for a work email. Firecrawl charges 20 credits for one, and a free account gets 1,000 credits a month, so one account buys 50 emails and then stops scraping.
2. Firecrawl refuses every Alexandria call until an org admin accepts the provider's terms, once per provider and once per account. You rotate six accounts, so that is up to 18 acceptances.
3. Firecrawl's free tier allows about 10 requests a minute. The test hit that limit within 12 requests.
4. treg tries providers cheapest first and charges nothing for a miss on per-success endpoints.

Keep Firecrawl's free credits for scraping and crawling, which no other tool here does as well.

treg has one weakness. treg.companies.enrich reported PostHog at 29 employees, which is years out of date. Check headcount against the company's LinkedIn page before you use it to qualify a lead.

Agent-Reach Reads Reddit and X for Free Through Your Browser

agent-reach costs nothing because it reads through your own logged-in Chrome session. Exa search through agent-reach returned five live "founding DevRel" job posts for one query, and each one is a buyer for a DevRel or content service. firecrawl search returned five blog articles for the same query.

Reddit and X stay dark until you install the OpenCLI Chrome extension and stay logged in to reddit.com and x.com. Until then, fall back to treg at about $0.001 a call. Firecrawl refuses Reddit outright.

Never connect agent-reach's LinkedIn channel to your personal account. That channel drives a logged-in scraper, and LinkedIn restricts accounts that scrape. Your personal profile is the sales channel, so treg reads LinkedIn for you through providers that use their own sessions.

Three Built Pipelines Run the Recipes From treg.to/jev

treg fetches and Jev decides. Three scripts in D:\Atharva\NOTES\SCRIPTS\gtm already do this for atharvashah.com and 10x DevRel, so run them before you build anything by hand. Their README is the SOP and holds the tested cost of each run.

Run them from the vault root. Each script stops at its --cap of treg spend.

Every lead hunt keeps only high and qualified leads, and that rule is Atharva's, not a default to tune away. A dropped person never reaches a file. The five Jev checks and their bars live in TIERS and qualify() in buyer_signal.py, and any new hunting script reuses them.

Five Workflows Cost Under $1 per 100 Prospects

Every treg call takes a cost cap as a header. Always send one.

W1. Build a Prospect List From Buying Signals

About $0.70 per 100 prospects.

1. Find companies that show a buying signal with free Exa search.
2. Find the buyer at each company for free.
3. Find the work email of each person worth contacting, at $0.0048 a hit.
4. Verify each email for free with treg.people.email.verify.
5. Save the list as a CSV in the project you work in. Never paste emails into chat.

The 2026-10-03 hunt for book buyers tested this order on 90 Exa results. It produced 11 qualified buyers for $0.128 of treg spend. Four rules came out of that run.

1. Run keyless Exa at most three calls at a time. A fourth parallel call returns HTTP 429.
2. Use category:people in the Exa query to search LinkedIn profiles. A query for announcement posts, such as "I joined X as their first developer advocate", finds people new in seat. Firecrawl search returned only job ads for the same query.
3. Read each finalist's recent posts with treg.linkedin.user.posts before you buy an email. Two of ten finalists had left the job that their profile snapshot still showed.
4. Look up email by name plus domain at $0.0048. Lookup by LinkedIn URL costs $0.005 to $0.02, so use it only when you do not know the domain.

Firecrawl search with --tbs qdr:m beats Exa at one job: finding job posts from the last month, because keyless Exa has no date filter.

W2. Warm a LinkedIn Prospect Before the DM

1. Read their last posts for $0.0015 with treg.linkedin.user.posts and their profile URL.
2. Comment on one post from your personal account, by hand.
3. Draft the DM from what they posted. You send it, because no tool here touches your personal LinkedIn inbox.

W3. Hunt SEO and AEO Keywords

For a site you work on every week, start in OpenSEO. Run the seo-project-setup skill once per site, then keyword-research, keyword-clustering and seo-audit. OpenSEO keeps the project context and the Search Console link, so each later session starts informed.

For a one-off check with no project, such as a book title or a post idea, use treg.

1. Put every candidate keyword into one call, because the $0.09 price covers up to 1,000.
2. Read what currently ranks with firecrawl scrape on the top three URLs.
3. Find SERP and backlink endpoints with treg catalog search "<job>", and read the price before you call.

W4. Listen on Reddit and X for Post Ideas and Reply Targets

1. Search with agent-reach once OpenCLI is connected.
2. Without the browser login, use treg at about $0.001 a call: treg.x.search.posts and anyapi.reddit.search.
3. Turn a thread into a post, then publish through W5.

W5. Publish

Zernio is the only publisher. In the vault, use python SCRIPTS/zernio/post.py for X and python SCRIPTS/zernio/li_draft.py for LinkedIn drafts, and read SCRIPTS/zernio/README.md first. A YouTube video goes through the youtube-publish skill (yt_publish.py), never through post.py, and the cut must be final before it ships because YouTube cannot replace a video file. From any other repo, the zernio MCP server is registered at user scope. A live send always needs Atharva's explicit yes.

Check Every Balance Before a Batch

1. Check the treg balance with treg balance before a batch. Topping up is Atharva's call and his card, so ask him first.
2. Check Firecrawl credits with firecrawl credit-usage. When a slot runs out, run python "D:\Atharva\NOTES\SCRIPTS\keys\keys.py" activate.
3. Check OpenSEO credits with its whoami tool, which costs nothing.
4. agent-reach and Exa cost nothing. Reach for them first whenever they cover the job.

Fund the Balance From the Command Line

The treg web UI does not take the top-up. Use the CLI, and let Atharva type the card.

1. Run treg topup 10. It prints a Stripe Checkout link for $10. Atharva opens the link and pays himself. Never type card details for him.
2. Run treg balance to confirm. The balance updates in seconds.
3. Set the monthly budget with treg topup --auto on --threshold 2 --amount 10 --cap 20. It adds $10 when the balance drops below $2 and never charges more than $20 a month. On 2026-10-03 the account showed auto top-up on with the default cap of $100 a month, so run this command to lower it. Check the result in the auto top-up line of treg balance.

--auto on asks for a typed confirmation and cancels on piped input, so Atharva must run it himself in an interactive terminal. In the Terminal panel on 2026-10-03, treg failed with uv trampoline failed to canonicalize script path. The same exe works from the Bash tool, so run it in a Git Bash tab.

treg/SKILL.md is overwritten by toolbelt.ps1 on restore, so keep this note here.

One Script Restores All Five Tools

The script reinstalls all five tools, signs in from D:\Atharva\NOTES\.env, registers the treg, zernio and openseo MCP servers at user scope, and prints the steps only a person can do. Override the env file with -EnvFile or the CLAUDE_SECRETS_ENV variable.

OpenSEO Must Run on the Right Account

On 2026-10-03 the OpenSEO sign-in belonged to marketing@altimate.ai, which is Altimate's account with 21,302 credits. Use that account only for Altimate sites. Personal SEO for atharvashah.com, the vault or the DevRel workbench needs OPENSEO_API_KEY from a personal OpenSEO account. Run whoami before any paid call to confirm which account is live.

The keyword head-to-head against treg is still open for the same reason. Run the same five keywords through both once a personal key exists, then fix the one-off row above.

We need to update the navbar also the /runs and /audits part of the slugs are really looking entirely different compared to the main application they are appearing in grey and they look different too!!

please fix this issue and make sure it's good!

Base directory for this skill: C:\Users\AtharvaShah.claude\skills\impeccable

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.

Setup (non-optional)

Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.

Codex-style agents must state this before editing files:

For $impeccable craft, shape=pass is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark shape=pass after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.

Other harnesses should follow the same checklist when they can expose this state.

1. Context gathering

Two files, case-insensitive. The loader looks at the project root by default and falls back to .agents/context/ and docs/ if the root is clean. Override with IMPECCABLE_CONTEXT_DIR=path/to/dir (absolute or relative to cwd).

• PRODUCT.md — required. Users, brand, tone, anti-references, strategic principles.
• DESIGN.md — optional, strongly recommended. Colors, typography, elevation, components.

Load both in one call:

Consume the full JSON output. Never pipe through head, tail, grep, or jq. The output's contextDir field tells you where the files were resolved from.

If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran $impeccable teach or $impeccable document (they rewrite the files), or the user manually edited one.

$impeccable live already warms context via live.mjs — if you've run live.mjs, don't also run load-context.mjs this session.

If PRODUCT.md is missing, empty, or placeholder ([TODO] markers, <200 chars): run $impeccable teach, then resume the user's original task with the fresh context. If the original task was $impeccable craft, resume into $impeccable shape before any implementation work.

If DESIGN.md is missing: nudge once per session ("Run $impeccable document for more on-brand output"), then proceed.

2. Register

Every design task is brand (marketing, landing, campaign, long-form content, portfolio — design IS the product) or product (app UI, admin, dashboard, tool — design SERVES the product).

Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) register field in PRODUCT.md. First match wins.

If PRODUCT.md lacks the register field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run $impeccable teach to add the field explicitly.

Load the matching reference: reference/brand.md or reference/product.md. The shared design laws below apply to both.

Shared design laws

Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work — don't hold back.

Color

• Use OKLCH. Reduce chroma as lightness approaches 0 or 100 — high chroma at extremes looks garish.
• Never use #000 or #fff. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
• Pick a color strategy before picking colors. Four steps on the commitment axis:
  • Restrained — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
  • Committed — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
  • Full palette — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
  • Drenched — the surface IS the color. Brand heroes, campaign pages.
• The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.

Theme

Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."

Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.

"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.

Typography

• Cap body line length at 65–75ch.
• Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.

Layout

• Vary spacing for rhythm. Same padding everywhere is monotony.
• Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
• Don't wrap everything in a container. Most things don't need one.

Motion

• Don't animate CSS layout properties.
• Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.

Absolute bans

Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.

• Side-stripe borders. border-left or border-right greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
• Gradient text. background-clip: text combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
• Glassmorphism as default. Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
• The hero-metric template. Big number, small label, supporting stats, gradient accent. SaaS cliché.
• Identical card grids. Same-sized cards with icon + heading + text, repeated endlessly.
• Modal as first thought. Modals are usually laziness. Exhaust inline / progressive alternatives first.

Copy

• Every word earns its place. No restated headings, no intros that repeat the title.
• No em dashes. Use commas, colons, semicolons, periods, or parentheses. Also not --.

The AI slop test

If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.

Category-reflex check. If someone could guess the theme and palette from the category name alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the training-data reflex. Rework the scene sentence and color strategy until the answer is no longer obvious from the domain.

Commands

Plus two management commands — pin <command> and unpin <command>, detailed below.

Routing rules

1. No argument — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
2. First word matches a command — load its reference file and follow its instructions. Everything after the command name is the target.
3. First word doesn't match — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.

Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke $impeccable.

If the first word is craft, setup still runs first, but reference/craft.md owns the rest of the flow. If setup invokes teach as a blocker, finish teach, refresh context, then resume the original command and target.

Pin / Unpin

Pin creates a standalone shortcut so $<command> invokes $impeccable <command> directly. Unpin removes it. The script writes to every harness directory present in the project.

Valid <command> is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.

ARGUMENTS: Unify /runs/ and audit.html with the FirstRun landing page (docs/index.html): same light-only Apple-style look, same floating glass nav with logo, same background. Remove Film link and Try it button from the landing nav.

merge it

add a todo here noting this session that i need to add the evals here!! note it well!

but also if i open any other session i want to be reminded of this and get the steps for this well

Update Config Skill

Modify Claude Code configuration by updating settings.json files.

When Hooks Are Required (Not Memory)

If the user wants something to happen automatically in response to an EVENT, they need a hook configured in settings.json. Memory/preferences cannot trigger automated actions.

These require hooks:

• "Before compacting, ask me what to preserve" → PreCompact hook
• "After writing files, run prettier" → PostToolUse hook with Write|Edit matcher
• "When I run bash commands, log them" → PreToolUse hook with Bash matcher
• "Always run tests after code changes" → PostToolUse hook

Hook events: PreToolUse, PostToolUse, PreCompact, PostCompact, Stop, Notification, SessionStart

CRITICAL: Read Before Write

Always read the existing settings file before making changes. Merge new settings with existing ones - never replace the entire file.

CRITICAL: Use AskUserQuestion for Ambiguity

When the user's request is ambiguous, use AskUserQuestion to clarify:

• Which settings file to modify (user/project/local)
• Whether to add to existing arrays or replace them
• Specific values when multiple options exist

Decision: /config command vs Direct Edit

Suggest the /config slash command for these simple settings:

• theme, editorMode, verbose, model
• language, alwaysThinkingEnabled
• permissions.defaultMode

Edit settings.json directly for:

• Hooks (PreToolUse, PostToolUse, etc.)
• Complex permission rules (allow/deny arrays)
• Environment variables
• MCP server configuration
• Plugin configuration

Workflow

1. Clarify intent - Ask if the request is ambiguous
2. Read existing file - Use Read tool on the target settings file
3. Merge carefully - Preserve existing settings, especially arrays
4. Edit file - Use Edit tool (if file doesn't exist, ask user to create it first)
5. Confirm - Tell user what was changed

Merging Arrays (Important!)

When adding to permission arrays or hook arrays, merge with existing, don't replace:

WRONG (replaces existing permissions):

RIGHT (preserves existing + adds new):

Settings File Locations

Choose the appropriate file based on scope:

Settings load in order: user → project → local (later overrides earlier).

Settings Schema Reference

Permissions

Permission Rule Syntax:

• Exact match: "Bash(npm run test)"
• Prefix wildcard: "Bash(git *)" - matches git, git status, git commit, etc.
• Tool only: "Read" - allows all Read operations
• File paths: "Edit(src/**)" - path rules in permissions use Edit(path) for every file-writing tool (Write, Edit, NotebookEdit) and Read(path) for reads. Write(path), NotebookEdit(path) and Glob(path) rules are not matched by file permission checks. Bare tool names ("Write"), deny/ask Tool(param:value) rules and hook if conditions still use each tool's own name

Environment Variables

Model & Agent

Attribution (Commits & PRs)

Set commit or pr to empty string "" to hide that attribution. To hide all of it, set both to "" and also set "sessionUrl": false. Write this object form, not "attribution": false: older Claude Code versions reject true or false here and then skip the whole settings file.

MCP Server Management

Plugins

Plugin syntax: plugin-name@source where source is claude-code-marketplace, claude-plugins-official, or builtin.

Other Settings

• language: Preferred response language (e.g., "japanese")
• cleanupPeriodDays: Days to keep transcripts before automatic cleanup (default: 30; minimum 1)
• respectGitignore: Whether to respect .gitignore (default: true)
• spinnerTipsEnabled: Show tips in spinner
• timeFormat: Clock format for times shown in the UI: "auto" (default), "12-hour", "24-hour", "24-hour-utc", or a strftime pattern such as "%H:%M"
• timeZone: IANA time zone for times shown in the UI, e.g. "UTC" (default: system time zone)
• spinnerVerbs: Customize spinner verbs ({ "mode": "append" | "replace", "verbs": [...] })
• spinnerTipsOverride: Override spinner tips ({ "excludeDefault": true, "tips": ["Custom tip"] })
• syntaxHighlightingDisabled: Disable diff highlighting

Hooks Configuration

Hooks run commands at specific points in Claude Code's lifecycle.

Hook Structure

Hook Events

Common tool matchers: Bash, Write, Edit, Read, Glob, Grep

Hook Types

1. Command Hook - Runs a shell command:

2. Prompt Hook - Evaluates a condition with LLM:

Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.

3. Agent Hook - Runs an agent with tools:

Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.

Hook Input (stdin JSON)

Hook JSON Output

Hooks can return JSON to control behavior:

Fields:

• systemMessage - Display a message to the user (all hooks)
• continue - Set to false to block/stop (default: true)
• stopReason - Message shown when continue is false
• suppressOutput - Hide stdout from transcript (default: false)
• decision - "block" for PostToolUse/Stop/UserPromptSubmit hooks (deprecated for PreToolUse, use hookSpecificOutput.permissionDecision instead)
• reason - Explanation for decision
• hookSpecificOutput - Event-specific output (must include hookEventName):
  • additionalContext - Text injected into model context
  • permissionDecision - "allow", "deny", or "ask" (PreToolUse only)
  • permissionDecisionReason - Reason for the permission decision (PreToolUse only)
  • updatedInput - Modified tool input (PreToolUse only)

Common Patterns

Auto-format after writes:

Log all bash commands:

Stop hook that displays message to user:

Command must output JSON with systemMessage field:

Run tests after code changes:

Constructing a Hook (with verification)

Given an event, matcher, target file, and desired behavior, follow this flow. Each step catches a different failure class — a hook that silently does nothing is worse than no hook.

1. Dedup check. Read the target file. If a hook already exists on the same event+matcher, show the existing command and ask: keep it, replace it, or add alongside.

2. Construct the command for THIS project — don't assume. The hook receives JSON on stdin. Build a command that:

   • Extracts any needed payload safely — use jq -r into a quoted variable or { read -r f; ... "$f"; }, NOT unquoted | xargs (splits on spaces)
   • Invokes the underlying tool the way this project runs it (npx/bunx/yarn/pnpm? Makefile target? globally-installed?)
   • Skips inputs the tool doesn't handle (formatters often have --ignore-unknown; if not, guard by extension)
   • Stays RAW for now — no || true, no stderr suppression. You'll wrap it after the pipe-test passes.

3. Pipe-test the raw command. Synthesize the stdin payload the hook will receive and pipe it directly:

   • Pre|PostToolUse on Write|Edit: echo '{"tool_name":"Edit","tool_input":{"file_path":"<a real file from this repo>"}}' | <cmd>
   • Pre|PostToolUse on Bash: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | <cmd>
   • Stop/UserPromptSubmit/SessionStart: most commands don't read stdin, so echo '{}' | <cmd> suffices

   Check exit code AND side effect (file actually formatted, test actually ran). If it fails you get a real error — fix (wrong package manager? tool not installed? jq path wrong?) and retest. Once it works, wrap with 2>/dev/null || true (unless the user wants a blocking check).

4. Write the JSON. Merge into the target file (schema shape in the "Hook Structure" section above). If this creates .claude/settings.local.json for the first time, add it to .gitignore — the Write tool doesn't auto-gitignore it.

5. Validate syntax + schema in one shot:

   jq -e '.hooks.<event>[] | select(.matcher == "<matcher>") | .hooks[] | select(.type == "command") | .command' <target-file>

   Exit 0 + prints your command = correct. Exit 4 = matcher doesn't match. Exit 5 = malformed JSON or wrong nesting. A broken settings.json silently disables ALL settings from that file — fix any pre-existing malformation too.

6. Prove the hook fires — only for Pre|PostToolUse on a matcher you can trigger in-turn (Write|Edit via Edit, Bash via Bash). Stop/UserPromptSubmit/SessionStart fire outside this turn — skip to step 7.

   For a formatter on PostToolUse/Write|Edit: introduce a detectable violation via Edit (two consecutive blank lines, bad indentation, missing semicolon — something this formatter corrects; NOT trailing whitespace, Edit strips that before writing), re-read, confirm the hook fixed it. For anything else: temporarily prefix the command in settings.json with echo "$(date) hook fired" >> /tmp/claude-hook-check.txt; , trigger the matching tool (Edit for Write|Edit, a harmless true for Bash), read the sentinel file.

   Always clean up — revert the violation, strip the sentinel prefix — whether the proof passed or failed.

   If proof fails but pipe-test passed and jq -e passed: the settings watcher isn't watching .claude/ — it only watches directories that had a settings file when this session started. The hook is written correctly. Tell the user to start a new session so the new settings load. You can't do this yourself.

7. Handoff. Tell the user the hook is live (or needs a new session per the watcher caveat), and that they can review, edit, or disable it later in the settings file you wrote. The UI only shows "Ran N hooks" if a hook errors or is slow — silent success is invisible by design.

Example Workflows

Adding a Hook

User: "Format my code after Claude writes it"

1. Clarify: Which formatter? (prettier, gofmt, etc.)
2. Read: .claude/settings.json (or create if missing)
3. Merge: Add to existing hooks, don't replace
4. Result:

Adding Permissions

User: "Allow npm commands without prompting"

1. Read: Existing permissions
2. Merge: Add Bash(npm *) to allow array
3. Result: Combined with existing allows

Environment Variables

User: "Set DEBUG=true"

1. Decide: User settings (global) or project settings?
2. Read: Target file
3. Merge: Add to env object

Common Mistakes to Avoid

1. Replacing instead of merging - Always preserve existing settings
2. Wrong file - Ask user if scope is unclear
3. Invalid JSON - Validate syntax after changes
4. Forgetting to read first - Always read before write

Troubleshooting Hooks

If a hook isn't running:

1. Check the settings file - Read ~/.claude/settings.json or .claude/settings.json
2. Verify JSON syntax - Invalid JSON silently fails
3. Check the matcher - Does it match the tool name? (e.g., "Bash", "Write", "Edit")
4. Check hook type - Is it "command", "prompt", or "agent"?
5. Test the command - Run the hook command manually to see if it works
6. Use --debug - Run claude --debug to see hook execution logs

Full Settings JSON Schema

User Request

Add a global SessionStart hook that prints a reminder (the neatlogs evals TODO with steps and IDs) at the start of every session in every project, until a done marker file exists.