terminalhire — your code is your résumé

Local-first job + bounty matching, and a verifiable Proof of Work credential earned from PRs that maintainers who aren't you merged into established repos — checkable on GitHub, impossible to self-report. Matching runs entirely on your device. Your profile never leaves your machine.

Domain: terminalhire.com

Install

# one-off — no global install needed
npx terminalhire help

# global install
npm i -g terminalhire

# wire up the Claude Code statusLine nudge (optional, recommended)
node $(npm root -g)/terminalhire/install.js

The installer prints a full v3.1 disclosure, asks for explicit "yes", then offers GitHub sign-in (recommended), and finally writes one key to ~/.claude/settings.json. Install is NOT consent to share your profile — that is a separate, per-role decision.

Uninstall

node $(npm root -g)/terminalhire/install.js --uninstall
terminalhire logout             # clear GitHub token (if connected)
terminalhire profile --delete   # also wipe local profile
rm -rf ~/.terminalhire          # wipe everything

To disable only the spinner job surface without uninstalling:

terminalhire spinner --off

Commands

terminalhire login              # sign in with GitHub — enriches profile instantly (recommended)
terminalhire logout             # clear stored GitHub token from ~/.terminalhire/github-token.enc

terminalhire jobs               # fetch index, match locally, browse ranked roles
terminalhire jobs --limit 20    # show top 20 results (default: 10)
terminalhire jobs --remote-only # filter to remote roles only
terminalhire jobs --all         # show all matches above zero score

terminalhire bounties           # day-sized paid tasks you can knock out today
terminalhire bounties --priced  # only bounties with a known $ amount
terminalhire contribute         # credential-building issues matched to your stack — merges grow your Proof of Work

terminalhire claim record <id|issueUrl>  # claim a bounty locally + print the executor brief
terminalhire claim list --active         # list your active claims + accepted-PR rate
terminalhire claim status <id>           # poll source PR merge state (updates the metric)

terminalhire trajectory         # trajectory from your local Claude Code corpus
terminalhire trajectory --export  # write a derived score + Markdown to ~/.terminalhire/
terminalhire trajectory --inward  # also show private rework/recovery (never exported)

terminalhire devs               # opted-in peers & founders, matched 100% locally
terminalhire intro <login>      # request a double-opt-in intro (typed-yes consent)
terminalhire inbox              # unread chats, connections & pending intros in one place
terminalhire mcp --print-config # read-only MCP server config for VS Code/Cursor/Codex/Zed/JetBrains

terminalhire profile --show     # inspect your encrypted local profile (incl. GitHub fields)
terminalhire profile --edit     # set displayName, contactEmail, prefs
terminalhire profile --delete   # wipe profile and encryption key from disk

GitHub sign-in (recommended)

GitHub is the primary enrichment signal for Terminalhire. Signing in solves the cold-start problem — you get accurate matches on the very first run instead of waiting for tag accumulation.

terminalhire login

This runs the GitHub OAuth Device Flow:

