Metadata-Version: 2.4
Name: agent-thanks
Version: 0.7.0
Summary: Record CLI use, review coding-agent evidence, and thank open source 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)](https://github.com/dbwls99706/agent-thanks/blob/main/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 used in your coding work, then thank them with a Star.**

`agent-thanks` turns coding work into a shortlist of open-source repositories worth thanking. It checks project changes, recorded CLI commands, 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.

## Record your CLI work

Capture a command while you run it, then review the repositories it used:

```bash
agent-thanks exec -- git clone https://github.com/psf/requests.git
agent-thanks thanks --dry-run
agent-thanks thanks
```

`exec` runs the command in the current directory, preserves its terminal input
and output, and returns its exit status. Use `--repo PATH` before `--` to choose
another working/project directory. The private local log records argv and the
actual outcome, so supported successful clone and Git-install commands can
provide verified evidence without `--trust-session`. Output is not recorded.

It captures the outer command you run, rather than tracing its nested
subprocesses. Use agent transcripts to inspect work performed inside a coding
agent. Shell expressions require an explicit shell; uncertain compound actions
remain review-only under the same evidence rules.

Captured records are automatically included in later scans of that project,
including after the work has been committed.

## Review several agent sessions together

```bash
agent-thanks thanks --all-sessions --dry-run
agent-thanks thanks --all-sessions
agent-thanks thanks --all-sessions --from codex
```

`--all-sessions` collects all discoverable transcripts whose recorded project
directory matches the selected project. `--from` limits it to one agent.
Explicit `--session` files can be added too. Duplicate paths and repository
candidates are combined, and conflicting or missing outcomes do not become
verified success. The default remains the newest matching agent transcript,
plus this project's locally captured commands.

## Keep a receipt and undo a batch

```bash
agent-thanks history
agent-thanks history --json
agent-thanks undo --last --dry-run
agent-thanks undo --last
agent-thanks undo --receipt RECEIPT_ID
```

Live Stars save a private receipt before the first request and update it after
each confirmed response. `history` reads those local receipts without contacting
GitHub. `undo` selects only confirmed Stars from a receipt, checks that you are
authenticated as its account, and asks for each repository plus final approval.
Existing Stars skipped during the original batch are not recorded for undo.

Interrupted or timed-out requests can leave an **unconfirmed** outcome. It is
shown as `pending` and excluded from undo because the tool cannot prove what
happened remotely. Confirmed entries from a partial batch remain available
after restarting the command.

Receipts belong to the selected project directory. `thanks --repo PATH` saves
them there. `star report.json` uses the report's directory; hook reports inside
`.agent-thanks/` use the enclosing project. Use `star report.json --project PATH`
to choose explicitly, and pass the same `--repo PATH` to `history` and `undo`.

## Try it safely in 30 seconds

Install the published package:

```bash
pipx install agent-thanks
```

Without `pipx`:

```bash
python -m pip install agent-thanks
```

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="https://raw.githubusercontent.com/dbwls99706/agent-thanks/main/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,
- confirmed actions are saved in account-bound receipts for later review,
- `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.

## Manual and other CLI sessions

Project changes can come from a person or any CLI; newly declared dependencies
are checked the same way. You can also scan a saved terminal log:

```bash
agent-thanks thanks --session terminal.log
```

Plain-text logs do not prove that a command succeeded, so their commands remain
review-only. If you have checked that the commands succeeded, attest to that
explicitly with `--trust-session`. Each eligible repository still requires your
approval before a Star. A URL mentioned in the log is not enough on its own.

## 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 |
| `exec` capture log | Direct CLI commands with matching start and recorded result | High for supported successful repository-use commands |

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.

Go `replace` directives are applied before attributing a dependency; version-specific
replacements stay unresolved without the selected module graph. Renamed
Cargo dependencies use their published package names. Dependencies with Cargo
patches/replacements, uv source overrides, or requirements index/find-links
options stay unresolved when the selected source is uncertain; they are not
silently mapped to the default public upstream. Explicit Git pins and verified
session actions can still provide repository evidence.

This is a manifest and session evidence scan, not a complete audit of installed
packages. Lockfile selection, workspace inheritance, and configuration outside
the scanned manifests are not reconstructed.

## 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](https://github.com/dbwls99706/agent-thanks/blob/main/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 |
| `exec` | The command you choose has its normal network behavior; capture itself stays local |
| `history` / `undo --dry-run` | 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.
Stop hooks prune whole session log files that have not been updated for 30 days.
The cumulative CLI capture file keeps earlier argv entries while it is active;
exec-only workflows do not run hook cleanup. Delete `executions.jsonl` to clear
those captured commands. You can delete local logs at any time.

CLI captures also retain raw argv and live under `.agent-thanks/sessions/`.
Avoid putting secrets directly in command arguments. Star receipts under
`.agent-thanks/receipts/` contain account names, project paths, repositories, and
confirmed/pending states, without credentials or command output. Receipt files
are retained until you delete them, so earlier batches remain reviewable.

## 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](https://github.com/dbwls99706/agent-thanks/blob/main/docs/integrations.md)
- [Usage recipes](https://github.com/dbwls99706/agent-thanks/blob/main/docs/recipes.md)
- [Design and trust model](https://github.com/dbwls99706/agent-thanks/blob/main/docs/design.md)
- [Troubleshooting](https://github.com/dbwls99706/agent-thanks/blob/main/docs/troubleshooting.md)
- [Changelog](https://github.com/dbwls99706/agent-thanks/blob/main/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](https://github.com/dbwls99706/agent-thanks/blob/main/CONTRIBUTING.md). If you find a case where uncertain evidence is promoted to verified use, please report it as a correctness bug.

## License

MIT
