Heron · Stand still. Strike well.
A thinking partner for career transitions. Local-first. Open source. AI-agnostic.
Quick start · Documentation · Architecture · FAQ · Discord · Sponsor
The Heron stands motionless in shallow water. It waits. It watches. It evaluates every passing form. Then, when the moment is exactly right, it strikes -- once, precisely, and the work is done.
This is the wrong era for spray-and-pray job searches. Recruiters' attention is finite. So is yours. Heron is a thinking partner for people in career transition who'd rather make one excellent move than fifty mediocre ones.
It runs entirely on your machine. Your data is yours. See docs/PHILOSOPHY.md for the full posture.
Inbox -- triaged opportunities by score, sortable, multi-profile
A-F evaluation -- six-block analysis per role (fit, CV match, level, comp, personalization, prep)
Autopilot -- score-gated, daily-capped, opt-in · Mobile -- iOS / Android via Capacitor
- Pipeline + A-F evaluation -- every opportunity tracked with a six-block analysis (role fit, CV match, level strategy, comp research, personalization plan, interview prep). Multi-profile if you run parallel career tracks.
- CV generation -- ATS-optimized PDFs tailored per role, with AI-detect + keyword check baked in.
- Portal scanning -- 11 ATSes (Greenhouse, Ashby, Lever, LinkedIn, Indeed, Workday, Recruitee, SmartRecruiters, Workable, Personio, Teamtailor) hit directly via their APIs -- zero AI tokens on scan.
- Recruiter inbound + interview prep -- Gmail IMAP poller classifies offers; STAR+R stories ready when a screen lands.
- Autonomous apply (opt-in, off by default) -- score-gated, daily-capped, falls back to manual the moment anything looks off. Native everywhere via Capacitor (iOS / Android) + Electron (Mac/Win/Linux) + Apple Watch.
Heron is MIT-licensed and free -- $0/month, forever if you use a Claude Max plan via AGENT_CLI=claude. See docs/FAQ.md for the cost breakdown including direct API tokens and the optional Apple Developer Program fee for iOS builds.
macOS / Linux
brew install mise gh # one-time, if not installed
gh repo clone kaelys-js/heron && cd heron
mise install # Node 26 + pnpm 11 + Ruby 3.3 + Python 3.13
pnpm install # one-shot install across workspaces
pnpm setup:native # optional — Capacitor iOS/Android/Electron setup
pnpm dev # SvelteKit dashboard at localhost:5173Windows
scoop install mise gh # via Scoop
gh repo clone kaelys-js/heron; cd heron
mise install # Node 26 + pnpm 11 + Ruby 3.3 + Python 3.13
pnpm install
pnpm setup:native # optional
pnpm dev # SvelteKit dashboard at localhost:5173See docs/SETUP.md for the long form including Capacitor / iOS / Apple Watch builds, fastlane signing, and the pnpm doctor:native preflight check.
| Topic | Where |
|---|---|
| Philosophy (local-first, quality-over-volume) | docs/PHILOSOPHY.md |
| Architecture (data flow, backend discovery, tech stack, repo layout) | docs/ARCHITECTURE.md |
| FAQ (cost, auto-apply, privacy, supported ATSes) | docs/FAQ.md |
| Comparable tools (JobScan / Teal / AIHawk and where Heron sits) | docs/COMPARISON.md |
| Setup (Capacitor, iOS, Watch, signing) | docs/SETUP.md |
| Development (daily commands, branding SSOT, release flow) | .github/CONTRIBUTING.md |
| Testing (Vitest matrix, coverage gates) | docs/TESTING.md |
| Data contract (per-user / per-profile layout, what's auto-updated) | docs/DATA_CONTRACT.md |
| Governance + trademark | docs/GOVERNANCE.md, docs/TRADEMARK.md |
| Channel | Use for |
|---|---|
| 💬 Discord | Real-time questions, setup help, show-and-tell -- typically same-day during EU/US working hours |
| 📚 GitHub Discussions | Async Q&A + ideas + roadmap + success stories |
| 🐛 Issues | Bugs + feature requests (use the templates) |
| 🎓 I got hired | Tell the Hall of Fame your story |
| 📰 Press kit | Pre-written boilerplate for journalists + bloggers |
| 🔒 Security disclosure | Private vulnerability reporting (NOT public issues) |
See .github/SUPPORT.md for the "where should I ask this?" routing matrix.
Heron's security posture covers Better Auth + cookies, CSP + DOMPurify, rate limiting, path-traversal guards, audit logging, multi-user IDOR prevention, OSSF Scorecard, CodeQL across TS+Python+Swift, SLSA L2 build provenance attestations, lockfile-lint, license-compliance, TruffleHog secret-scanning, StepSecurity harden-runner, SHA-pinned actions, branch-protection rulesets, signed commits + DCO.
See .github/SECURITY.md for the full posture + vulnerability disclosure flow.
We welcome PRs. Start with .github/CONTRIBUTING.md -- covers the contributor ladder (Participant → Contributor → Triager → Reviewer → Maintainer), commit-message rules, DCO sign-off, and the "what we do NOT accept" list.
Issues labeled good first issue are scoped for first-time contributors. Join Discord before opening a feature PR -- saves you scope-rework.
This project follows the all-contributors specification. Non-code contributions (docs, design, translation, ideas, infrastructure) count. See .all-contributorsrc.
Heron is built in volunteer time. If it saves you a job-search week, consider sponsoring. Sponsors get a thank-you in CHANGELOG.md + a Discord role.
Original work © 2026 santifer, MIT-licensed. See REUSE.toml for the full SPDX attribution.
MIT for code. CC-BY-4.0 for branding/* (logos, mascot specs, voice guide). CC0-1.0 for docs/examples/*. See REUSE.toml for the full SPDX declaration.
This fork © resist.js.
See docs/TRADEMARK.md for trademark policy, docs/LEGAL_DISCLAIMER.md for usage disclaimers, and docs/GOVERNANCE.md for contribution governance.
Maintained by @kaelys-js. Sponsor · Press kit · Discord · [email protected]
MIT licensed.