Metadata-Version: 2.4
Name: reasonwork
Version: 0.6.0
Summary: Reasonwork CLI: safely contribute Codex, Claude Code, and Cursor trajectories to Reasonwork.
Author: ReasonworkAI, Inc.
License-Expression: LicenseRef-Proprietary
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: worker
Requires-Dist: boto3>=1.35; extra == "worker"
Requires-Dist: litellm>=1.50; extra == "worker"
Requires-Dist: supabase<3,>=2.0; extra == "worker"
Dynamic: license-file

# Reasonwork — CLI + Claude Code plugin

Turn your Claude Code, Codex, or Cursor CLI sessions into reviewed, priced, paid contributions to Reasonwork — automatically, with privacy checks running locally before anything ever leaves your machine.

Your dashboard, settings, and token creation all live on the Reasonwork web app — sign in there to get started and to check your own submissions.

## Requirements

- macOS, Linux, or Windows — the CLI and the background auto-sync timer (`reasonwork schedule`) are all cross-platform.
- Python 3.12+.
- `pip`, `pipx`, or `uv` for installing the CLI.
- Claude Code, if you want the plugin (hooks + slash commands) instead of running the CLI by hand.
- Codex, if you want the Codex hook + skill.
- A current Cursor release, if you want the Cursor hook + skill.
- A Reasonwork account and an `nxc_…` contributor token, created from your account's settings page.

## 1. Install the CLI

```bash
python -m pip install reasonwork
reasonwork --help
```

### Updating

```bash
reasonwork update
```

Detects how you installed it (pip/pipx/uv tool, or an editable install from a git checkout) and upgrades accordingly.

## 2. Log in

Create a contributor token from your account's settings page, then store it locally:

```bash
reasonwork login --token nxc_xxxxxxxx
```

The token is restricted to the current user with mode `0600` on macOS/Linux or a user-only ACL on Windows. Use `login --dry-run` to verify a token without writing it.

## 3. Install the Claude Code plugin (recommended)

The plugin is what makes this hands-off: it hooks into Claude Code's session lifecycle so you don't have to remember to run `sync` yourself. It isn't published to a public marketplace — ask your Reasonwork contact for the marketplace source to add.

Once installed, it wires up:

| Hook | Fires on | What it does |
|---|---|---|
| `SessionEnd` | Every Claude Code session (and subagent) ending | Refreshes the local session index (`scan`). If `sharing_mode=all`, also runs `sync --yes` in the background to submit anything new. Never blocks session exit, never errors if the CLI isn't installed. |
| `SessionStart` | Every new session | If `sharing_mode=ask`, checks for pending unsynced sessions and nudges you. Uploads nothing on its own. |

And two slash commands: `/exchange-status` (read-only summary of your sharing settings and pending sessions) and `/exchange-sync` (shows exactly what would be submitted, asks for confirmation, then submits only if you confirm).

## 4. Codex and Cursor (optional)

Both integrations use the same installed Python hook entry point on macOS, Linux, and Windows. Their installers copy skills instead of creating symlinks, so Windows Developer Mode and administrator privileges are not required.

## Turning on auto-capture (`sharing_mode`)

| Mode | Behavior |
|---|---|
| `none` | Nothing is scanned or submitted automatically. Manual `upload`/`sync` still works if you run it yourself. |
| `ask` *(default)* | Sessions are indexed locally, but nothing uploads without you confirming. |
| `all` | Full auto-capture: every session, at `SessionEnd`, is scanned and synced automatically — no prompt. |

```bash
reasonwork config set --sharing-mode all
reasonwork config exclude --source codex        # exclude a source or --path, add --remove to undo
reasonwork config show                          # check current settings
```

### Optional: scheduled background sync outside of Claude Code

```bash
reasonwork schedule install --interval-minutes 30
reasonwork schedule status
reasonwork schedule uninstall
```

## CLI commands

| Command | Purpose |
|---|---|
| `reasonwork login --token nxc_…` | Verify and store your contributor token. |
| `reasonwork scan` | Discover local Claude Code/Codex/Cursor sessions and show metadata-only checks. Never uploads. |
| `reasonwork sync` | Submit every newly discovered, consented session not already recorded in the local ledger. |
| `reasonwork upload --path … --source … --confirm-rights` | Manually run the safety checks and upload a single specific file. |
| `reasonwork config show / set / exclude` | Inspect and adjust local sharing consent. |
| `reasonwork schedule install / status / uninstall` | Manage the optional background sync timer (macOS/Linux/Windows). |
| `reasonwork update` | Upgrade to the latest version, however you installed it. |

