AI’m Hooman

"beep boop ... ai'm hooman"

aimhooman: AI works. Hoomans ship.

Human-owned, not human-washed. aimhooman removes tooling residue and sets human
ownership. It does not fake authorship or strip disclosure your policy requires.

TL;DR

Keep AI session files and stray Co-authored-by: lines out of your Git history —
a vendor-neutral guard, repair-first by default, without a per-tool ignore list and
without faking who wrote the code. Zero runtime dependencies. Node 22.8+, Git 2.28+.

The problem

Your AI agent works in your repo and quietly leaves state behind: .claude/session.json,
chat history, caches, and Co-authored-by: an AI. One git add -A later, it is in your
history. Ignore lists are per-tool and never complete, and a local git hook is one
--no-verify away from being skipped.

How it works

One detection core, many enforcement surfaces. On the default profile the ordinary commit
path repairs hygiene findings when it can; commit-msg checks the pinned would-be tree,
and the final ref boundary independently scans every commit introduced to HEAD or a
branch. A block that survives repair stops the commit; an incomplete scan warns on
clean/compliance and still vetoes at the final ref guard, unless the only gap is a
file over the per-file size budget. pre-push scans what a push would send, so a commit
pushed by raw object ID cannot bypass the local guards.

flowchart TD
    SESS([Session start]) -. once .-> EXCL["Auto-exclude known<br/>AI artifacts in .git/info/exclude"]
    AGENT([Agent calls a tool]) -. proactive .-> ADV["PreToolUse parses the command,<br/>resolves repo/policy, and checks bypass risk"]
    RUN([You run the CLI]) -. on demand .-> CLI["check · fix · explain"]

    COMMIT([Ordinary git commit or merge]) --> PRE["pre-commit / pre-merge-commit<br/>run predecessor, resolve staged policy,<br/>scan exact index"]
    DIRECT([Sequencer or direct ref path<br/>cherry-pick · rebase · fetch · worktree · update-ref]) --> REF
    PRE -->|clean: safe repair| MSG["commit-msg snapshots would-be tree,<br/>runs predecessor, then checks<br/>the message and pinned full tree"]
    PRE -->|strict violation or failed repair| BLOCK([Operation stops])
    MSG -->|message and tree accepted| REF["reference-transaction prepared<br/>scans what each introduced commit changes<br/>(messages of locally authored commits only)"]
    MSG -->|unsafe or unrepairable| BLOCK
    REF -->|accepted| SHIP([Ref update commits])
    REF -->|violation or incomplete scan| BLOCK
    PUSH([git push]) --> PREPUSH["pre-push<br/>scans every commit the push would send,<br/>messages included — even a push by raw object ID"]
    PREPUSH -->|accepted| SENT([Objects leave for the remote])
    PREPUSH -->|violation| BLOCK

    classDef entry fill:#f8fafc,stroke:#94a3b8,color:#0f172a,stroke-width:1.5px
    classDef hook fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px
    classDef ok fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1.5px
    classDef stop fill:#fef2f2,stroke:#ef4444,color:#7f1d1d,stroke-width:2px

    class SESS,AGENT,RUN,COMMIT,DIRECT,PUSH entry
    class PRE,MSG,REF,PREPUSH hook
    class SHIP,SENT ok
    class BLOCK stop

• Prevent: known AI artifacts go into .git/info/exclude on session start, so they never show in git status.
• Catch: pre-commit unstages what slips through; commit-msg removes exact high-confidence attribution lines.
• Advise: the plugin's PreToolUse reports paths early and denies protected commit/ref operations it cannot prove safe.
• Block: strict cancels instead of repairing; on every profile the final ref guard stops an unscannable or blocked commit.

Quick start

npm install -g @rmyndharis/aimhooman
aimhooman init            # git hooks + local excludes; normally no worktree files
git commit -m "ship it"   # guarded automatically

• aimhooman init --gitignore also writes the managed ignore block into the worktree
  .gitignore — commit it to share the ignore set with every clone. Default stays local.
• aimhooman init --global --yes is the advanced one-time setup for terminal Git: it
  changes global core.hooksPath for every inheriting repository — caveats in
  docs/cli-reference.md.

Profiles

• Default (clean): repairs and warns; the final ref guard still vetoes what it cannot fully scan.
• Strict for teams: findings cancel the commit; commit .aimhooman.json so every clone shares the baseline.

compliance repairs like clean but keeps required AI attribution. Details: docs/policy.md.

What it catches

• AI session/state artifacts: .claude/session*.json, .codex/sessions/, .aider.*
  — catalog: docs/catalog.md. Just want the ignore list? docs/ai-artifacts.gitignore.
• AI attribution in commit messages (Co-authored-by: an AI, "Generated with" lines, AI noreply trailers) and AI markers left in code.
• Review-required files: .aimhooman.json, AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md.

Secret scanning is out of scope since v0.3.0 — docs/secrets.md has the why and the gitleaks setup.

Use it in your AI coding tool

Claude Code runs the plugin hook every session; Codex after you trust the hooks with
/hooks; Copilot's repository hook needs aimhooman on PATH. None replaces the Git
guard from aimhooman init — full matrix: docs/design/agent-portability.md.

Run it in CI

The repository ships a .pre-commit-hooks.yaml for pre-commit.com and an action.yml
GitHub Action that scans the exact pull-request range — the tier a laptop cannot skip.
Setups, plus gitleaks, husky, and lint-staged: docs/integrations.md.

Docs

Contributing

Contributions are welcome — see CONTRIBUTING.md for rules, host
adapters, tests, and the commit policy. This project has a code of conduct;
by participating you agree to abide by it. To report a security issue, see
SECURITY.md. Architecture notes live in docs/design/.

Support

If aimhooman keeps your Git history clean, you can support its development by buying me a coffee.

License

This project is licensed under the MIT License – free for personal and commercial use.

See LICENSE for details.

Made with ❤️ by Yudhi Armyndharis & aimhooman contributors