1. A code like XXXX-XXXX and a URL (https://github.com/login/device) are displayed.
2. You open the URL, enter the code, and click "Authorize".
3. Terminalhire polls until you authorize, then stores the token encrypted at ~/.terminalhire/github-token.enc.
4. Your public GitHub profile is fetched, processed, and merged into your local profile.

What GitHub enriches

| Signal | Source | |---|---| | Skill tags | Repo languages + repo topics, filtered through vocabulary.normalize() | | Seniority estimate | Account age × (repos + followers) per documented thresholds | | Display name | user.name if not already set in profile | | Contact email | user.email if public and not already set in profile |

Public scope guarantee

Scope requested: read:user — public profile + public repos only.

Private-repo scopes are NEVER requested. This means:

• No employer-IP risk from private repos.
• No code, secrets, or private file access.
• Only what is already publicly visible on your GitHub profile.

Data residency

• Token: encrypted at ~/.terminalhire/github-token.enc (AES-256-GCM, same scheme as local profile).
• GitHub data stays on your machine — it enriches your local profile.
• GitHub fields cross the wire only in a consented LeadPayload when you type "yes".
• GitHub data is never sent silently.

Seniority thresholds

junior : age < 2 yr  OR  (repos < 5 AND followers < 10)
mid    : age 2–5 yr  AND repos >= 5
senior : age 5–9 yr  AND (repos >= 20 OR followers >= 100)
staff  : age >= 9 yr AND (repos >= 40 OR followers >= 500)

When signals conflict → conservative (lower) estimate. Unresolvable → undefined.

Mock mode (dev / CI)

No GitHub OAuth App registered yet? Set TERMINALHIRE_GITHUB_MOCK=1:

TERMINALHIRE_GITHUB_MOCK=1 terminalhire login

Uses the fixture at fixtures/github-sample.json instead of a live OAuth flow. No client ID needed. Safe for local development and CI.

Registering a GitHub OAuth App

1. Go to github.com → Settings → Developer settings → OAuth Apps → New OAuth App
2. Set "Authorization callback URL" to http://localhost (not used by device flow)
3. Enable Device Authorization in the OAuth App settings
4. Copy "Client ID" → set as GITHUB_CLIENT_ID in your environment
5. For public (CLI-only) OAuth Apps, the client secret is optional. If you set one, add it as GITHUB_CLIENT_SECRET.

export GITHUB_CLIENT_ID=Iv1.your_app_client_id
# optional:
export GITHUB_CLIENT_SECRET=your_client_secret

Status bar nudge

After terminalhire jobs runs and finds matches, the Claude Code status bar shows a once-per-session discovery nudge:

✦ N roles match your current work — run: terminalhire jobs

The nudge is printed at most once per Claude Code session. It reads only ~/.terminalhire/index-cache.json (a matchCount written by the last terminalhire jobs run). It makes zero network calls.

Spinner job surface

While you work inside Claude Code, terminalhire surfaces your top local job matches directly in the spinner — the ambient status indicator that appears while Claude is thinking.

• Enabled at install. No additional setup required.
• Computed locally. Match scoring runs on your machine against your encrypted local profile. No network call is made for the spinner display.
• Zero egress. The spinner reads only ~/.terminalhire/index-cache.json (written by the last terminalhire jobs run). Nothing leaves your device.
• Reversible. Disable at any time without uninstalling:

terminalhire spinner --off

Re-enable with:

terminalhire spinner --on

The spinner surface shows a short ranked summary (e.g. ✦ 3 matches — run: terminalhire jobs). It does not send your profile, fingerprint, or any data to any server.

Architecture (v3.1 hybrid)

Server                              Client (your machine)
──────────────────────────────      ─────────────────────────────────────────
Broad public pool:                  ~/.terminalhire/profile.enc  (AES-256-GCM encrypted)
  Greenhouse + Ashby (ATS)          ~/.terminalhire/github-token.enc  (AES-256-GCM)
  Himalayas + WWR + HN         GET  Fingerprint built from profile
  Coastal buyer-lead roles    ←─── /api/index (anonymous, no dev data)
                                    Local match() from @jpi/core
                                    Ranked list printed to terminal
                                    ↓
                               POST /api/lead  ←── ONLY on explicit "yes"
                                    Named-entity consent per role
                                    (GitHub fields included only if present AND consented)

GitHub (optional enrichment):
  github.com/login/device/code ←── Device flow (read:user scope only)
  api.github.com/users/<login>      Token + data stay on machine
  (public repos, topics, langs)

Zero dev-side egress during matching. The index download is anonymous. GitHub enrichment stays local. The only outbound payload with developer data is a consented LeadPayload, for buyer-lead roles only.

Privacy

| What happens locally | What crosses the wire | |---|---| | Profile accumulated from personal project sessions | GET /api/index — anonymous, no dev data | | Closed-vocab skill tags + seniority (encrypted at rest) | POST /api/lead — ONLY after explicit per-role "yes" consent | | GitHub token + public profile data (encrypted at rest) | GitHub fields in lead — ONLY after consent AND GitHub is connected | | Employer-repo sessions: language tags only | Nothing else | | git email domain + remote host (employer detection only) | |

Employer-repo exclusion (default on): if git config user.email is a corporate domain or git remote points to a non-personal host, only language-level tags (typescript, python, …) accumulate. Fine-grained framework/infra tags are excluded. The flag hasEmployerSessions is recorded locally but never emitted.

Local profile encryption

• Algorithm: AES-256-GCM via Node built-in crypto (no external deps).
• Key: stored at ~/.terminalhire/key with 0600 permissions. If keytar is installed, the OS keychain is preferred and the key file is not written.
• Profile file: ~/.terminalhire/profile.enc — JSON blob { iv, tag, ciphertext } (all hex-encoded).
• GitHub token file: ~/.terminalhire/github-token.enc — same format, same key.

Lead payload shape

The exact object sent to /api/lead when you consent (nothing else is sent):

{
  "opportunityId": "coastal:senior-fullstack-001",
  "buyerId": "coastal",
  "buyerLegalName": "Coastal Recruiting LLC",
  "approvedFields": {
    "skillTags": ["typescript", "react", "postgresql"],
    "seniorityBand": "senior",
    "displayName": "Your Name",
    "contactEmail": "[email protected]",
    "note": "Optional note typed at consent time",
    "github": {
      "login": "yourlogin",
      "profileUrl": "https://github.com/yourlogin",
      "topLanguages": ["typescript", "python", "go"],
      "publicRepos": 42
    }
  },
  "consentText": "You are about to share the following information with Coastal Recruiting LLC\n...",
  "createdAt": "2026-06-14T00:00:00.000Z"
}

• displayName, contactEmail, and note are included only if set.
• github is included only when: (a) you have run terminalhire login AND (b) you typed "yes" at the consent prompt.
• skillTags is always the full list from your profile.

Consent prompt text

The exact text shown before any lead is sent (GitHub profile connected):

You are about to share the following information with Coastal Recruiting LLC
for opportunity: <title> at <company> (<jobId>)

Fields that will be sent:
  • skillTags: ["typescript","react","postgresql"]
  • seniorityBand: "senior"
  • displayName: "Your Name"        ← only if set in profile
  • contactEmail: "[email protected]" ← only if set in profile
  • github.login: "yourlogin"
  • github.profileUrl: "https://github.com/yourlogin"
  • github.topLanguages: ["typescript","python","go"]
  • github.publicRepos: 42

GitHub fields above are public data only (scope: read:user). No private repos.

Nothing else leaves your machine. This action is specific to this role.
Coastal Recruiting LLC will use this to evaluate you for the role.
You can delete your profile at any time with: terminalhire profile --delete

Share your profile with Coastal Recruiting LLC for this role? [y/N]

Without GitHub: the github.* fields and the note about public scope are omitted.

Typing anything other than y or yes aborts with no network call.

Apply modes

| applyMode | What happens when you select a role | |---|---| | direct | Opens the employer's public URL in your terminal. No data sent. | | buyer-lead | Triggers the named-entity consent flow above. Nothing sent without "yes". |

The two modes are never silently conflated.

Zero-egress test (M-5)

node test/zero-egress.test.js

Environment variables

| Variable | Default | Description | |---|---|---| | TERMINALHIRE_API_URL | https://terminalhire.com | Base URL for /api/index and /api/lead (also accepts legacy JPI_API_URL) | | GITHUB_CLIENT_ID | (required for real OAuth) | GitHub OAuth App client ID (device flow) | | GITHUB_CLIENT_SECRET | (optional) | GitHub OAuth App client secret (public apps omit this) | | GITHUB_DEVICE_CLIENT_ID | (falls back to GITHUB_CLIENT_ID) | Device-flow specific client ID if different | | TERMINALHIRE_GITHUB_MOCK | 0 | Set to 1 to skip real OAuth and use the fixture (dev/CI); also accepts legacy JPI_GITHUB_MOCK |

File layout

apps/cli/
  bin/
    jpi.js          — statusLine nudge (once-per-session, zero egress)
    jpi-dispatch.js — 'terminalhire' bin entrypoint, routes subcommands
    jpi-jobs.js     — 'terminalhire jobs': fetch index, local match, consent flow
    jpi-login.js    — 'terminalhire login' / 'terminalhire logout': GitHub device flow + enrichment
    jpi-profile.js  — 'terminalhire profile': show/edit/delete encrypted profile
    refresh.js      — TOMBSTONE (v1 removed; exits non-zero)
  src/
    signal.ts       — local fingerprint extractor (reads dep files + extensions)
    profile.ts      — encrypted profile: read/write/accumulate/delete
    github-auth.ts  — GitHub device flow: token I/O + encrypted storage
  test/
    zero-egress.test.js  — M-5 zero-egress assertion suite
  install.js        — v3.1 installer with GitHub onboarding
  package.json

How data is used: local default vs consented lead

| Data | Default (local-enrichment) | Opt-in (consented lead) | |---|---|---| | Skill tags | Stored encrypted locally, used for local matching only | Included in approvedFields.skillTags on "yes" | | Seniority | Stored encrypted locally | Included in approvedFields.seniorityBand on "yes" | | Display name | Stored encrypted locally (pre-filled from GitHub if public) | Included if set and "yes" | | Contact email | Stored encrypted locally (pre-filled from GitHub public email) | Included if set and "yes" | | GitHub login / profileUrl | Stored in profile.github on terminalhire login | Included in approvedFields.github ONLY on "yes" | | GitHub topLanguages | Used locally for tag inference (closed vocab) | Included in approvedFields.github ONLY on "yes" | | GitHub token | Encrypted at ~/.terminalhire/github-token.enc | Never sent | | Private repos | Never accessed (scope: read:user) | N/A |