@pickagent/cli 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +155 -2
  3. package/dist/cli.js +23906 -0
  4. package/package.json +46 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 pickagent
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,156 @@
1
- # Temporary Holding Version
1
+ # pickagent scan
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Local CLI. It reads your agents' usage, builds a `pickagent.profile/v1` profile, and opens the verdict in the browser. The profile travels in the `#p=` URL fragment. It is not uploaded.
4
+
5
+ Scanner page: https://pickagent.dev/en/escaner
6
+
7
+ ## Install and use
8
+
9
+ Requires Node 20 or newer. Windows: untested.
10
+
11
+ On a machine that does not have this repository:
12
+
13
+ ```bash
14
+ npx @pickagent/cli scan
15
+ npx @pickagent/cli scan --period 2026-10 --plan claude-pro
16
+ npx @pickagent/cli scan --help
17
+ ```
18
+
19
+ `npx` downloads the package and runs it there. It is not installed into a project.
20
+
21
+ ## Options
22
+
23
+ ```text
24
+ --period YYYY-MM Calendar month. Default: the current local month.
25
+ --days N Last N days, including today (1–366).
26
+ --plan SLUG Plan you pay for today. Repeatable. E.g. claude-pro.
27
+ --base-url URL Verdict origin. Default https://pickagent.dev.
28
+ --lang es|en Verdict language. Default: es when LC_ALL, LC_MESSAGES,
29
+ or LANG starts with es; otherwise en.
30
+ --json Write only the JSON profile to stdout.
31
+ --yes Open the browser without asking.
32
+ --no-open Do not open the browser.
33
+ --codex Codex only (local rollouts; experimental).
34
+ --help This help.
35
+ ```
36
+
37
+ By default every harness is merged. `--codex` limits the read to Codex.
38
+ `--plan` replaces automatic plan detection.
39
+
40
+ From a clone of this repository:
41
+
42
+ ```bash
43
+ npm ci
44
+ npm run build
45
+ node dist/cli.js scan --period 2026-10 --plan claude-pro
46
+ npm test
47
+ ```
48
+
49
+ Without packaging: `npx tsx src/cli.ts scan --help`.
50
+
51
+ ## What it reads
52
+
53
+ Every agent ccusage detects, by default.
54
+
55
+ 1. `npx --yes ccusage@latest` with three unified reports, in parallel:
56
+ - `daily --json --by-agent --breakdown --no-cost --offline --since YYYY-MM-DD --until YYYY-MM-DD --timezone <IANA>`
57
+ - `session` with the same flags
58
+ - `blocks` with `--json --no-cost --offline` and the same range (Claude 5-hour windows)
59
+ 2. The `--by-agent` JSON is split by harness. Totals go into the profile metrics and the breakdown into `by_source` (hours, sessions, provenance per source).
60
+ 3. If ccusage fails to start or fails validation, the local parser reads every Claude config directory: comma-separated `CLAUDE_CONFIG_DIR`, each `config_dir` in `~/.claude-subs/registry.json` (that field only), and the defaults `~/.claude` and `~/.config/claude`. Usage is summed as one `claude-code` source.
61
+ 4. If local Codex rollouts exist and ccusage did not contribute Codex, they are merged into the profile.
62
+ 5. If Cursor agent-transcripts or `ai-tracking` exist and ccusage did not contribute Cursor, they are merged (estimated hours; chat text is not read).
63
+ 6. Plans (no network): it reads the Claude tier in every config directory (`default_claude_ai` is Claude Pro; Max 5× / 20× map to `claude-max-5x` / `claude-ultra`), the `chatgpt_plan_type` JWT claim in `~/.codex/auth.json`, and Cursor `stripeMembershipType` in `state.vscdb`. Old Stripe ids `pro` and `pro_plus` map to `cursor-pro-legacy` and `cursor-pro-plus-legacy`, not Premium or Super. `ultra` is ambiguous, so an interactive terminal asks. Several Claude profiles can contribute several plans. `--plan` replaces detection. Tokens and email are not uploaded.
64
+ 7. OpenCode, Kimi (`~/.kimi` and `~/.kimi-code`), and Codex hours that ccusage leaves at 0 are estimated from session timestamps. Gemini CLI (`~/.gemini/tmp`) and Antigravity (`~/.gemini/antigravity`) are included the same way: tokens by family when the file has a usage object, otherwise hours and days only.
65
+
66
+ ccusage is not part of pickagent. It is third-party code, and each run resolves it with `npx` as `ccusage@latest`, with no pinned version.
67
+
68
+ `--codex` limits the read to local Codex rollouts (experimental).
69
+
70
+ ## What it never reads
71
+
72
+ - Message text, prompts, and tool contents.
73
+ - Paths, `cwd`, project names, and titles.
74
+ - The session id in the clear. It is used only to group rows, and it is hashed with SHA-256 first. The hash does not enter the profile.
75
+ - API keys. They are not requested. The ccusage process does not inherit the environment: it only receives `LOG_LEVEL=0` (set by the scanner) and, when present, these variables: `PATH`, `HOME`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`, `TZ`, `LANG`, `LC_*`, `TMPDIR`, `TEMP`, `TMP`, `SystemRoot`, `ComSpec`, `PATHEXT`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `npm_config_registry`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `http_proxy`, `https_proxy`, `no_proxy`, `ALL_PROXY`, `npm_config_proxy`, `npm_config_https_proxy`, `npm_config_cafile`, `npm_config_userconfig`, `NODE_EXTRA_CA_CERTS`, and `SSL_CERT_FILE`. Names are compared case-insensitively. No variable whose name ends in `_TOKEN`, `_KEY`, or `_SECRET` is passed, nor `npm_config_*auth*`. If your proxy or registry URL contains a username and password, ccusage receives it. ccusage runs with your user permissions, so it can read your files, such as `~/.npmrc`.
76
+
77
+ From each Claude line, only these fields are copied, as numbers or hours: timestamp, model id, `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, and the session id (already hashed). Lines that do not look like an `assistant` record with `usage` or `rate_limit` are not parsed.
78
+
79
+ Profile hours are stored in one-hour blocks (truncated to the local hour). Clock minutes are not stored. The session median is in minutes, because the schema requires it, rounded to one minute.
80
+
81
+ ccusage output is filtered before use: dates, models, tokens, and the `isGap` / `isActive` flags are kept. Costs, session ids, paths, and the project grouping are dropped (`projects` keys are not copied).
82
+
83
+ ## Network
84
+
85
+ Only two network exits:
86
+
87
+ - `npx` may download `ccusage@latest` the first time. ccusage is launched with `--offline` so it does not request prices.
88
+ - Opening the browser at the verdict URL, after confirmation.
89
+
90
+ No other HTTP. No database.
91
+
92
+ To see those calls on Linux: `strace -f -e trace=network -o /tmp/pickagent.strace npx @pickagent/cli scan --no-open`. `strace` is Linux-only; macOS does not have it. The only expected connection is `npx` downloading `ccusage`. With `--no-open` the browser does not open.
93
+
94
+ ## Claude blocks (local parser)
95
+
96
+ ccusage does not say when you run out of quota (`no_limit_hits`). The local parser does, and only when ccusage did not produce a valid profile. It is best-effort, over the text Claude Code writes in the transcript when `error` is `"rate_limit"`.
97
+
98
+ The first line counts when it matches one of these:
99
+
100
+ ```text
101
+ /^You've hit your (?:session|weekly) limit\b/
102
+ /^You've hit your org's monthly spend limit\b/
103
+ ```
104
+
105
+ A transient API limit does not count, even when the error is `rate_limit`:
106
+
107
+ ```text
108
+ /not your usage limit/i
109
+ /temporarily limiting requests/i
110
+ ```
111
+
112
+ The wait comes from:
113
+
114
+ ```text
115
+ /\bresets (\d{1,2})(?::(\d{2}))?\s*(am|pm)\b(?:\s*\(([^)]+)\))?/i
116
+ ```
117
+
118
+ The sentence has no date. The wait is the next time the clock reaches that hour in the zone inside the parentheses, rounded to hours. For a weekly or monthly cap that undershoots. If the zone is missing or is not IANA, the block still counts and `wait_hours` is omitted. The sentence text is not stored.
119
+
120
+ Repeated `assistant` records with the same `message.id` count once: Claude Code writes the same response under several `uuid` values.
121
+
122
+ ## Codex (`--codex`, experimental)
123
+
124
+ The machine where this reader was written had no `~/.codex/sessions` directory, so the format is not confirmed here. The expected shape is what third-party readers document: `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl` and `archived_sessions/**/rollout-*.jsonl` (`CODEX_HOME` or `~/.codex`).
125
+
126
+ A file is included only when the first line is `session_meta` and `payload.originator` contains `codex`. `response_item` lines (prompts, tools, paths) are not parsed.
127
+
128
+ It uses `turn_context.payload.model` and `event_msg` with `payload.type === "token_count"` and `info.last_token_usage`. The cumulative `total_token_usage` is ignored. `input_tokens` includes the cached part, so uncached input is `input_tokens - cached_input_tokens`, cache read is `cached_input_tokens`, and output adds `output_tokens` and `reasoning_output_tokens`. There is no cache write: that field stays 0 and tokens and `by_model` are marked `estimated`. Hours taken from timestamps stay `measured`.
129
+
130
+ A block counts when `rate_limits.rate_limit_reached_type` is a non-empty string. The string is not stored. The wait comes from `primary.resets_at` or, if missing, `secondary.resets_at` (unix, seconds).
131
+
132
+ ## Output
133
+
134
+ Without `--json`, an English summary and the URL. It asks before opening the browser. `--yes` opens without asking. `--no-open` does not open. `--json` writes only the profile to stdout; the browser opens only when you also pass `--yes` and not `--no-open`.
135
+
136
+ The URL is `{base}/es/veredicto` when `LC_ALL`, `LC_MESSAGES`, or `LANG` starts with `es`, and `{base}/en/verdict` otherwise, plus `profileToHash()`. `--lang es` or `--lang en` overrides that. Default base: `https://pickagent.dev`. `/en/veredicto` redirects on the site.
137
+
138
+ The profile goes through `parseProfile` before use. If it does not match the schema, the issues are printed and the process exits with code 1. With no measurable usage (no hours with a distinct start and end) it also exits with code 1: an empty profile does not fit the schema, because `agent_hours`, `activity`, and `by_model` are required.
139
+
140
+ ## How to audit it
141
+
142
+ The code is in `src/`. The profile contract (`pickagent.profile/v1`, its parse, its encode, and the step from usage reports to that profile) is in `src/profile/`. esbuild bundles it into `dist/cli.js` together with Zod. There are no runtime dependencies: the published package is that file, this README, and the license.
143
+
144
+ Search for `fetch(`, `http.request`, `net.connect`, and keys: they should not appear, except the allowlist of variables passed to ccusage. The only external execution is `npx ccusage@latest` and the system `open` / `xdg-open`. On Windows the child does not start `npx.cmd` directly (Node 20.12 or newer rejects that) and the browser URL is quoted. Windows: untested.
145
+
146
+ On a clean clone: `npm ci && npm run build && node dist/cli.js scan --help && npm test`.
147
+
148
+ ## Why the code is public
149
+
150
+ The profile is not uploaded. It travels in the `#p=` URL fragment, and the browser does not send the fragment to the server. The repository is public so anyone can check: the scanner does not `fetch` the profile, it opens no network beyond `npx` resolving `ccusage` and opening the browser, and the `src/profile/` schema has no place for conversation text. The verdict page reads that fragment in the browser. The verdict calculation is not in this repository.
151
+
152
+ ## How it is published
153
+
154
+ No npm token is required. Pushing a tag `vX.Y.Z` whose `X.Y.Z` matches `version` in `package.json` makes GitHub Actions (`.github/workflows/release.yml`) install dependencies, build, run the tests, and publish `@pickagent/cli` with `npm publish --provenance --access public`. Provenance uses GitHub OIDC (`id-token: write`), so the npm package is tied to this repository and that commit.
155
+
156
+ Before the first tag, the repository must be registered as a trusted publisher of the package on npmjs.com (workflow `release.yml`). A person creates the tag; this repository does not publish itself.