agent-thanks 0.6.0__tar.gz

agent_thanks-0.6.0/CHANGELOG.md

@@ -0,0 +1,236 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.6.0 - 2026-09-15
+
+- Make `agent-thanks thanks` the primary user workflow. With no explicit
+  `--from` or `--session`, it selects the newest Claude Code, Codex, or Gemini
+  transcript that the existing transcript locator can prove belongs to the
+  current project, then combines that evidence with project changes before the
+  normal interactive Star review. If no matching transcript exists, it scans
+  project changes only instead of guessing.
+- Reframe the product around its intended outcome: find open-source repositories
+  a coding agent actually used and help a person thank verified repositories
+  with GitHub Stars. Provenance and evidence remain the conservative safety
+  layer behind the Star prompt, not the end product.
+- Add a dedicated top-level and `thanks` help experience while keeping `run` as
+  a lower-level compatibility command.
+- Verify the new entry point across Python 3.10 through 3.14, Windows, macOS,
+  built wheels, source distributions, and an installed `thanks --dry-run`
+  smoke flow before release.
+
+## 0.5.1 - 2026-09-03
+
+- Treat a project directory the platform cannot resolve as identifying nothing.
+  A transcript whose recorded directory holds an embedded null byte no longer
+  ends the scan with an error, and it never merges with another file recording
+  the same malformed directory, so one file's recorded success can never speak
+  for a command in another. This holds on every platform: POSIX and Windows
+  disagree about such paths, so they are refused before either is consulted.
+- Ship `examples/session.jsonl` in the source distribution again. The packaging
+  list still named the `examples/*.log` file that 0.5.0 replaced, so source
+  distributions carried no example at all; a release check now fails when the
+  bundled example is missing.
+- Name the evidence source in the README walkthrough after the transcript the
+  documented commands actually scan, instead of a file name no run produces.
+
+## 0.5.0 - 2026-09-03
+
+- Count a session command as verified use only when its own successful
+  completion is recorded: the recorded result must carry an exact success
+  signal and no failure signal, the tool call must be a single logical line,
+  and the statement must be a single command or an `&&` chain whose other
+  segments are trivially safe (`cd`, `mkdir`, `echo`, and similar; `set`,
+  `export`, `printf`, variable assignments, and `env` wrappers with
+  assignments or options are not, because `set -n` skips execution and an
+  assignment can redirect `PATH` to a fake `git`), and every executable must
+  be named without a path. Failed,
+  conflicting, unjudgeable, and missing results, transcripts without results,
+  multi-line invocations, and compound statements such as
+  `git clone URL || true` or `eval 'exit 0' && git clone URL` stay references,
+  and the evidence names the reason.
+- Treat plain-text session logs as review-only by default, because they record
+  no results; `--trust-session` attests that their commands succeeded.
+- Read coding-agent transcripts (JSON and JSON Lines) with `--session`,
+  pairing recognized shell-tool calls in the supported structured formats
+  (Claude Code, Codex CLI, and Gemini CLI records) with their recorded
+  results. Success is read only from the structured field each agent writes,
+  in the position it writes it (a Claude Code `tool_result` inside a user
+  message, a Codex output item paired with a Codex call record of its own
+  `shell` or `exec_command` tool; Gemini has none), only for calls and results
+  at the positions the agent writes them, only for the agent's own shell tool
+  (`Bash` for Claude Code), only after the call it names, only when every
+  item's own role agrees with its record, only when the envelope can be
+  scanned completely and no contradictory or malformed field anywhere in the
+  whole result record blocks the success, and only when every transcript of
+  the same recorded session and project scanned together agrees about the
+  call, never from program output or bare text; every JSON record and
+  JSON-encoded result is parsed rejecting duplicate keys; a transcript with an
+  unparsable line promotes nothing, in any file; provenance prose counts only
+  at an assistant message position; several
+  results for one call combine failure first; a call id reused for different
+  calls, or a call found outside a recognized tool call position, attributes
+  no result; call-shaped objects inside user or tool content are never
+  actions; provenance phrases count in prose only, never inside a command.
+  Only known shell
+  tools count; other tools contribute references. In agent prose only
+  line-initial provenance statements count as use. Tool output, user prompts,
+  and hidden reasoning are never actions.
+- Recognize Codex `exec_command` results, whose exit code is recorded in a
+  header ahead of the program output, and Codex hooks, whose payloads name the
+  shell tool `Bash`. Code-mode `exec` programs yield references only; the
+  hook log covers the calls they make. Gemini CLI yields review-only
+  references, because its
+  shell tool marks success only by the absence of failure signals.
+- Replace the bundled plain-text example with `examples/session.jsonl`, a
+  transcript whose classification matches `agent-thanks demo`.
+- Add `--from claude-code|codex|gemini` to `scan`, `run`, and `hook stop` to
+  locate the transcript whose recorded project directory equals the current
+  one and whose recorded session identifier matches the hook payload exactly,
+  never by file name alone, honoring `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, and
+  to fail rather than guess.
+- Create the `.agent-thanks` state directory and its files readable by their
+  owner only on POSIX, tightening every known file on each run, because hook
+  logs keep raw shell commands; refuse symbolic links and special files
+  anywhere in the state directory for reads and writes alike, write whole
+  files through a private temporary file, and prune only regular files inside
+  it.
+- Add `agent-thanks hook record` and `agent-thanks hook stop`, detection-only
+  entry points for agent hooks. `record` keeps a structured per-session log
+  with each command's recorded status and basis, treating the Claude Code
+  success-only post-tool event as a success basis only when started with
+  `--from claude-code` and only for a `PostToolUse` payload of the `Bash` tool,
+  never recording pre-tool events; a Codex entry is `ok` only for a
+  `PostToolUse` payload of its canonical `Bash` tool with an explicit exit
+  status of 0; a Claude Code `PostToolUseFailure` payload records an error;
+  Gemini has no success contract. Every entry carries a schema marker, the
+  agent, the event, the tool, and the tool call id; a stored success counts
+  only while those fields still form one of the two contracts, and a log with
+  any corrupted line promotes nothing.
+  `stop` treats that log as the authority for actions, combining several
+  entries for one call failure first, overriding the transcript's own result
+  only when call id and exact command text both match and the transcript
+  recorded no failure, leaving mismatches and transcript commands the log
+  never saw unconfirmed (a failure whose call record is missing from a partial
+  transcript still counts), promotes successful entries only, writes
+  per-session reports, and announces newly verified repositories once per
+  session, without ever changing a Star. With `--from codex` or `--from
+  gemini` the hooks answer `{}` when silent, as those hook contracts require.
+- Bundle a Claude Code plugin marketplace with hooks and a `/thanks` command.
+- Scope hook logs, reports, and announcements by the session or thread
+  identifier every supported hook contract carries, or by the transcript path
+  when a payload lacks one; a payload with neither is not recorded and never
+  announced. File names are a sanitized prefix plus a hash of the whole scope,
+  so distinct sessions never share a file. Commands are stored and compared
+  with outer whitespace removed.
+- Document pip and release-wheel installation for environments without `pipx`.
+
+## 0.4.2 - 2026-09-02
+
+- Restore repository detection for editable VCS requirements such as
+  `-e git+https://github.com/owner/repository.git#egg=name`, which 0.4.1 left
+  unresolved.
+- Never map a dependency through PyPI, npm, or crates.io when its manifest pins
+  a Git, URL, local path, workspace, or alternative-registry source. Such
+  dependencies count only when the pinned source itself names a GitHub
+  repository and are otherwise reported as unresolved.
+- Ignore local path requirements such as `vendor/pkg` instead of reading them
+  as GitHub `owner/repository` shorthand.
+- Treat an existing dependency that is repinned to a different repository
+  source as new use of that repository, with evidence that names the source
+  change.
+- Validate evidence confidence and meaningful-use fields when reading a report,
+  and report malformed JSON reports as errors instead of a traceback.
+
+## 0.4.1 - 2026-09-02
+
+- Match high-confidence session evidence to the exact repository targeted by a
+  supported command or provenance phrase, leaving nearby URLs as review-only
+  references.
+- Parse shell options, non-mutating flags, command reachability, comments,
+  document examples, heredocs, and line continuations conservatively so
+  ambiguous session text fails closed.
+- Recognize repository operands in `gh repo clone` and package-manager GitHub
+  shorthand without weakening the per-repository evidence boundary.
+- Require direct, valid GitHub targets in commands and package metadata instead
+  of promoting GitHub text embedded inside unrelated or malformed URLs.
+
+## 0.4.0 - 2026-08-28
+
+- Require a real interactive terminal and a default-No decision for every live
+  Star; the authenticated GitHub account is shown before approval.
+- Check existing Stars before prompting, so one account is not asked to approve
+  the same repository again.
+- Remove persistent `ask`/`auto` configuration and all unattended Star paths,
+  including `--mode`, `--yes`, and `--all --yes`.
+- Make low-confidence and viewed-only references ineligible for Star even when
+  requested explicitly with `--repo`.
+- Keep detection, JSON reports, review, Markdown export, demo, and dry-run
+  workflows non-interactive and free of Star mutations.
+- Add `agent-thanks export` for deterministic, shareable Markdown evidence with
+  optional review-only references and sanitized absolute source paths.
+- Require interactive confirmation for Unstar operations and preserve exact Undo
+  receipts for new Stars and partial failures.
+- Ignore legacy 0.3.x consent configuration safely and document migration to
+  evidence-only automation.
+- Align README, design notes, recipes, troubleshooting, terminal visuals, CI,
+  and package metadata with the new human-confirmation invariant.
+- Publish wheel and source distributions with SHA-256 checksums in the GitHub
+  Release workflow.
+
+## 0.3.1 - 2026-08-28
+
+- Add `agent-thanks demo`, a credential-free and network-free preview of the
+  evidence, review, and dry-run experience.
+- Verify the demo from the built wheel in CI.
+- Clarify the task-level positioning relative to whole-project dependency
+  starring tools.
+- Document that `ATTRIBUTION.md` v0.1 parsing is planned rather than currently
+  implemented, and that its `mode: suggest` requires per-repository consent.
+
+## 0.3.0 - 2026-08-27
+
+- Prevent renamed or relocated manifests from making existing dependencies look
+  newly introduced.
+- Compare dependency changes against the full Git baseline so a dependency
+  moved between manifests is not recommended twice.
+- Keep dry-run operations completely detached from GitHub authentication.
+- Add live-compatible coverage for missing credentials and GitHub 401, 403, and
+  404 failures without reporting false success.
+- Add `agent-thanks doctor` to verify Python, Git, project state, consent mode,
+  and the authenticated GitHub account before the first Star.
+- Check existing Star state so repeated runs report `Already starred` without
+  claiming a new mutation.
+- Print an exact one-command Undo receipt for every newly completed batch,
+  including API and network failures after partial progress.
+- Add direct Go module and Git submodule detection.
+- Recognize bare `github.com/owner/repository` references in agent transcripts.
+- Test Python 3.10 through 3.14 plus Windows and macOS smoke environments.
+- Add a 60-second onboarding path, usage recipes, troubleshooting guidance,
+  an accessible terminal walkthrough, and a GitHub social preview.
+
+## 0.2.0 - 2026-08-26
+
+- Add persistent `ask` and `auto` consent modes with interactive first-run setup.
+- Add `agent-thanks config` for setting, changing, and inspecting consent policy.
+- Add `agent-thanks run` to scan and apply the selected policy in one command.
+- Add per-run `--mode ask|auto` overrides that do not mutate saved settings.
+- Make every prompt in `ask` mode default to No and retain final batch approval.
+- Restrict `auto` to verified meaningful-use candidates; viewed-only and
+  low-confidence references remain unstarred.
+- Save configuration atomically with owner-only POSIX permissions.
+- Add safe non-interactive error handling and Ctrl-C cancellation.
+- Expand the test suite for setup, persistence, overrides, and both consent modes.
+- Add issue forms, pull request guidance, security policy, code ownership, and
+  dependency update configuration for the public repository.
+
+## 0.1.0 - 2026-08-26
+
+- Add Git-aware dependency scanning for Python, Node.js, and Rust manifests.
+- Add agent-session GitHub repository detection with meaningful-use evidence.
+- Add PyPI, npm, and crates.io repository metadata resolution.
+- Add review, consent-gated star, dry-run, and unstar commands.
+- Add Python 3.10–3.13 test workflow and standard-library test suite.

