jobtriage 0.3.0__tar.gz

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 (102) hide show
  1. jobtriage-0.3.0/LICENSE +21 -0
  2. jobtriage-0.3.0/PKG-INFO +364 -0
  3. jobtriage-0.3.0/README.md +335 -0
  4. jobtriage-0.3.0/pyproject.toml +66 -0
  5. jobtriage-0.3.0/pyproject.toml.orig +62 -0
  6. jobtriage-0.3.0/src/jobtriage/__init__.py +10 -0
  7. jobtriage-0.3.0/src/jobtriage/__main__.py +7 -0
  8. jobtriage-0.3.0/src/jobtriage/assets/AGENTS.md +79 -0
  9. jobtriage-0.3.0/src/jobtriage/assets/gitignore +9 -0
  10. jobtriage-0.3.0/src/jobtriage/assets/jobtriage.toml +40 -0
  11. jobtriage-0.3.0/src/jobtriage/assets/letters/README.md +3 -0
  12. jobtriage-0.3.0/src/jobtriage/assets/presets/any.toml +10 -0
  13. jobtriage-0.3.0/src/jobtriage/assets/presets/backend-engineer.toml +52 -0
  14. jobtriage-0.3.0/src/jobtriage/assets/presets/data.toml +37 -0
  15. jobtriage-0.3.0/src/jobtriage/assets/presets/designer.toml +43 -0
  16. jobtriage-0.3.0/src/jobtriage/assets/presets/product-manager.toml +38 -0
  17. jobtriage-0.3.0/src/jobtriage/assets/presets/web-engineer.toml +53 -0
  18. jobtriage-0.3.0/src/jobtriage/assets/profile/DETAILS.md +32 -0
  19. jobtriage-0.3.0/src/jobtriage/assets/profile/README.md +7 -0
  20. jobtriage-0.3.0/src/jobtriage/assets/scrapers/README.md +9 -0
  21. jobtriage-0.3.0/src/jobtriage/assets/scrapers/_example.py +229 -0
  22. jobtriage-0.3.0/src/jobtriage/assets/skills/README.md +14 -0
  23. jobtriage-0.3.0/src/jobtriage/assets/skills/add-scraper/SKILL.md +143 -0
  24. jobtriage-0.3.0/src/jobtriage/assets/skills/add-scraper/references/contract.md +101 -0
  25. jobtriage-0.3.0/src/jobtriage/assets/skills/cover-letter/SKILL.md +107 -0
  26. jobtriage-0.3.0/src/jobtriage/assets/skills/cover-letter/references/example-letter.md +34 -0
  27. jobtriage-0.3.0/src/jobtriage/assets/skills/fill-application/SKILL.md +124 -0
  28. jobtriage-0.3.0/src/jobtriage/assets/skills/fill-application/references/ats-forms.md +52 -0
  29. jobtriage-0.3.0/src/jobtriage/assets/skills/jobtriage/SKILL.md +112 -0
  30. jobtriage-0.3.0/src/jobtriage/assets/skills/jobtriage/references/cli.md +212 -0
  31. jobtriage-0.3.0/src/jobtriage/assets/skills/jobtriage-db/SKILL.md +104 -0
  32. jobtriage-0.3.0/src/jobtriage/assets/skills/jobtriage-db/references/recipes.sql +107 -0
  33. jobtriage-0.3.0/src/jobtriage/assets/skills/jobtriage-db/references/schema.md +82 -0
  34. jobtriage-0.3.0/src/jobtriage/assets/skills/setup/SKILL.md +121 -0
  35. jobtriage-0.3.0/src/jobtriage/assets/skills/triage/SKILL.md +101 -0
  36. jobtriage-0.3.0/src/jobtriage/assets/skills/tune-filters/SKILL.md +142 -0
  37. jobtriage-0.3.0/src/jobtriage/assets/writing-style.md +38 -0
  38. jobtriage-0.3.0/src/jobtriage/attachments.py +54 -0
  39. jobtriage-0.3.0/src/jobtriage/browser/__init__.py +9 -0
  40. jobtriage-0.3.0/src/jobtriage/browser/find.py +177 -0
  41. jobtriage-0.3.0/src/jobtriage/browser/front.py +152 -0
  42. jobtriage-0.3.0/src/jobtriage/chrome.py +283 -0
  43. jobtriage-0.3.0/src/jobtriage/cli/__init__.py +9 -0
  44. jobtriage-0.3.0/src/jobtriage/cli/attach.py +72 -0
  45. jobtriage-0.3.0/src/jobtriage/cli/config.py +388 -0
  46. jobtriage-0.3.0/src/jobtriage/cli/db.py +216 -0
  47. jobtriage-0.3.0/src/jobtriage/cli/doctor.py +468 -0
  48. jobtriage-0.3.0/src/jobtriage/cli/export.py +94 -0
  49. jobtriage-0.3.0/src/jobtriage/cli/filter.py +114 -0
  50. jobtriage-0.3.0/src/jobtriage/cli/filters.py +67 -0
  51. jobtriage-0.3.0/src/jobtriage/cli/import_sheet.py +407 -0
  52. jobtriage-0.3.0/src/jobtriage/cli/init.py +337 -0
  53. jobtriage-0.3.0/src/jobtriage/cli/list.py +67 -0
  54. jobtriage-0.3.0/src/jobtriage/cli/main.py +230 -0
  55. jobtriage-0.3.0/src/jobtriage/cli/mcp.py +37 -0
  56. jobtriage-0.3.0/src/jobtriage/cli/note.py +37 -0
  57. jobtriage-0.3.0/src/jobtriage/cli/open.py +59 -0
  58. jobtriage-0.3.0/src/jobtriage/cli/output.py +43 -0
  59. jobtriage-0.3.0/src/jobtriage/cli/scrape.py +296 -0
  60. jobtriage-0.3.0/src/jobtriage/cli/show.py +148 -0
  61. jobtriage-0.3.0/src/jobtriage/cli/skills.py +230 -0
  62. jobtriage-0.3.0/src/jobtriage/cli/sources.py +947 -0
  63. jobtriage-0.3.0/src/jobtriage/cli/status.py +58 -0
  64. jobtriage-0.3.0/src/jobtriage/cli/tty.py +26 -0
  65. jobtriage-0.3.0/src/jobtriage/cli/tui.py +56 -0
  66. jobtriage-0.3.0/src/jobtriage/config.py +1127 -0
  67. jobtriage-0.3.0/src/jobtriage/db.py +334 -0
  68. jobtriage-0.3.0/src/jobtriage/geo.py +1258 -0
  69. jobtriage-0.3.0/src/jobtriage/logs.py +137 -0
  70. jobtriage-0.3.0/src/jobtriage/mcp.py +498 -0
  71. jobtriage-0.3.0/src/jobtriage/pipeline.py +582 -0
  72. jobtriage-0.3.0/src/jobtriage/plugin/__init__.py +74 -0
  73. jobtriage-0.3.0/src/jobtriage/plugin/dates.py +161 -0
  74. jobtriage-0.3.0/src/jobtriage/plugin/geo.py +42 -0
  75. jobtriage-0.3.0/src/jobtriage/plugin/http.py +322 -0
  76. jobtriage-0.3.0/src/jobtriage/plugin/parse.py +104 -0
  77. jobtriage-0.3.0/src/jobtriage/registry.py +539 -0
  78. jobtriage-0.3.0/src/jobtriage/relevance.py +276 -0
  79. jobtriage-0.3.0/src/jobtriage/scrapers/__init__.py +19 -0
  80. jobtriage-0.3.0/src/jobtriage/scrapers/bruntwork.py +230 -0
  81. jobtriage-0.3.0/src/jobtriage/scrapers/dynamitejobs.py +208 -0
  82. jobtriage-0.3.0/src/jobtriage/scrapers/euremotejobs.py +330 -0
  83. jobtriage-0.3.0/src/jobtriage/scrapers/eurotechjobs.py +172 -0
  84. jobtriage-0.3.0/src/jobtriage/scrapers/inclusivelyremote.py +212 -0
  85. jobtriage-0.3.0/src/jobtriage/scrapers/jobgether.py +377 -0
  86. jobtriage-0.3.0/src/jobtriage/scrapers/justremote.py +146 -0
  87. jobtriage-0.3.0/src/jobtriage/scrapers/remocate.py +356 -0
  88. jobtriage-0.3.0/src/jobtriage/scrapers/remotefrontendjobs.py +256 -0
  89. jobtriage-0.3.0/src/jobtriage/scrapers/remoteok.py +208 -0
  90. jobtriage-0.3.0/src/jobtriage/scrapers/remotesource.py +124 -0
  91. jobtriage-0.3.0/src/jobtriage/scrapers/remotive.py +187 -0
  92. jobtriage-0.3.0/src/jobtriage/scrapers/wellfound.py +244 -0
  93. jobtriage-0.3.0/src/jobtriage/scrapers/weworkremotely.py +400 -0
  94. jobtriage-0.3.0/src/jobtriage/scrapers/workingnomads.py +105 -0
  95. jobtriage-0.3.0/src/jobtriage/status.py +126 -0
  96. jobtriage-0.3.0/src/jobtriage/store.py +712 -0
  97. jobtriage-0.3.0/src/jobtriage/tui/__init__.py +27 -0
  98. jobtriage-0.3.0/src/jobtriage/tui/app.py +912 -0
  99. jobtriage-0.3.0/src/jobtriage/tui/help.py +82 -0
  100. jobtriage-0.3.0/src/jobtriage/tui/keys.py +264 -0
  101. jobtriage-0.3.0/src/jobtriage/tui/widgets.py +438 -0
  102. jobtriage-0.3.0/src/jobtriage/workspace.py +470 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niyi Adeosun
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.
@@ -0,0 +1,364 @@
1
+ Metadata-Version: 2.4
2
+ Name: jobtriage
3
+ Version: 0.3.0
4
+ Summary: Scrape remote job boards, keep the relevant roles, remember them in SQLite, triage them from the keyboard.
5
+ Keywords: jobs,job-search,job-boards,scraping,cli,sqlite,tui
6
+ Author: Niyi Adeosun
7
+ Author-email: Niyi Adeosun <deniyi.adeosun@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Utilities
21
+ Requires-Dist: mcp>=2.3.0
22
+ Requires-Dist: platformdirs>=4.3.0
23
+ Requires-Dist: textual>=8.2.8
24
+ Requires-Dist: tomlkit>=0.15.2
25
+ Requires-Python: >=3.11
26
+ Project-URL: Homepage, https://github.com/niyiao/jobtriage
27
+ Project-URL: Repository, https://github.com/niyiao/jobtriage
28
+ Description-Content-Type: text/markdown
29
+
30
+ # jobtriage
31
+
32
+ One CLI over fifteen remote job boards — and one place to keep what it
33
+ finds. jobtriage scrapes every enabled board in parallel, drops the
34
+ postings older than three weeks, keeps the titles that match your
35
+ filter, and remembers every job and its triage status in a local SQLite
36
+ database, so a later scrape only shows you what is new. A TUI sits on
37
+ top: newest first, one key to move a job through **new → to apply →
38
+ applied → skip**, and `enter` opens the posting in a Chrome window it
39
+ keeps for applying.
40
+
41
+ <!-- screenshot: TODO — the repository has no real TUI screenshot yet.
42
+ Take one of `jobtriage` on a populated database (a wide terminal
43
+ with the details pane open), save it under docs/, and embed it
44
+ here. Never commit a mock-up. -->
45
+
46
+ ## Install
47
+
48
+ uv tool install jobtriage # or: pipx install jobtriage
49
+ jobtriage init # create the op folder (default ~/jobtriage)
50
+ jobtriage doctor # check the setup; every problem names its fix
51
+
52
+ Python 3.11 or newer. macOS and Linux are the tested platforms.
53
+ Windows is supported in the code — the browser finder, the launch, the
54
+ copy fallback for skill links and the CI matrix all cover it — but the
55
+ TUI has not been run in Windows Terminal yet. If the screen renders
56
+ badly there, a screenshot in an issue is the report that helps.
57
+
58
+ `jobtriage init` asks four small questions — where you can work from,
59
+ what kind of role, a title-filter preset, employment — then writes the
60
+ op folder from the shipped templates. Pressing Enter keeps each
61
+ default; `--yes` takes all four without asking, for scripts and agents.
62
+ Everything personal lives in that folder:
63
+
64
+ ~/jobtriage/
65
+ jobtriage.toml config; its presence marks the folder
66
+ jobtriage.db the database: jobs, statuses, notes
67
+ profile/ RESUME.md, DETAILS.md, resume PDF
68
+ letters/ cover letters
69
+ scrapers/ user scraper plugins
70
+ skills/ agent skills
71
+ AGENTS.md agent instructions for this folder
72
+ CLAUDE.md symlink to AGENTS.md
73
+ .agents/skills symlink to skills/ (also .claude/skills,
74
+ .opencode/skills)
75
+ writing-style.md prose style for letters and content
76
+ .env secrets (API keys), optional
77
+ .browser-profile/ the Chrome profile for applying/research
78
+ .jobtriage/ tool state: version stamp, asset manifest,
79
+ database backups, logs, the TUI's remembered place
80
+ .gitignore so the folder can be git-tracked safely
81
+
82
+ The repository holds the code and nothing personal. The command finds
83
+ the folder by itself: from inside it, from the pointer `init` wrote, or
84
+ explicitly with `--workspace PATH` or `JOBTRIAGE_HOME`.
85
+
86
+ `init` is idempotent — safe to run twice, it never overwrites a file
87
+ you've edited. After a package update, `jobtriage init --upgrade`
88
+ refreshes the shipped templates: files you haven't touched are
89
+ replaced, edited files are left alone and the new version lands beside
90
+ them as `<file>.new`. If the package is newer than the folder, the
91
+ first run says so and points at that command.
92
+
93
+ ## Quickstart
94
+
95
+ jobtriage scrape # the pipeline: every board in parallel,
96
+ # relevant new jobs into the database
97
+ jobtriage # the TUI over what landed
98
+
99
+ A default scrape asks each enabled board for its 50 newest jobs for
100
+ your configured locations, merges and dedupes them, drops anything
101
+ older than 21 days, keeps the titles the filter matches, and ingests
102
+ what remains in one transaction. The one-line summary
103
+ (`N relevant · x new · y already seen · total in the database`) goes to
104
+ stderr. A second run reports what it has already seen; nothing is
105
+ repeated.
106
+
107
+ `jobtriage scrape -s rs 20` runs one board with a different limit;
108
+ `--raw` prints the unfiltered listing and saves nothing;
109
+ `--explain` says, per board, what the age and title gates dropped and
110
+ which words did it.
111
+
112
+ ### The TUI
113
+
114
+ Tabs follow the workflow: **new → to apply → applied → skip → all**,
115
+ opening on `tui.default_filter` (to apply) unless the last session
116
+ ended on another. `←`/`→` change tabs and never touch a status. The
117
+ tab, the search query and the selected job are saved on quit and
118
+ restored at the next start.
119
+
120
+ A status key writes the status the moment it is pressed and moves on
121
+ to the next job — triage is a stream of decisions. `u` undoes the last
122
+ one: status, tab and cursor, repeatable for the session. Writes go
123
+ straight to the database, and every change lands in the job's history
124
+ with the actor `tui`.
125
+
126
+ `/` searches title and company as you type; enter keeps the query, esc
127
+ clears it. `m` adds a one-line note, `y` copies the job's URL, `d`
128
+ shows the details pane (company, dates, locations, pay, source, notes,
129
+ history, attachments), and `?` shows every binding. `R` runs a scrape
130
+ in the background and reloads the list when it lands; `r` reloads
131
+ without scraping.
132
+
133
+ `enter` opens the job in the apply Chrome — the op folder's browser
134
+ profile, started if it isn't already up. Each job remembers its tab: a
135
+ second enter focuses that tab, and a new one opens only once the old
136
+ has been closed. Quitting the TUI leaves Chrome running. With no
137
+ Chrome installed, `enter` opens the job in the system's default
138
+ browser instead.
139
+
140
+ <!-- tui keys: generated from src/jobtriage/tui/keys.py — do not edit by hand -->
141
+
142
+ | Key | Action |
143
+ |---|---|
144
+ | `n` | set new and move on |
145
+ | `t` | set to apply and move on |
146
+ | `a` | set applied and move on |
147
+ | `s` | set skip and move on |
148
+ | `u` | undo the last status change |
149
+ | `j` / `↓` | move down one job |
150
+ | `k` / `↑` | move up one job |
151
+ | `g` | press twice for the first job |
152
+ | `G` | go to the last job |
153
+ | `^d` | move half a screen down |
154
+ | `^u` | move half a screen up |
155
+ | `pgdn` | move a page down |
156
+ | `pgup` | move a page up |
157
+ | `←` / `h` / `⇧tab` | previous tab |
158
+ | `→` / `l` / `tab` | next tab |
159
+ | `1` | jump to the new tab |
160
+ | `2` | jump to the to apply tab |
161
+ | `3` | jump to the applied tab |
162
+ | `4` | jump to the skip tab |
163
+ | `5` | jump to the all tab |
164
+ | `space` | space twice: applied (alias for a) |
165
+ | `S` | skip and move on (alias for s) |
166
+ | `enter` | open the job in Chrome |
167
+ | `d` | toggle the details pane |
168
+ | `/` | search title and company |
169
+ | `y` | copy the job URL |
170
+ | `m` | add a note to the job |
171
+ | `r` | reload from the database |
172
+ | `R` | run a scrape in the background |
173
+ | `?` | show this help |
174
+ | `q` / `^c` / `^q` | quit |
175
+
176
+ <!-- end tui keys -->
177
+
178
+ Keys are rebindable per op folder; the help overlay and the footer
179
+ follow the same table:
180
+
181
+ [tui.keys]
182
+ skipped = "x"
183
+
184
+ ## Commands
185
+
186
+ | Command | What it does |
187
+ |---|---|
188
+ | `jobtriage` | the TUI (same as `jobtriage tui`) |
189
+ | `jobtriage scrape [LIMIT]` | run the boards; `-s NAME`, `--raw`, `--explain` |
190
+ | `jobtriage sources` | the boards: list, `info`, `new`, `test`, `enable`, `disable` |
191
+ | `jobtriage list [LIMIT]` | query the database; `--status`, `--since`, `--source`, `--search`, `--json` |
192
+ | `jobtriage show ID` | one job: every field, notes, history, attachments |
193
+ | `jobtriage open ID` | the posting in the apply browser |
194
+ | `jobtriage status ID SLUG` | set a job's status |
195
+ | `jobtriage note ID TEXT` | append a note |
196
+ | `jobtriage attach ID FILE` | record a file (a cover letter) against a job |
197
+ | `jobtriage export` | the rows as CSV, or `--format json` |
198
+ | `jobtriage config` | `show`, `edit`, `get`, `set`, `validate` |
199
+ | `jobtriage filter test TITLE` | why one title passes or not |
200
+ | `jobtriage db` | `path`, `shell`, `schema`, `import-sheet old.csv` |
201
+ | `jobtriage skills` | list the agent skills; `install --global --agent …` |
202
+ | `jobtriage mcp` | the MCP server over stdio |
203
+ | `jobtriage doctor [--offline]` | check the setup |
204
+ | `jobtriage where` | print the op folder's path |
205
+ | `jobtriage --version` | build, workspace path, database schema |
206
+
207
+ Every command takes `--help`; `jobtriage <cmd> --help` is the reference
208
+ for its flags. The config keys are in [docs/config.md](docs/config.md),
209
+ the boards and the plugin contract in
210
+ [docs/scrapers.md](docs/scrapers.md). `-v`/`--verbose` before the
211
+ command puts DEBUG detail on stderr. (`uv run jobtriage …` works from a
212
+ checkout; `python -m jobtriage` too.)
213
+
214
+ ## Filtering
215
+
216
+ Two gates. **Age**: anything older than `search.max_age_days` (21 by
217
+ default) is dropped; a job with no date at all is assumed new. **Title**:
218
+ the `[filter]` table, starting from a shipped preset. A fresh folder
219
+ has no title filter (`preset = "any"`), so the board's category is the
220
+ only narrowing.
221
+
222
+ `jobtriage filter test "Senior React Native Engineer"` says why one
223
+ title passes or not. Every key and every preset is in
224
+ [docs/config.md](docs/config.md#filter); the reasoning behind the age
225
+ cutoff and the undated rule — and how the dedup keys work — is in
226
+ [docs/design.md](docs/design.md).
227
+
228
+ ## The database
229
+
230
+ `jobtriage.db` in the op folder (gitignored by the shipped template) is
231
+ the single source of truth: every job the pipeline has seen, its
232
+ status, your notes, and a history row for every status change. `list`
233
+ and `export` read it without scraping; `show` prints one job in full;
234
+ `status`, `note` and `attach` are the writes.
235
+
236
+ Ad hoc questions go through sqlite3:
237
+
238
+ jobtriage db shell 'select title, company, url from jobs order by published desc limit 10'
239
+ jobtriage db schema # the tables and columns, with comments
240
+
241
+ Coming from an old Google Sheet: `jobtriage db import-sheet old.csv`
242
+ (File → Download → CSV) moves its statuses over, matching by url first
243
+ and then by folded title and company; `--dry-run` first. It is a
244
+ one-time bridge, not part of the daily workflow. The dedup key and the
245
+ column list are in
246
+ [docs/design.md](docs/design.md#dedup-keys-and-the-jobs-table).
247
+
248
+ ## Config
249
+
250
+ Everything you might change is `jobtriage.toml` in the op folder: where
251
+ you can work from, families, age and the per-board limit, the title
252
+ filter, disabled boards and per-board overrides, the browser, the
253
+ scraper's User-Agent, the TUI's startup tab and key bindings. Every key
254
+ ships commented out, so a fresh folder runs on the defaults until you
255
+ fill something in.
256
+
257
+ `jobtriage config show` prints every effective value with the layer
258
+ that set it, `config set` edits the file without losing its comments,
259
+ and `config validate` names a typo with a suggestion. The reference is
260
+ [docs/config.md](docs/config.md).
261
+
262
+ ## Agents and skills
263
+
264
+ `init` ships eight agent skills in `<op>/skills/`: an umbrella
265
+ `jobtriage` page, the database and triage workflows, cover letters,
266
+ applications, scrapers, filter tuning and setup. It links them from
267
+ `.agents/skills`, `.claude/skills` and `.opencode/skills` (and
268
+ `CLAUDE.md` to `AGENTS.md`), so an agent opened in the folder finds
269
+ them by itself.
270
+
271
+ jobtriage skills # what ships and what's installed
272
+ jobtriage skills install --global --agent all # copy them for the agents
273
+ jobtriage mcp # a stdio MCP server instead
274
+
275
+ `skills install --global` copies them into `~/.claude/skills`,
276
+ `~/.codex/skills` and `~/.config/opencode/skills` for use outside the
277
+ folder. `jobtriage mcp` is for clients without skill support: it
278
+ exposes typed reads and writes (`list_jobs`, `get_job`, `set_status`,
279
+ `add_note`, `attach`, `scrape`, `filter_test`) and never submits an
280
+ application. Triggers, discovery folders, the tool list and client
281
+ config: [docs/skills.md](docs/skills.md).
282
+
283
+ ## Plugins
284
+
285
+ Fifteen boards ship in the package. Any Python file in
286
+ `<op>/scrapers/` is also a board — no registration, no fork, no
287
+ reinstall: `jobtriage sources new myboard` writes one from the shipped
288
+ template, `sources test myboard` runs it with limit 5 and names any
289
+ contract problem, and `sources` shows every board and its health. The
290
+ plugin contract, the worked example, the research playbook and the
291
+ notes for every board are in [docs/scrapers.md](docs/scrapers.md).
292
+
293
+ ## doctor
294
+
295
+ `doctor` is the first thing to run when something is off. One line per
296
+ check — the workspace it found, the config, the database schema, the
297
+ browser and its CDP port, every plugin, the shipped skills, the profile
298
+ files — and a `problem` line carries the command that fixes it. It exits
299
+ 1 when anything is broken. Its only network use is one `HEAD` request
300
+ per enabled board to the board's homepage. `--offline` runs the local
301
+ checks only — workspace, config, database, plugins, skills, profile —
302
+ and skips the three that depend on the machine: the browser, its CDP
303
+ port and the boards. That is the mode CI uses, and the right one for a
304
+ headless box or a support request that starts with "is this install
305
+ sound?".
306
+
307
+ ## Logging
308
+
309
+ Every command also appends to `.jobtriage/logs/jobtriage.log`: DEBUG
310
+ detail, rotated at about a megabyte with three older copies kept.
311
+ `-v`/`--verbose` before the command puts the same detail on stderr:
312
+
313
+ jobtriage -v scrape # requests, board timings, every warning
314
+
315
+ ## Responsible use
316
+
317
+ jobtriage is one person's reader for boards that publish jobs publicly;
318
+ it is not a crawler farm.
319
+
320
+ - A default run asks each enabled board for its 50 newest postings, one
321
+ pass. Boards that paginate stay within their declared `MAX_PAGES`
322
+ cap, and `POLITE_DELAY` puts a minimum gap between a board's requests
323
+ (`src/jobtriage/plugin/http.py` enforces it for the whole run).
324
+ - Each built-in declares `TERMS` — what the board asks of a scraper:
325
+ a link back, a credit, a request rate. `jobtriage sources info NAME`
326
+ prints it. The URLs stored are the canonical ones several boards'
327
+ terms require (remotefrontendjobs' `/{id}` page, weworkremotely's own
328
+ links), and remoteok's "Remote OK" credit is carried with its link.
329
+ - `euremotejobs` ships disabled because its terms ban automated
330
+ collection outright. `jobtriage sources enable euremotejobs` is how
331
+ you accept them after reading `sources info euremotejobs`.
332
+ - Requests send a desktop-browser User-Agent by default, because several
333
+ boards refuse a generic one. If you would rather identify the tool,
334
+ set `[network] user_agent` in `jobtriage.toml` (see docs/config.md);
335
+ a board that demands its own string still gets it.
336
+ - Run it when you will read the results. There is no scheduler and no
337
+ queue — a scrape is one pass you started — and the only retry is a
338
+ single reconnect after a dropped connection.
339
+
340
+ ## Privacy
341
+
342
+ No telemetry, no account, no server of ours. The tool reads and writes
343
+ only the op folder, and its network traffic goes to two places: the job
344
+ boards you enabled, and any agent or API you choose to run yourself.
345
+ Delete the op folder and everything jobtriage knows is gone; the only
346
+ other file it writes is the one-line pointer in your platform config
347
+ directory that says where that folder is.
348
+
349
+ ## Documentation and contributing
350
+
351
+ - [docs/config.md](docs/config.md) — every config key, the location
352
+ vocabulary, the presets
353
+ - [docs/scrapers.md](docs/scrapers.md) — the plugin contract, discovery,
354
+ the board notes
355
+ - [docs/skills.md](docs/skills.md) — the eight skills and the MCP server
356
+ - [docs/design.md](docs/design.md) — why: the cache keys, the one
357
+ transaction, the location model, the registry tiers, the version tracks
358
+ - [docs/research.md](docs/research.md) — the investigations that chose
359
+ the boards
360
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, tests, how to add a
361
+ board, the commit convention
362
+ - [CHANGELOG.md](CHANGELOG.md) — what changed, release by release
363
+ - [SECURITY.md](SECURITY.md) — the trust model and how to report a
364
+ problem