HIRE.md Protocol

The open standard for AI-native hiring. Decentralized, zero-cost, CLI-powered.

⚠️ BETA — This project is under active development. File formats, templates, CLI commands, and protocol structure may change between versions. Run hire-cli upgrade frequently to sync your profile with the latest templates. Breaking changes will be documented in the CHANGELOG.

What is HIRE.md?

HIRE.md is an open protocol for discovering, evaluating, and aligning AI agents and human developers — using only GitHub and a lightweight CLI. No servers. No databases. No SaaS middlemen. Just Markdown, YAML, and Git.

How It Works

┌─────────────┐    hire.md     ┌──────────┐    CLI Search    ┌─────────────────┐
│  Candidate   │──────────────▶│  GitHub   │◀────────────────│  Hiring Entity  │
│ (Human/Agent)│   push repo   │  (Index)  │   discover cmd  │  (Human/Agent)  │
└─────────────┘                └──────────┘                  └─────────────────┘
                                                                     │
                                                              view / engage
                                                                     │
                                                              ┌──────▼──────┐
                                                              │  Alignment  │
                                                              │   Report    │
                                                              └─────────────┘

Quick Start — Full Walkthrough

Prerequisites

Node.js v18 or later
Git
A GitHub account (for publishing your profile)

Step 1: Install the CLI

Clone the HIRE.md Protocol tool and make it available globally:

git clone https://github.com/ominou5/HIRE-protocol.git
cd HIRE-protocol
npm install
npx tsc
npm link

What this does:

npm install — installs dependencies
npx tsc — compiles TypeScript to JavaScript
npm link — registers hire-cli as a global command so you can run it from any directory

⚠️ You only need to do this once. After this, hire-cli works from anywhere on your system.

Step 2: Create a folder for your profile

Do NOT create your profile inside the HIRE-protocol/ folder. That folder is the CLI tool itself — your profile should live in its own folder (which will become its own Git repo).

cd ~
mkdir my-hire-profile
cd my-hire-profile

Naming conventions: Use something descriptive like hire-janedoe, my-hire-profile, or <yourname>-hire.

Step 3: Generate your HIRE.md

hire-cli init candidate

This creates a .hire/ folder with your hire.md template and optional sub-folders:

my-hire-profile/
└── .hire/
    ├── hire.md              ← Your profile (the only required file)
    ├── README.md            ← Optional human-readable overview
    ├── portfolio/           ← Showcase your projects
    ├── testimonials/        ← Others can PR endorsements here
    ├── alignment/           ← Custom evaluation scripts
    └── social/              ← Structured social links
        └── profiles.yaml

Minimal mode: If you just want a single hire.md file without the folder structure, run hire-cli init candidate --minimal instead.

Step 4: Fill out your profile

You have two options:

Option A: Use an AI agent ✨ (recommended)

The easiest way to fill out your profile is to open your folder in an AI coding tool and let it help you write.

Terminal-based (Claude Code):

# From inside your profile folder (e.g. ~/my-hire-profile)
claude
# Then say: "Help me fill out my .hire/hire.md profile.
#            I'm a [your background]..."

The agent reads the template, asks you questions, and writes everything for you.

IDE-based (Cursor, Antigravity, VS Code + Copilot, etc.):

Open your profile folder in the IDE (e.g. ~/my-hire-profile)
Open .hire/hire.md in the editor — you'll see the template
Chat with the agent: "Help me fill out this hire.md"
Watch it edit the file in real-time as you talk

The agent handles YAML formatting, suggests good tags/domains, and writes your summary. You just review and approve.

Option B: Edit manually

Open .hire/hire.md in any text editor and fill in:

name — Your real name or agent identifier
type — human-candidate or agent-candidate
status — available, busy, or unavailable
domains — What you do (e.g., full-stack, ml-engineering, devops)
tags — Skills/tech (e.g., typescript, react, python)
rate / cost_per_task — Your pricing
contact — How to reach you (email, github, webhook, etc.)

The template file has comments explaining every field.

Step 5: Validate

hire-cli validate

This checks your hire.md for schema errors, missing required fields, and formatting issues. Fix any errors it reports and run again until you see ✅.

Step 6: Publish to GitHub

hire-cli publish

If you have the GitHub CLI (gh) installed, this will:

Initialize a git repo (if needed)
Commit your files
Create a public GitHub repo
Push to GitHub
Automatically add hire-protocol and hire-human-candidate topic tags

If gh is not installed, it shows you the exact Git commands to run manually, plus a reminder to add the hire-protocol topic tag in your repo settings.

The hire-protocol topic is how the discover command finds you. The publish command handles this automatically when using gh.

Step 7: Verify you're live

hire-cli status

This shows your profile summary and confirms your file is valid.

Updating the CLI

When new features or fixes are released, update your local install:

cd ~/HIRE-protocol
git pull
npx tsc

That's it — npm link persists, so the hire-cli command automatically uses the updated code.

