hashfm-agent

Extracts hashfm blocks from shell scripts and produces a machine-readable index for LLM agents.

hashfm-agent is the primary implementation of the hashfm convention. It reads # --- delimited YAML blocks from scripts and generates an index — a minimal, token-efficient map of available tools.

---

Getting Started

Install (macOS and Linux):

curl -o- https://raw.githubusercontent.com/sidisinsane/hashfm-agent/main/install.sh | bash

Install (Windows):

irm https://raw.githubusercontent.com/sidisinsane/hashfm-agent/main/install.ps1 | iex

---

Generate an index:

# Current directory
hashfm-agent generate .

# With flags
hashfm-agent generate --format jsonl --output index.jsonl .

---

The Hashfm Convention

hashfm-agent reads a small YAML payload from scripts delimited by # ---:

#!/usr/bin/env bash
# ---
# description: Deploy the application to staging
# usage: deploy.sh <environment> [--dry-run]
# exits:
#   0: success
#   1: environment not provided
#   2: deployment failed
# ---

See hashfm for the full specification — delimiters, line prefix, parser rules, and the config file schema.

---

Configuration

Set persistent defaults in .hashfm:

version: "1.1.0"
project:
  name: "my-project"

hashfm-agent:
  generate:
    format: tsv
    recursive: true
    output: index.tsv
    exclude:
      - _*.sh
    include:
      - scripts/*.sh

Field	Type	Default	Description
format	string	tsv	Output format: tsv, jsonl, or yaml.
output	string	—	File path to write the index to. If empty, writes to stdout.
recursive	boolean	false	Whether to scan subdirectories.
exclude	list	—	Blacklist of glob patterns. Matching files are skipped.
include	list	—	Whitelist of glob patterns. Only matching files are processed. If empty, all .sh files are included.

See hashfm/CONFIG.md for supported filenames, schema, and validation rules.

---

Output Formats

Format	Token cost	Use case
tsv (default)	lowest	LLM agent consumption
jsonl	medium	Pipelines, further processing
yaml	highest	Human readability

---

Documentation

Document	What it covers
spec.md	Agent field schema, index formats, agent workflow
hashfm/spec.md	Base hashfm syntax and rules
hashfm/CONFIG.md	.hashfm config file design and implementation

---

Development

Prerequisites

• Go 1.26.2
• golangci-lint — for Go linting
• lefthook — for pre-commit hooks

Setup

# Install lefthook
brew install lefthook

# Enable hooks
lefthook install

Linting

Go files are linted with golangci-lint. Run manually:

golangci-lint run ./...

Hooks run automatically on commit via lefthook.