Metadata-Version: 2.4
Name: reasonwork
Version: 0.4.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 (background auto-sync via `launchd` is macOS-only today; on Linux you can still use the CLI manually or wire your own systemd timer/cron entry).
- Python 3.12+.
- [`uv`](https://docs.astral.sh/uv/) for installing the CLI as a tool.
- 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 instead — unlike Claude Code, this install path is not yet verified end-to-end against a live Codex install.
- Cursor (the `cursor-agent` CLI, not the IDE chat panel), if you want the Cursor hook + skill instead — also not yet verified end-to-end against a live Cursor install, and depends on your installed Cursor version supporting the `sessionStart`/`sessionEnd` hook events.
- A Reasonwork account and an `nxc_…` contributor token, created from your account's settings page.

## 1. Install the CLI

```bash
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 written to a local config file (mode `0600`, owner read/write only). Use `login --dry-run` to just verify a token works without writing it to disk.

## 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 work the same way: a local install script wires up a session-end/session-start hook and a skill, scoped entirely to that tool's own config directory — never touching anything Claude-Code-related. Neither is yet verified end-to-end against a live install; treat as best-effort. See your Reasonwork contact for the install scripts if you use Codex or Cursor CLI.

## 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 (macOS only)

```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 macOS background timer. |
| `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 macOS itself running). 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.
