Docs / Alpha

yakcc v0.5.0-alpha — tester guide

Welcome. You’re early. This document tells you what we’re testing, what’s known broken, and how to send feedback so we can iterate fast.

This is not the end-user walkthrough — that lives at docs/USING_YAKCC.md. Read that first; this file adds the alpha-specific context.

What this alpha is

v0.5.0-alpha.0 is the first version of yakcc anyone outside the core team has used. The flywheel works — every Claude Code / Cursor session you run can hit registry atoms (registry-hit), pass through your own emission (passthrough), or atomize your novel code into the local registry for future sessions (atomized). The corpus grows as you use it.

What we’re testing:

  1. The walkthrough is honest. Following docs/USING_YAKCC.md end-to-end should produce the experience it describes, without you having to read source or dig in Discord. If it doesn’t, that’s the most important bug class.
  2. The flywheel is real. Atomize an emission once, see it surface in the next session’s yakcc query. If the round-trip is silent or surfaces wrong atoms, we need to know.
  3. The cost story holds. On the auto_accept / followed path (when yakcc_resolve returns a high-confidence match), hooked Claude/Cursor produces fewer output tokens than unhooked, at equal-or-better quality — B4-v5 measured 91% oracle pass under auto_accept. In raw aggregate the win is coverage-gated (auto_accept coverage 56–72% against the 6-atom corpus today); the gap closes as your corpus grows. Telemetry captures the data; we’ll ask for snapshots.
  4. Cold-start is tolerable. Even with the bundled yakcc corpus (yakcc seed --yakcc), early sessions on your code may see lots of synthesis-required. That’s expected; what matters is whether it improves week-over-week as your personal corpus grows.

What we are not testing in this alpha:

Install (alpha-specific)

Primary install: clone from monorepo. This is the only path that gives every platform a working yakcc today.

git clone https://github.com/cneckar/yakcc.git ~/.yakcc-cli
cd ~/.yakcc-cli
git checkout v0.5.0-alpha.0    # pin to the alpha tag
pnpm install --frozen-lockfile
pnpm -r build
export PATH="$HOME/.yakcc-cli/packages/cli/dist:$PATH"
yakcc --version    # confirm

Optional secondary: build a standalone binary locally (Linux x64 only today — macOS and Windows arrive with #361 Slice 2). This is the Slice-1-of-#361 output; a downloadable GitHub Release artifact is not yet available.

# inside ~/.yakcc-cli (already cloned above)
pnpm --filter @yakcc/cli build:binary
# produces packages/cli/dist/yakcc-bin
cp packages/cli/dist/yakcc-bin ~/bin/yakcc    # or any dir on your PATH
yakcc --version    # confirm

Coming soon: downloadable binaries via GitHub Releases and multi-arch support land with #361 Slices 2-3.

Then in your own project:

cd ~/my-project
yakcc init    # creates .yakcc/, .yakccrc.json, auto-detects + wires IDE hooks, seeds the bootstrap corpus

yakcc init is a single command (per DEC-CLI-INIT-002): it detects your installed IDEs (Claude Code, Cursor, Cline, Continue.dev), wires each hook, and seeds the yakcc bootstrap corpus (~4k atoms) in one step. No separate yakcc seed --yakcc call is needed.

Open Claude Code (or Cursor) in the project. Ask it to do real work. Watch the hook fire.

Known platform notes

Known broken / known limited

Things we know about, in priority order. You will hit some of these. That’s the point of the alpha.

WhatStatusIssue
Substitution-integration: 4 specific test cases failUnder triage; classifying which (if any) hit real-world usage#365
Bootstrap perf: schema v9 write path 30+min vs prior 5minFix in flight, lands within ~3 hours of investigation#377
Windows yakcc init may no-opUnder investigation; #274 fix may be incomplete#385
Standalone binary Slice 1 shipped (#361, local Linux x64 build only); multi-arch download via GitHub Releases pending Slices 2-3Slices 2-3 in flight#361
No global registry peer (yakcc.dev) yetPost-v0 by design; alpha = your local corpus + yakcc seed#371
Codex CLI hook not wiredDeferred to v0.5+ on demand#220 (closed not-planned)
Recursive self-hosting proof not yet greenSurgical fix in flight; load-bearing for v2 narrative not v0 use#355
Shave cache (--verify flag for byte-identical) not yet builtDaily-UX improvement; v0.5+#363

If you hit something not on this list, that’s the bug we want to hear about.

How to send feedback

GitHub issues are the official channel. Use the alpha-feedback issue template:

https://github.com/cneckar/yakcc/issues/new?template=alpha-feedback.md

The template asks for:

The telemetry sample is the most useful diagnostic we have. Please include it. It’s local-only, never leaves your machine until you paste it into a GitHub issue.

Note: telemetry lives in ~/.yakcc/telemetry/ (your home dir), not in <project>/.yakcc/. Run yakcc telemetry --path to confirm the location. See docs/USING_YAKCC.md §4d for the full two-directory layout explanation.

Triage SLA

We’re not promising hotfixes for cosmetic issues. We are promising to read every report.

What’s in this alpha (one-paragraph CHANGELOG)

v0.5.0-alpha.0 ships:

What’s next (post-alpha-0 trajectory)

We’ll cut a new alpha tag for each substantive fix wave. Pin to a specific tag in your install instructions; we’ll announce when to move forward.

How to contribute

The most impactful thing you can do as an alpha tester, beyond filing bugs, is run the B3 cache-hit sprint — a structured 3+3+3 day experiment that measures the real-world registry-hit rate on your own code. The protocol is self-contained:

Thank you

You’re testing software whose primary value-proposition is “every session grows the corpus, and the corpus saves you tokens on the auto_accept path.” That value emerges over time, not on day 1. Your feedback during the awkward early period is what lets us reshape the rough edges before public launch.

We owe you working software in return. If something is broken in a way that wastes your time, tell us — that’s the most useful signal we can get.