Useful flags across most commands: `--dry-run` (preview only), `--json` (stable JSON output for scripting), `--yes` (skip the confirmation prompt on `sync`/`schedule install`).

## Features

- **Local-first privacy scanning.** Every session is analyzed on your machine before anything uploads: secret detection (private keys, basic-auth URLs, API keys, etc.), email/phone PII counts, and an overall `privacy_risk` rating. A `blocked`/`high`/`medium` risk session is **rejected locally and never uploaded** — only a metadata-only rejection report is sent to the server for operator visibility, never the file content.
- **Exact-hash dedup and duplicate-content detection.** A session already submitted once is never re-submitted, even across renamed/moved files or when a *different* file's content turns out to be a byte-exact prefix of something already known (e.g. a session resumed, copied, or exported to a new location).
- **Subagent session recording**, across all three sources, each judged, priced, and paid independently of its parent session.
- **Server-side quality scoring and automatic pricing** based on privacy risk and content quality — the scoring/pricing logic itself is deliberately not part of this package, so it can't be reverse-engineered from a local install and gamed.
- **Full contributor data controls** — export your records, delete unaccepted raw submissions, and file tracked privacy requests (access, correction, deletion, restriction, opt-out) from your dashboard.

## How it works end-to-end

1. **Discover** — `scan`/`sync` find Claude Code, Codex, and Cursor session files (`.jsonl`) locally, including subagent transcripts.
2. **Analyze locally** — for each new/changed file: parse JSONL, count messages/tool calls/tool results, run secret + PII detection, and decide a privacy risk level. Quality scoring itself happens server-side only.
3. **Local gate** — if privacy risk is `medium`/`high`/`blocked`, or the file's content is a duplicate/contained-duplicate of something already known, it's rejected/skipped *before upload*, with only metadata reported to the server.
4. **Upload** — anything that passes the local gate is uploaded.
5. **Worker intake** — a backend worker re-runs the same deterministic analysis server-side, optionally adds an LLM ("semantic") quality judgment, and finalizes the record's status and price.
6. **Review** — an operator reviews priced/quarantined items and accepts or rejects.
7. **Payout** — accepted items get queued and paid out.

## How scoring and pricing actually work

Quality scoring and pricing are computed **server-side only**, from a fresh re-download of what you actually uploaded — never trusted from anything this CLI reports about itself. That's deliberate: the exact formula (score weights, anti-gaming thresholds, price bands) lives only in the private backend, specifically so it can't be reverse-engineered and gamed by anyone who's installed this package.

At a high level, without exact numbers: a session earns credit for genuine tool diversity, real code edits (not just reads), substantive messages, and recovering from tool errors; sessions that look padded or that loop the same trivial tool call with no real edits score worse. An optional LLM pass can add a small bonus on top for sessions that clear every check, but it can never rescue a below-floor score or exceed the overall offer cap. New contributors' first few submissions are price-capped regardless of computed score, to limit the blast radius while an operator builds confidence in the account.

## Things to keep in mind

- **Nothing uploads while your machine is off or asleep with no active session.** Auto-capture only runs at `SessionEnd` (live hook) or on the scheduled timer (requires your machine to be on). There's no queued/replay-on-wake behavior for missed intervals.
- **A "rejected" privacy verdict only grows, never shrinks.** Once a path is recorded as rejected-for-privacy or a duplicate, the CLI stops re-scanning and re-reporting that exact path on later syncs.
- **The scanner can false-positive on its own source code.** If a session's transcript includes reading the analyzer's own source, the scanner can flag its pattern literals themselves as a match. Always worth a quick manual look at `rejection_codes`/`secret_findings` before assuming a block means a real leaked credential.
- **Subagents are scored completely independently of their parent.** A rejected/quarantined parent session's subagent transcripts can still be scanned clean, uploaded, priced, and accepted on their own.
- **Exclusions and sharing mode are local-only settings** — they don't retroactively affect anything already submitted.