agent_thanks-0.6.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of conduct
+
+## Our standard
+
+This project welcomes people of every background and experience level.
+Participants are expected to communicate respectfully, discuss technical
+decisions in good faith, and give actionable feedback without personal attacks.
+
+Harassment, discrimination, intimidation, doxxing, sexualized conduct, and
+deliberate disruption are not acceptable in issues, pull requests, discussions,
+or other project spaces.
+
+## Enforcement
+
+Project maintainers may edit or remove inappropriate content and may temporarily
+or permanently restrict participation when necessary to protect the community.
+Enforcement decisions should be proportionate, documented privately, and
+focused on maintaining a constructive environment.
+
+## Reporting
+
+Report conduct concerns privately through the repository owner's GitHub profile.
+Do not publish private information about another person while reporting an
+incident. Reports will be reviewed fairly and kept confidential to the extent
+practical.

agent_thanks-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Thanks for helping make AI-assisted open-source acknowledgment more accurate
+and less noisy.
+
+## Local setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## Detection changes
+
+A detector should be conservative. Pull requests that add a new high-confidence
+signal should include:
+
+- A positive test showing substantive use.
+- A negative test showing a nearby but non-meaningful reference.
+- A clear evidence message suitable for human review.
+- No hidden network calls or account mutations during `demo`, `scan`, `review`,
+  or `export`.
+
+New account mutations must preserve the per-repository interactive-confirmation
+invariant and provide a reversal path where the platform supports one. Star
+mutations must never gain an unattended, bulk, or piped-confirmation path.
+
+## Pull requests
+
+Keep changes focused and include tests. Explain false-positive and
+false-negative tradeoffs for detection logic.

