AhaDiff User Guide

1. Quick Start

Install AhaDiff, open the local WebUI in your working folder, and add a provider. Start with two file versions, a saved baseline, or one Markdown document; none needs a Git repository or AI tool integration.

Open your working folder

Open a terminal in the folder where you want to keep your learning history. An ordinary folder works; a Git repository is optional for file, patch, snapshot, and document input. The following command works in macOS/Linux terminals and Windows PowerShell:

AhaDiff opens http://127.0.0.1:8765 and creates local state as needed. In Settings, add a local or remote provider. Remote generation requires an explicit remote privacy mode. Provider setup may send a small probe; previewing file changes does not call an LLM.

Choose what you want to learn from

The same run links these pages together. Save a snapshot explicitly before editing, or choose one Markdown document for a document lesson. Snapshots require an explicit save. PDF ingestion and web-page capture are not available. AI tool integration is optional.

Run artifacts and review state stay in the selected workspace. Provider configuration can stay workspace-local or global.

The storage gate accepts these SQLite builds

Use Python 3.11+ with an accepted SQLite runtime. The SQLite version comes from the Python build used by AhaDiff, not from the installer name.

Check the diagnostics in Quick Start before your first lesson. Inside a Git repository, you can also run ahadiff doctor to confirm your SQLite build clears the gate; it reports the detected version and the required threshold, and fails closed when the build is too old. A higher version number is not automatically accepted. The gate requires SQLite 3.51.3 or newer, or a backported 3.50.4+ / 3.44.6+ build, so 3.51.0-3.51.2 fall below the bar and are not accepted. If the diagnostics flag your build, choose a Python build with a compatible SQLite runtime and recheck it. An installer name or a Windows Python version alone does not establish SQLite compatibility.

1. Serif hero headline: Ship with AI. Learn it back.
2. Drop-cap intro paragraph describing AhaDiff.
3. Latest-lesson and first-run entry points.
4. Right card previews the latest finalized run's lesson outline.

2. Configure a Provider

Open Settings and add a local or remote provider. Choose the API protocol, base URL, and a model your account or local server can use. Select the generation provider and model; the optional judge can use a different pair. A saved configuration is not proof of a working connection, so check the test result before starting a lesson.

A model-limit preview reads local configuration and registry data without contacting the provider. Testing a provider sends a small real request and may incur a charge. Remote generation requires redacted_remote or explicit_remote; the default is strict_local.

Configure from the terminal

The examples below test a provider and save its configuration after a successful probe. Replace the base URL and model placeholders with values from your service. --api-key-env takes an environment-variable name. Keep the key in that variable for later CLI calls, or save it through Settings.

Model limits and thinking

• Model default leaves thinking behavior to the provider. Off requests disabled thinking only on supported models and endpoints. Other models may offer effort levels, an on/off toggle, or no thinking control.
• Leave the output limit empty for Auto. AhaDiff warns when it reduces a value to a known maximum. Unknown or deployment-specific limits stay estimates; a cloud limit does not establish your local server's capacity.
• Generation and judge limits resolve separately. Select a limits profile only when it matches the endpoint you use. If you change models, review any explicit thinking setting before saving.
• Keep shared providers in global configuration if you use several workspaces. A workspace provider with the same alias takes precedence. A model listing confirms its name, not your account's inference access.

Where the key is stored

Paste the key itself into the API Key field in Settings. AhaDiff writes it to the selected scope’s .env and stores only a reference in config.toml. Workspace providers use .ahadiff/.env; global providers use the directory below. Back up global configuration separately from your learning history. Workspace ignore rules keep the key file out of an ordinary git add. Keep key files out of shared archives. A system environment variable with the same name takes precedence.

Leave an existing provider's key field blank to retain its key. Saving a new key can test the connection, but a failed test does not undo the saved configuration; inspect the result. Removing a provider cleans up unreferenced keys using the reserved AHADIFF_ prefix. Do not use that prefix for unrelated entries in the local key file.

On macOS/Linux the key file uses owner-only permissions. On Windows, protect the folder with NTFS permissions. For OS-managed credentials, set api_key_env to an environment variable instead of pasting a key.

3. Run a Learn Session

Prefer the terminal? These CLI modes use the same learning pipeline. File and patch paths must stay inside your workspace; Git modes require a repository. Use --force-learn when you want to study a small exercise.

--since alone vs --since --author

Patch and URL captures carry caveats:

File input, preview, and evidence limits

The browser accepts UTF-8 text files up to 256 KiB each and 512 KiB for a pair. Snapshot files and single Markdown documents keep the 256 KiB limit in both CLI and WebUI. Selecting files keeps drafts in page memory and does not edit the originals. Two .ipynb files retain cell-aware source comparison; AhaDiff does not run their cells. Markdown and structured formats add dedicated anchors where parsing succeeds; SQL and unsupported structures retain explicit line evidence. Weak or unproven states remain when stronger support is unavailable.

