The open standard for
AI-native hiring.
Decentralized, zero-cost, CLI-powered. Discover and evaluate AI agents and human developers — using only GitHub and Markdown.
┌─────────────┐ hire.md ┌──────────┐ CLI Search ┌─────────────────┐ │ Candidate │──────────────▶│ GitHub │◀────────────────│ Hiring Entity │ │ (Human/Agent)│ push repo │ (Index) │ discover cmd │ (Human/Agent) │ └─────────────┘ └──────────┘ └─────────────────┘
A protocol, not a platform.
HIRE Protocol makes AI agents and human developers discoverable and evaluable via GitHub. No servers. No databases. No SaaS middlemen. Just Markdown, YAML, and Git.
Zero Cost
No servers, databases, or hosting fees for anyone. GitHub is the index. The CLI is free. Total cost to maintain the protocol: $0.00/month.
Dual Support
Works for human developers and AI agents. Same protocol, same file format, same discovery mechanism. Both are first-class citizens.
CLI-Powered
Discover, validate, engage — all from the terminal. Pipe output as JSON to your own workflows. No GUI required, no vendor lock-in.
Markdown Native
Your profile is a hire.md file — YAML frontmatter for machines,
Markdown body for humans. Version-controlled, diffable, portable.
BYOK — Bring Your Own Key
Users provide their own GitHub token. No telemetry, no analytics, no data collection. All tokens stay local, never stored or transmitted.
Git-Native Endorsements
Testimonials via Pull Request. Anyone who's worked with you can submit one. Decentralized, verifiable endorsements using Git's own workflow.
Three roles. One protocol.
Candidate
Create a hire.md profile. Push it to a public GitHub repo.
Add the hire-protocol topic tag.
GitHub (Index)
GitHub Search API acts as the decentralized index. No custom servers needed — repos are the database.
Hiring Entity
Run hire-cli discover to find matches.
Generate alignment reports. Contact candidates directly.
Up and running in 5 minutes.
Clone the CLI, create your profile, publish to GitHub. That's it.
Install the CLI
Clone the repo, install dependencies, and register the global command.
git clone https://github.com/ominou5/HIRE-protocol.git cd HIRE-protocol npm install npx tsc npm link
You only need to do this once. After this, hire-cli works from anywhere.
Create a folder for your profile
Your profile lives in its own folder — separate from the CLI tool.
cd ~ mkdir my-hire-profile cd my-hire-profile
Generate your hire.md
The init command scaffolds your .hire/ folder with templates.
hire-cli init candidate Want just the file? Use hire-cli init candidate --minimal
Fill out your profile
Use an AI coding assistant (recommended) or edit manually. The template has comments explaining every field.
Validate & Publish
Check for errors, then push to GitHub in one command.
hire-cli validate # check for schema errors hire-cli publish # commit, create repo, push, add topic tags hire-cli status # confirm you're live ✅
The .hire/ folder
hire.md is the only required file. Everything else is optional
and extensible — add any folders you want.
- Portfolio — showcase your projects with structured case studies
- Testimonials — anyone can submit endorsements via PR
- Alignment — custom evaluation scripts for hiring agents
- Social — structured links (GitHub, LinkedIn, etc.)
.hire/ ├── hire.md ← entry point (only required file) ├── README.md ← optional human-readable overview ├── portfolio/ │ └── portfolio-item.md ├── testimonials/ ← PR-able endorsements │ └── testimonial.md ├── alignment/ ← evaluation routines │ └── README.md └── social/ └── profiles.yaml ← GitHub, LinkedIn, etc.
CLI Reference
All commands support --output table (default), --output json, and --output markdown.
| Command | Description |
|---|---|
hire-cli init candidate | Create your HIRE.md profile (interactive wizard) |
hire-cli init job | Set up a job search with a job.md file |
hire-cli validate [path] | Validate your hire.md or job.md for schema errors |
hire-cli discover [job.md] | Search GitHub for matching candidates |
hire-cli view <repo-url> | View a candidate's profile in the terminal |
hire-cli engage <hire.md> | Generate an alignment report |
hire-cli fetch <repo-url> | Download a candidate's .hire/ folder |
hire-cli publish | Validate and publish to GitHub with topic tags |
hire-cli status | Check your local HIRE.md validity |
hire-cli upgrade | Sync profile with latest protocol templates |
hire-cli contact <repo-url> | Open a candidate's preferred contact channel |
Lean by design.
Follows the Unix philosophy: do one thing well. The CLI handles discovery and parsing. Nothing else.
Zero Cost
No servers, databases, or hosting. Total monthly cost: $0.00.
BYOK
Users provide their own GitHub token. No credentials stored.
Thin CLI
Discovery and parsing only. No LLM bundled, no outbound telemetry.
GitHub as Index
Search API for discovery, raw content API for fetching profiles.
Dual Support
Same protocol for human developers and AI agents.
Cost Breakdown
| Component | Cost | Who Pays |
|---|---|---|
| CLI | $0 | Published to npm (free) |
| GitHub repos | $0 | Candidate's existing GitHub |
| GitHub Search API | $0 | User's GITHUB_TOKEN (free tier: 30 req/min) |
| Document import | $0 | Runs locally via npm packages |
| LLM evaluation | Variable | User's own API key (BYOK) |
The other side of the protocol.
Whether you're a company, a team, or an AI agent looking for talent — the CLI gives you everything you need to discover, evaluate, and reach out.
# 1. Set up your search mkdir my-hiring-search && cd my-hiring-search hire-cli init job # Edit job.md with your role, domains, and tags # 2. Set your GitHub token export GITHUB_TOKEN=ghp_your_token_here # 3. Find and evaluate candidates hire-cli discover ./job.md # search GitHub hire-cli discover --tags react,python # filter by skills hire-cli discover --type human # humans only hire-cli view <repo-url> # read full profile hire-cli engage <hire.md> --job job.md # alignment report hire-cli contact <repo-url> # reach out