Claude Code integration

💡 For the generic version (any git workflow, not just Claude Code), see Generic git hooks.

This is the feature Vibstr was built around. Every other tracker treats your build as an external system that occasionally gets a webhook. Vibstr treats the build as the closing event for items — the moment code went live, items close, the changelog writes itself.

Setup is three clicks. Copy the master snippet from Settings → PROJECT → Connect Claude Code. Paste into your Claude Code chat. Tell Claude: Add this to my CLAUDE.md. After that, every build prompt drives the loop automatically — Claude plans first, derives items, builds them, commits with closes #NN, and reports the build back to Vibstr.

Why this matters

You are coding with Claude. You ask it to fix three bugs. It writes the patches, runs the tests, commits, pushes. In every other tracker that closes the loop, you context-switch to a tab, find the three issues, click "close" three times, paste in a comment about which build closed them, and try to remember the version string. Then you forget.

In Vibstr the loop closes itself:

Claude posts the build report to your project's ingest endpoint (it knows to, because the master snippet is in your CLAUDE.md).
Vibstr parses the commit message for closes #42, fixes #58, #101 style references and closes those items deterministically with no AI credit charge.
If there are open items not referenced in the commit, Claude Sonnet reads the build output and matches semantically — "looks like Claude actually fixed the login redirect bug too" — and closes those.
The build card on the Builds tab shows the commit hash, the prompt, the output, the changelog, and a stats line: 4 items closed (commit: 3, AI: 1).

The deterministic path always works, even when you have hit the AI daily limit. The semantic path is a bonus.

2-minute setup: copy this, paste into Claude Code, tell Claude to add it to CLAUDE.md

Open the app, click your avatar → Settings → pick the project → Connect Claude Code. The pane shows:

A connection status line (green check + "Connected" if any builds have been ingested, grey "Not connected yet" otherwise)
A short intro paragraph + an "after that:" bullet list of what Claude will do automatically once the snippet is in your CLAUDE.md
A code-block preview of the master snippet (mono, scrollable)
One primary button: Copy CLAUDE.md snippet — sets up the full automation loop
An expandable "What happens next?" disclosure (collapsed by default) with the per-step mechanics for curious minds
A deep dive link to this page
An API key card collapsed below (reveal / copy / regenerate)

Three clicks gets you set up:

Click Copy. The snippet is on your clipboard, with your project's API key already embedded — no placeholder substitution required.
Paste into Claude Code. Open the chat, paste.
**Tell Claude: Add this to my CLAUDE.md.** Claude reads the snippet, recognises it as workflow instructions plus a per-project tailored plan prompt plus a build-report curl recipe, and merges it into your CLAUDE.md (or AGENTS.md, or whatever it reads at session start).

Done. From here on Claude internalises the workflow contract. Every time you ask Claude for a build, it plans first, sends the plan to vibstr-plan-create with derive_items: true, builds the items, commits with closes #NN references, and runs the build-report curl after every commit and push. You don't have to remember any of it — Claude does.

The API key is a UUID stored on vibelog_projects.api_key. It is per-project, not per-user. Treat it like a webhook secret — anyone who has it can post a build to your project. Regenerate it the moment a contractor leaves.

What happens after that

Make a real commit with a real closes # reference. For example, if item #42 is "Login redirect goes to wrong URL after timeout":

git commit -m "Fix login redirect after timeout — closes #42"
git push

Claude runs the build-report curl automatically. Within a second or two:

A new build appears in the Builds tab as the hero card.
The hero card shows: Latest build: v1.4.3 · <relative time>, the theme line (the first non-empty 80 characters of the prompt), and the stats line 1 item closed (commit: 1, AI: 0).
Item #42 vanishes from your Open filter and shows up in the next build group on Done.
The activity log on item #42 records "Closed in build v1.4.3 (via commit message)".

That is the whole loop. No clicks on your side after the initial paste.

How the `#NN` parser works

The parser is deliberately strict and deliberately small. It runs in the vibelog-ingest edge function before any AI is called.

What matches:

closes #42, fixes #42, resolves #42 (case-insensitive, any of the three verbs)
A bare #42 anywhere in the commit message
Multiple references in one commit: closes #42, fixes #58, #101 closes all three

What does not match:

#42 inside a code block or backticks (we strip those first)
#42 that does not correspond to any open or checking item (silently skipped — no fake closures)
#42 already closed (deduped — the parser will not double-close)

The match runs against vibelog_items.item_number (your #001, #002, etc.), not the database id. Item numbers are project-scoped, so two projects can both have #42 and the parser will pick the right one based on the project's API key.

This costs zero AI credits. It is a Postgres IN (...) query. Run as many builds as you like — the deterministic close path is rate-limit-free.

How the AI semantic match works

If your build did more than your commit message admits, the AI catches the rest. After the deterministic parser runs, Claude Sonnet 4 receives:

Your build's output field (the agent's own summary of what changed)
The list of remaining open / checking items in this project (max 200)

…and responds with a JSON list of { item_id, fix_summary } matches. Each match closes the item, links it to the build, and records "Closed in build v1.4.3 (AI semantic match)" in the activity log.

This path costs one AI call per build, regardless of how many items it matches. Burning through your trial AI budget ($1 USD covers ~100 typical Haiku calls during the 14-day trial; 0 platform AI post-trial unless you BYO Anthropic key) does not break ingest — it just skips the semantic step. You can re-run the match manually later from the Builds tab via the Paste Output action.

The Builds tab hero card shows the breakdown:

Latest build: v1.4.3 — 4 items closed (commit: 3, AI: 1)

Hover the stats line to see the per-item match source. The 1.10.1 release added a hover_match_source feature flag for chris-only debugging; the public stats line ships in 1.10.x.

Optional: GitHub repo linking

If your project has vibelog_projects.github_repo set (1.9.7 onwards — Settings → project → GitHub), every commit hash in the Builds tab becomes a clickable link to GitHub, every #NN reference in a build's commit message becomes a clickable link to the item drawer in Vibstr, and every commit-closed item gets a backlink to the GitHub commit that closed it.

The format is owner/repo (no https://github.com/ prefix). It is a per-project setting because most teams use Vibstr across multiple repos.

The full GitHub linking deep-dive lands in Phase 8 / 1.12.x docs when the public changelog ships alongside it.

Troubleshooting

The curl returns { "ai_matched": false }. That means you are out of AI credits for the day. Your build was still stored. Items referenced via #NN still closed. Open the Paste Output modal in the app to manually re-run the semantic match against the same output, no extra ingest call needed.

The curl returns 401. Your API key is wrong, your key was regenerated, or you are POSTing to a project that has been deleted. Settings → PROJECT → Connect Claude Code → copy the snippet again. The fresh snippet embeds the current key.

The curl returns 200 but no items closed. Either your commit message has no #NN references AND the AI semantic match found no plausible candidates, or your items are in done status already. Check the Builds tab — your build is still there with the prompt and output, just no closures attached.

The build shows up but the version says unknown. The shell expansion node -p ... failed because there is no package.json. Hard-code the version in the curl, or wire it to whatever your project uses for versioning.

What is next

The deterministic-and-semantic-match-on-top architecture is half the loop. The other half is what we use to plan the work that generates those commits in the first place: a markdown plan that derives items.

Read about Plans →