Preview changes sends input to the local service, without an LLM call. It displays at most 64 KiB and marks partial display. Display truncation is separate from a capture-limit warning: only the latter means the captured input itself is incomplete. After Start learning, generation follows your chosen local/remote privacy mode and stores the normal run artifacts in .ahadiff/.

Pasted unified diffs have a 64 KiB input limit. Serialized browser requests have a 1 MiB limit, so heavily escaped text can reach the request cap before the file caps. Use the CLI for larger comparison inputs; snapshot and document limits remain fixed. CLI patch and comparison files resolve inside the workspace root; pass --patch - for an externally generated patch.

Save and reuse a local baseline

1. Open Saved snapshot, choose the file before editing, and enter a portable name of at most 80 characters.
2. Select Save baseline locally. The list shows the saved time, size, and readiness; filtering may change the saved content.
3. On a later visit, select Use baseline and choose the file after editing. Preview the comparison, then start learning.
4. To remove a baseline, select Delete snapshot and confirm the named item. Existing runs and source files remain intact.

Copy SNAPSHOT_ID and content_hash from the list. The optional learn hash binds the exact comparison content. Deletion instead requires the record's record_hash and an interactive confirmation:

--yes skips only the interactive prompt for that exact ID/hash. The WebUI always presents a specific deletion confirmation. Corrupt or unsupported records stay unavailable for comparison; records that cannot be safely read have no deletion hash.

Learn from one Markdown document

Choose One Markdown document, select a single UTF-8 .md or .markdown file of at most 256 KiB, preview its original text after filtering, and start learning.

The independent document source stores document.md and section/paragraph anchors. The evidence page displays original lines without add/delete markers; Lesson, Quiz, and Review keep their normal run links. This mode has no diff-spec alignment. Diff Coverage and change-novelty Learnability are N/A / 0/0 and excluded from its overall score; A required coverage check looks for evidence in the document’s body text. If the document contains only headings, the check uses those headings instead. Quoting headings alone does not cover a document that has body text. This mode accepts one local Markdown file; it does not accept PDFs, URLs, or document collections.

Add human review notes

After choosing a change source, optionally fill in Review notes. CLI users can select a local text file:

Notes are limited to 8 KiB of UTF-8 text, filtered as untrusted input, and labeled as auxiliary context. They do not produce evidence locations or replace counterevidence. The run records their use and content hash. Draft text stays out of task retry summaries; editing it invalidates the earlier preview. Do not include credentials.

Read format-specific evidence

The dedicated format index is limited to 4,096 anchors. A large diff can show a partial-index warning while its existing hunk evidence remains usable. A standalone document above this structural limit is rejected, so a partial document is not presented as a complete evidence basis.

Open a claim's source anchor to see its side, location, quote, and hash. Moving or renaming different content does not preserve its evidence identity. Existing runs with only hunk evidence remain readable. A declared new source artifact that is missing, corrupted, or inconsistent is rejected rather than treated as verified text.

Long-running commands show progress in the terminal. Wait for the final run ID before opening the result.

4. Use the WebUI

Run one of these to open the local React SPA. serve opens a browser by default; add --no-browser to keep it headless, or --watch to auto-learn when files change in a Git working tree.

Workflow at a glance

Page map

1. Top stat cards: total runs, avg score, pass rate, concepts, LLM calls.
2. Spec alignment block with score, trend, and evaluated count.
3. Ratchet trajectory line chart of kept vs discarded scores.
4. Review activity heatmap calendar on the right.

Claims and the diff

Open a claim to inspect its source location and evidence status. The five states below describe what AhaDiff could establish from the captured material.

1. Header with PASS score, View score details, Mark as Learned.
2. Compact / Hint / Full detail-level toggle, top right.
3. Left outline rail: TL;DR, What Changed, Claims, Concepts.
4. Right claims summary: verified / weak / not proven counts.

1. Center code diff with red/green added and removed lines.
2. File tabs and Unified / Split view toggle above the diff.
3. Right Claim Inspector panel listing per-claim cards.
4. Claim state badges link the explanation back to code lines.

Attempt active transfer practice

Explicitly enable More options for this source → Active transfer practice in the New Run dialog. It is off by default: normal runs keep the mixed guided/recall/transfer allocation. Enabling it requests only open transfer questions; with at least 3 questions, the quiz covers all three exercise forms. Changing the switch invalidates the preview, and changing the source or closing the dialog resets it.

regenerate replaces this run’s quiz and cards, recomputes the score, and clears the old Judge result. It does not rerun the judge. Without a practice flag it keeps the existing mode; --mixed-practice requests a mixed quiz. Select the run you intend to change. Generation uses your configured provider and privacy mode.

