humanfile

Move fast with AI, without losing human ownership.

humanfile is a CLI and npm library for declaring boundaries for coding agents. You write .human files using .gitignore-style patterns so both agents and collaborators can see which areas are expected to be human-maintained. Every path gets a protection level:

In plain terms	Level	Syntax (in .human)
Agent may edit freely	free	(no matching rule)
Agent must ask you first	confirm	plain pattern, e.g. docs/specs/
Agent must not edit	readonly	! + pattern, e.g. !LICENSE

The detailed rules (precedence, ! vs .gitignore negation, examples) are in docs/specs/human-file-format.md. Prefer confirm for areas you own day-to-day. Use readonly sparingly for files agents must never touch.

Warning

This repository is still under active development and is not fully tested yet. Expect breaking changes and rough edges.

Why humanfile?

AI coding agents can modify any file in your repository. Without boundaries:

• Your carefully crafted documentation gets overwritten by AI-generated text
• A colleague's hand-tuned config gets silently replaced in an AI-driven PR
• Developers lose motivation to invest in manual editing — why bother if AI will just overwrite it?
• Agents can't tell which files are the source of truth when they see conflicting information

humanfile gives you a lightweight policy that limits the highest-risk edits while keeping delivery speed high: free for velocity, confirm for consent, readonly for hard stops.

Minimal .human example:

docs/specs/    # confirm — ask before editing specs
!LICENSE       # readonly — do not edit (use sparingly)

How it shows up in your repo

                    .human
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
     🤖 Agent       🪝 Git         ⚙️ CI
     guidance       hooks         Action

  check before   optional blocks  PR feedback
  editing        on commit/push   in CI

• Agent guidance: humanfile install drops instructions for Cursor, Copilot, Claude Code, and other tools (see table below).
• Git hooks: humanfile guard install runs checks on staged files or on push (optional).
• CI: the published GitHub Action comments on PRs and can fail when readonly rules are broken (optional).

Quick Start

Requires Node.js 20+ for npx humanfile.

If you run these commands a lot, you can install the CLI once so humanfile ... works as a global command:

# install the humanfile CLI globally (enables `humanfile ...`)
npm i -g humanfile

If you don't want a global install, keep using npx humanfile ... (or pnpx humanfile ... if using pnpm).

1. Create a .human file

# create a starter .human in the repo root
npx humanfile init

This writes a starter .human in the project root. You can also author .human by hand.

2. Install agent guidance

# write agent/editor guidance files (auto-detect environment)
npx humanfile install

Writes editor- or platform-specific instructions so agents know your boundaries. You may target one environment explicitly with:

npx humanfile install --env cursor   # Cursor (.cursor/rules/humanfile.mdc)
npx humanfile install --env copilot  # GitHub Copilot (.github/copilot-instructions.md)
npx humanfile install --env claude   # Claude Code (CLAUDE.md)
npx humanfile install --env windsurf # Windsurf (.windsurfrules)
npx humanfile install --env cline    # Cline (.clinerules)
npx humanfile install --env codex    # Codex (AGENTS.md)

Install walkthrough (Cursor, non-interactive):

3. (Optional) Git hooks

# install a pre-commit hook that checks staged files
npx humanfile guard install --hook pre-commit --mode staged

Run this from any directory inside your git checkout (including monorepo package folders). The CLI resolves the repository root and writes hooks under <repo>/.git/hooks.

Optional local enforcement before commits or pushes. See docs/specs/cli-spec.md and packages/core/DEVELOPMENT.md for hooks, modes, and policies.

Guard walkthrough:

4. (Optional) Enforce on pull requests

The GitHub action is published from this monorepo repo. Reference it by tag (for example action-v0.1.3) and subpath packages/action:

name: humanfile
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: zhangyu94/humanfile/packages/action@action-v0.1.3
        with:
          ai-threshold: 1000
          fail-on-readonly: true

Action setup details: packages/action/README.md and docs/specs/action-spec.md.

Example PR run (GitHub Action CI):

Common CLI commands

Effective levels: humanfile check classifies the whole tree or a single path so you can sanity-check patterns before relying on agents or CI. humanfile ls lists discovered .human files. humanfile explain shows provenance for one path (add --non-matching / -n for free paths).

npx humanfile check                         # classify the whole tree (effective levels)
npx humanfile check path/to/file            # classify a single path
npx humanfile ls                            # list discovered .human files
npx humanfile explain path/to/file          # show why a path is confirm/readonly
npx humanfile explain -n path/to/free-file  # show why a path is free (non-matching)

Classification walkthrough (check, ls, explain):

Guards (optional; see Quick Start step 3):

# install pre-commit + pre-push (staged mode)
npx humanfile guard install --hook both --mode staged
# ai-aware diff policy tuned for large PRs
npx humanfile guard install --hook both --mode diff --policy ai-aware --ai-threshold 1200
# show which hooks are installed
npx humanfile guard status

Full CLI contract: docs/specs/cli-spec.md.

humanfile install targets

Platform	Path written by install
Cursor	.cursor/rules/humanfile.mdc
GitHub Copilot	.github/copilot-instructions.md
Claude Code	CLAUDE.md
Windsurf	.windsurfrules
Cline	.clinerules
Codex	AGENTS.md

Library API

To depend on the humanfile package from TypeScript or Node: packages/core/README.md and docs/specs/core-library-api-spec.md.

Learn more

Doc	What it's for
docs/SPECS.md	Index of product specs
docs/specs/human-file-format.md	.human syntax and semantics
docs/specs/editor-modes-and-expected-behavior.md	How editor modes relate to confirm / readonly
docs/DESIGN.md	Design philosophy
ARCHITECTURE.md	Monorepo layout
CONTRIBUTING.md	Contributing
AGENTS.md	Map for AI agents working in this repo