agent_thanks-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yujin Hong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_thanks-0.6.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+include SECURITY.md
+include SUPPORT.md
+recursive-include docs *.md *.png *.svg
+recursive-include examples *.jsonl

agent_thanks-0.6.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: agent-thanks
+Version: 0.6.0
+Summary: Find open-source repositories used by coding agents and thank them with human-approved GitHub Stars.
+Author: Yujin Hong
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dbwls99706/agent-thanks
+Project-URL: Changelog, https://github.com/dbwls99706/agent-thanks/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/dbwls99706/agent-thanks#readme
+Project-URL: Issues, https://github.com/dbwls99706/agent-thanks/issues
+Project-URL: Source, https://github.com/dbwls99706/agent-thanks
+Keywords: ai-agents,coding-agents,github,github-stars,open-source,open-source-sustainability,provenance,attribution,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Dynamic: license-file
+
+# agent-thanks
+
+[![Tests](https://github.com/dbwls99706/agent-thanks/actions/workflows/tests.yml/badge.svg)](https://github.com/dbwls99706/agent-thanks/actions/workflows/tests.yml)
+[![Python 3.10-3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+<a href="https://smollaunch.com" target="_blank" rel="noopener"><img src="https://smollaunch.com/badges/featured.svg" alt="agent-thanks - Featured on Smol Launch" loading="lazy" width="150" height="36"></a>
+
+**Find the open-source repositories your coding agent actually used, then thank them with a Star.**
+
+`agent-thanks` turns one AI coding task into a trustworthy shortlist of open-source repositories worth thanking. It checks project changes and coding-agent activity, shows the evidence behind each match, then asks you before every GitHub Star.
+
+The evidence engine is the safety layer. **The product goal is simple: make it easy to notice the open source your agent relied on and leave a visible thank-you.**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dbwls99706/agent-thanks/main/docs/assets/agent-thanks-banner.svg" alt="AI: done in 12 seconds. Open source: 12 years in the making. Leave a star." width="900">
+</p>
+
+## One command after the coding task
+
+Authenticate to GitHub once:
+
+```bash
+gh auth login
+```
+
+Then, after an AI coding session:
+
+```bash
+agent-thanks thanks
+```
+
+`thanks` tries to find the newest Claude Code, Codex, or Gemini transcript that belongs to the current project. It combines that activity with the Git diff, writes a report, shows which repositories have verified evidence, and asks whether you want to Star each eligible repository.
+
+If no matching transcript exists, it still scans project changes such as newly declared dependencies and submodules.
+
+Want to see exactly what would happen first?
+
+```bash
+agent-thanks thanks --dry-run
+```
+
+Typical flow:
+
+```text
+AI coding task
+      |
+      v
+find OSS touched by the task
+      |
+      v
+verify evidence
+   /      \
+verified  review-only
+   |          |
+   |          +--> shown, never Star-eligible
+   v
+ask you: Star this repository? [y/N]
+      |
+      v
+final confirmation
+      |
+      v
+GitHub Star
+```
+
+No unattended Star mode exists. A Star always requires an interactive terminal and an explicit human decision.
+
+## Try it safely in 30 seconds
+
+Install from GitHub:
+
+```bash
+pipx install git+https://github.com/dbwls99706/agent-thanks.git
+```
+
+Without `pipx`:
+
+```bash
+python -m pip install "https://github.com/dbwls99706/agent-thanks/archive/refs/heads/main.zip"
+```
+
+Then run the built-in demo:
+
+```bash
+agent-thanks demo
+```
+
+The demo makes no network requests, reads no credentials, writes no files, and changes no Stars.
+
+Example:
+
+```text
+[verified | high] https://github.com/BehaviorTree/BehaviorTree.CPP
+  - Session ran a repository-use command that completed successfully
+
+[review | low] https://github.com/example/reference-only
+  - Repository was referenced in the session; verify actual reuse
+
+Would star: https://github.com/BehaviorTree/BehaviorTree.CPP
+```
+
+<p align="center">
+  <img src="docs/assets/terminal-walkthrough.svg" alt="Terminal walkthrough showing the detect, inspect, approve, and thank flow." width="900">
+</p>
+
+## Why the evidence step exists
+
+A coding agent can mention a repository without using it. A clone can fail. A shell command can hide a failure behind `|| true`. A transcript can be incomplete or contradictory.
+
+Automatically Starring every repository URL would make the tool noisy and the Star itself less meaningful. `agent-thanks` therefore separates **finding candidates** from **proving enough to offer a Star**.
+
+A plain URL is a reference. A verified candidate needs stronger evidence.
+
+| Evidence | Result | Star eligible? |
+| --- | --- | --- |
+| Newly declared direct dependency | Verified use | Yes |
+| Clone, submodule, or Git install command with recorded success | Verified use | Yes |
+| Explicit provenance statement such as `Adapted from ...` | Verified use | Yes |
+| GitHub URL that merely appeared | Review only | No |
+| Command with missing, conflicting, or failed result | Review only | No |
+| Package that cannot be mapped to a repository | Unresolved | No |
+
+The classifier is deterministic. It does not call another model to decide whether a repository deserves a Star.
+
+## Human-approved means human-approved
+
+For live Stars, `agent-thanks` intentionally makes automation stop before the social action:
+
+- the authenticated GitHub account is shown first,
+- existing Stars are detected and skipped,
+- each new repository gets its own default-No `y/N` prompt,
+- review-only candidates cannot be promoted with a flag,
+- there is no approve-all or unattended Star mode,
+- a final confirmation is required before mutations,
+- partial failures print an exact undo command,
+- `unstar` can revoke Stars created by mistake.
+
+This keeps the useful automation while preserving the meaning of a GitHub Star.
+
+## Choose the agent explicitly when needed
+
+Auto-detection is the normal path, but explicit sources are available:
+
+```bash
+agent-thanks thanks --from claude-code
+agent-thanks thanks --from codex
+agent-thanks thanks --from gemini
+```
+
+Or provide a transcript directly:
+
+```bash
+agent-thanks thanks --session path/to/session.jsonl
+```
+
+For work that is already committed, point `--base` to the revision immediately before the task:
+
+```bash
+agent-thanks thanks --base HEAD~1 --from codex
+```
+
+`run` remains available as the lower-level compatibility command. Unlike `thanks`, it does not auto-detect a coding agent.
+
+## Read-only workflows
+
+You can use the evidence engine without ever authenticating to GitHub.
+
+Create a report:
+
+```bash
+agent-thanks scan --repo . --base HEAD --from claude-code
+```
+
+Review it:
+
+```bash
+agent-thanks review .agent-thanks-report.json
+```
+
+Export verified use as Markdown:
+
+```bash
+agent-thanks export .agent-thanks-report.json --output OPEN_SOURCE_USE.md
+```
+
+Include review-only references in a separate section when useful:
+
+```bash
+agent-thanks export .agent-thanks-report.json \
+  --include-low-confidence \
+  --output OPEN_SOURCE_USE.md
+```
+
+The Markdown export removes absolute local directory prefixes and is suitable for a PR description, release note, audit record, or internal review.
+
+## What it can detect
+
+| Source | Coverage | Evidence level |
+| --- | --- | --- |
+| `requirements*.txt`, `pyproject.toml` | Python direct dependencies | High |
+| `package.json` | npm direct dependencies | High |
+| `Cargo.toml` | Rust direct dependencies | High |
+| `go.mod` | Direct Go modules | High |
+| `.gitmodules` | GitHub submodules | High |
+| Claude Code transcript / hooks | Repository-use commands and provenance prose | High when success is explicit |
+| Codex transcript / hooks | Repository-use commands and provenance prose | High when success is explicit |
+| Gemini transcript | Repository references and provenance review | Command success is review-only today |
+| Plain-text log | Commands without machine-verifiable results | Review-only unless `--trust-session` is supplied |
+
+Supported repository-use commands include Git clone and submodule operations plus Git-based installs through pip, uv, npm, pnpm, Yarn, Cargo, and Go tooling.
+
+Package names from PyPI, npm, and crates.io can be mapped through public registry metadata. `--offline` disables those lookups. GitHub-hosted Go modules, submodules, and direct Git URLs can resolve locally.
+
+## Coding-agent integrations
+
+### Claude Code
+
+The repository is also a Claude Code plugin marketplace:
+
+```text
+/plugin marketplace add dbwls99706/agent-thanks
+/plugin install agent-thanks@agent-thanks
+```
+
+The plugin records supported shell events and announces newly verified open-source use after a completed turn. `/thanks` shows the current evidence. The plugin itself never authenticates to GitHub or creates a Star. Approval happens in your terminal.
+
+### Codex and Gemini
+
+Codex hooks and Gemini `AfterAgent` integration are supported. Exact setup, transcript lookup behavior, and agent-specific limitations are documented in [Coding-agent integrations](docs/integrations.md).
+
+## Privacy
+
+| Operation | Network behavior |
+| --- | --- |
+| `demo` | None |
+| Transcript scan | Transcript contents stay local |
+| Package resolution | Sends package names to PyPI, npm, or crates.io unless `--offline` is used |
+| `review` / `export` | None |
+| `doctor` | Checks the authenticated GitHub account |
+| Live Star / Unstar | Uses the GitHub API for the repositories you explicitly approve |
+
+Hook logs live under `.agent-thanks/` and are ignored by their own `.gitignore`. On POSIX, state directories and files are tightened to owner-only permissions. Symbolic links are refused in the private state path.
+
+Logs can contain raw shell commands, including secrets typed into commands. They are pruned after 30 days and can be deleted at any time.
+
+## What a Star means here
+
+A Star is a small, visible thank-you. It is not payment, legal attribution, license compliance, or a claim about authorship.
+
+`agent-thanks` also does not try to identify model-training sources, invisible influence from model weights, every transitive dependency, or semantic similarity inferred by another model. It only acts on observable evidence from the project and the supplied coding-agent activity.
+
+## Design principles
+
+**Thank first.** The end goal is to help people notice and thank open-source maintainers.
+
+**Evidence before the prompt.** A repository must earn its place in the Star prompt through observable evidence.
+
+**Fail closed.** Missing or contradictory success information never becomes verified use.
+
+**Keep Stars human.** Detection can be automated. The GitHub Star cannot.
+
+**Explain every candidate.** The report says why each repository was found and why it is or is not eligible.
+
+## Documentation
+
+- [Coding-agent integrations](docs/integrations.md)
+- [Usage recipes](docs/recipes.md)
+- [Design and trust model](docs/design.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Changelog](CHANGELOG.md)
+
+## Status
+
+`agent-thanks` is alpha software. Coding-agent transcript formats are still changing, so the evidence rules intentionally prefer a missed candidate over an unjustified Star prompt.
+
+The current implementation is heavily tested across Python 3.10 through 3.14 and Windows, macOS, and Linux CI. Contributions that add real transcript fixtures, new ecosystem resolvers, and adversarial cases are especially useful.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). If you find a case where uncertain evidence is promoted to verified use, please report it as a correctness bug.
+
+## License
+
+MIT