Transfer reuses the existing Quiz and SRS flow: Predict the next step, Complete a similar example, or Explain an error. Write your attempt before revealing the reference. Reference answers, explanations, and evidence stay hidden before that attempt; code is never executed.

Compare meaning with the reference, then choose Completed independently, Needed help, or Not yet. When needed, identify the difficulty: recall, application, reasoning, or evidence boundaries. Equivalent wording can be valid. Choice checking is mechanical; open-exercise feedback is semantic self-assessment.

Written WebUI attempts remain in page memory. Only bounded assessment, error-category, and timing metadata are saved. Review brings back the same cards. Delayed recall requires at least 24 hours since the prior recorded attempt; an unseen-variant first attempt requires a question explicitly marked as a new scenario.

Dashboard shows initial practice, delayed recall, and unseen-variant self-assessments with their own sample counts and error categories. A missing denominator is unmeasured, not a zero-success claim. The older SRS rating-improvement ratio remains separate from these practice measures.

Quiz and review

Review grades each card; the grade drives the next due date.

1. Single multiple-choice question with A/B/C/D options.
2. Guided / Recall / Transfer mode tabs and progress counter.
3. Right Evidence panel locked until you answer.
4. Right Progress list of per-question status (pending).

1. Header counts: cards due, FSRS, at-risk concepts.
2. Review Overview activity heatmap and Concept Mastery list.
3. Needs Practice list with per-concept stability values.
4. New Concepts list marked New on the right.

Concepts

1. Ledger / Graph tabs and Health Status filter counts.
2. Table columns: concept, runs, files, claims.
3. Per-row health tags like Orphan and Contradicted.
4. Run and file links per concept row.

1. Ledger / Graph tabs with a Refresh Graph button.
2. Graphify source card: node/edge counts, FRESH badge, sha256.
3. Community filter chips and All / code / rationale filters.
4. Canvas of graph nodes below with Export JSON, Fit to view.

5. Common Commands

Daily work runs through learn, quiz, and review. The clusters below cover everything else: serving the UI and managing local data.

Daily loop

improve-run RUN_ID regenerates a lesson and keeps the new copy only when the deterministic score strictly improves, saving it as a separate run and leaving the original untouched. Use --candidates N (default 3, range 1-10) to control how many regeneration attempts are tried; a higher value improves the chance of beating the score but costs more tokens and time. It works in any install, including pip. The separate improve command tunes AhaDiff's own generation prompts and only runs inside an AhaDiff source checkout.

Maintenance clusters

Refresh vs learn: what touches Graphify

6. Export & Share

The WebUI provides static previews, TSV/JSON results, and Anki cards. From the CLI, use export-results for TSV or export preview for a local preview:

Static previews preserve the document/diff source, quoted structural anchors, and separately labeled review notes. Read-only MCP exposes source/anchor provenance and bounded auxiliary excerpts. Preserve those distinctions when sharing or consuming either output. A flattened quotation or a review comment must not become runtime proof. Static preview and APKG files contain answers; share them deliberately after checking their contents.

7. Optional Features and Scoring

Choose what each run generates

Optional tools and automation

• Anki export and file watching are included in the standard package. Automatic learning can make repeated provider requests; review privacy and budget settings before enabling ahadiff watch or ahadiff serve --watch in a Git workspace.
• FSRS parameter optimization needs the optional optimizer extra, which installs torch. Base card review and scheduling work without it.
• The repository graph overlay needs a Graphify graph. ahadiff graph refresh imports an existing graph; it does not run Graphify.
• AI tool guidance is optional. Settings previews the exact project files before writing, updating, or removing them. Guide lists the same tools and explains their usage.

Read a run’s score

The deterministic score checks the lesson and its evidence. These are the maximum points for each dimension before excluding dimensions that do not apply:

A run without a specification shows Spec Alignment as N/A. Document runs also show Diff Coverage and change-novelty Learnability as N/A. These dimensions do not lower the overall score; document evidence has its own coverage check.

PASS starts at 80, CAUTION covers 60 to below 80, and FAIL covers scores below 60. A failed required check can still make a high-scoring run FAIL. Open Run Detail → Score to inspect the failed checks and their reasons.

The optional LLM judge adds feedback and cannot override that verdict. If the judge fails, Run Detail shows the failure while retaining the deterministic score. Neither score measures whether you can make a similar change yourself; use your attempts and later recall to assess that.

8. FAQ

9. Platforms and Release Information

Core CLI and WebUI target macOS, Linux, and Windows. Python's SQLite runtime must meet the requirement listed in Quick Start. The following features have explicit platform limits.

See the v1.4.0 release notes for tested platforms, known issues, and downloads. The PyPI package includes the WebUI.

Screenshots and videos illustrate the workflow and may show earlier UI details. Use the written steps and labels in this guide for version 1.4.0.