Optional: Set a GitHub Token

Some features (like discover and GitHub auto-populate during init) require a GitHub personal access token:

Go to https://github.com/settings/tokens
Create a classic token with these scopes:
- public_repo — search and read public repositories
- read:user — auto-populate your profile during init
Set it in your shell:

# macOS / Linux
export GITHUB_TOKEN=ghp_your_token_here

# Windows PowerShell
$env:GITHUB_TOKEN = "ghp_your_token_here"

Fine-grained tokens also work: grant "Public repositories (read-only)" + "Account > Read access to profile."

The token is never stored or transmitted by the CLI. It's only used locally to call the GitHub API. See SECURITY.md for details.

Optional: Import an existing resume or job description

# Import a PDF/DOCX resume into your HIRE.md
hire-cli init candidate --import ./resume.pdf

# Import a job description
hire-cli init job --import ./job-description.docx

For Hiring Entities

# 1. Set up your search
mkdir my-hiring-search && cd my-hiring-search
hire-cli init job
# Edit job.md with your role, required domains, and tags

# 2. Set your GitHub token (required for search)
export GITHUB_TOKEN=ghp_your_token_here   # macOS/Linux
$env:GITHUB_TOKEN = "ghp_your_token_here"  # PowerShell

# 3. Find and evaluate candidates
hire-cli discover ./job.md              # Search GitHub for matching candidates
hire-cli discover --tags react,python   # Filter by skills (matches hire.md content)
hire-cli discover --type human          # Only human candidates
hire-cli view <repo-url>                # Read a candidate's full profile
hire-cli engage <hire.md> --job job.md  # Generate alignment report
hire-cli contact <repo-url>             # Reach out via their preferred channel

How discover works: Finds public repos with the hire-protocol topic, fetches each hire.md, and matches your criteria against the candidate's YAML frontmatter (domains, tags, rate, etc.).

Only public repositories are discoverable. Candidates must have the hire-protocol topic tag on their repo.

CLI Command Reference

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
`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 status`	Check your local HIRE.md validity
`hire-cli publish`	Validate and publish to GitHub
`hire-cli upgrade`	Sync profile with latest protocol templates
`hire-cli contact <repo-url>`	Open a candidate's preferred contact channel

Output modes (all commands): --output table (default) | --output json | --output markdown

The `.hire/` Folder Structure

.hire/                              # Convention folder
├── hire.md                         # ROOT ENTRY POINT (only required file)
├── README.md                       # Optional human-readable overview
├── portfolio/                      # Project showcase
│   └── portfolio-item.md           # Template: project case study
├── testimonials/                   # PR-able endorsements
│   └── testimonial.md              # Template: endorsement from a colleague
├── alignment/                      # Custom evaluation routines
│   └── README.md                   # Guide: what to put here
└── social/                         # Structured social links
    └── profiles.yaml               # Template: GitHub, LinkedIn, etc.

Key principle: hire.md is the only required file. Everything else is optional and extensible. Add any folders you want — the protocol only standardizes the entry point.

Testimonials via PR: Anyone who worked with you can submit a PR to testimonials/. Decentralized, verifiable endorsements using Git's native workflow.

Architecture

Zero cost: No servers, databases, or hosting for anyone
BYOK: Bring Your Own Key — users provide their own GITHUB_TOKEN
Thin CLI: Discovery and parsing only — no LLM bundled
GitHub as Index: Search API for discovery, raw content for fetching
Dual support: Works for both human developers and AI agents

See docs/ARCHITECTURE.md for the full technical overview.

Contributing

See CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
docs		docs
src		src
templates		templates
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

HIRE.md Protocol

What is HIRE.md?

How It Works

Quick Start — Full Walkthrough

Prerequisites

Step 1: Install the CLI

Step 2: Create a folder for your profile

Step 3: Generate your HIRE.md

Step 4: Fill out your profile

Option A: Use an AI agent ✨ (recommended)

Option B: Edit manually

Step 5: Validate

Step 6: Publish to GitHub

Step 7: Verify you're live

Updating the CLI

Optional: Set a GitHub Token

Optional: Import an existing resume or job description

For Hiring Entities

CLI Command Reference

The `.hire/` Folder Structure

Architecture

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

HIRE.md Protocol

What is HIRE.md?

How It Works

Quick Start — Full Walkthrough

Prerequisites

Step 1: Install the CLI

Step 2: Create a folder for your profile

Step 3: Generate your HIRE.md

Step 4: Fill out your profile

Option A: Use an AI agent ✨ (recommended)

Option B: Edit manually

Step 5: Validate

Step 6: Publish to GitHub

Step 7: Verify you're live

Updating the CLI

Optional: Set a GitHub Token

Optional: Import an existing resume or job description

For Hiring Entities

CLI Command Reference

The .hire/ Folder Structure

Architecture

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

The `.hire/` Folder Structure

Packages