GACM - Git AI Context Manager

GACM syncs factual project context into AI coding tool files after every commit.

No API key. No network call during commit. Works offline by default.

Install

npx gacm-sync@latest init

Run it from the root of any Git repository. The command creates AGENTS.md and .gacmrc.json, installs an idempotent post-commit hook, and creates detected AI-tool sync targets when possible.

Check the install:

npx gacm-sync@latest status

Commit the generated context file:

git add AGENTS.md .gacmrc.json
git commit -m "Initialize GACM context"
git push

How It Works

git commit
  -> post-commit hook
  -> gacm sync
  -> extract Git metadata, changed files, tree, dependencies
  -> update managed blocks in AGENTS.md
  -> sync IDE-specific files when configured

GACM does not use AI to infer task status. It writes factual data only.

Commands

npx gacm-sync@latest init
npx gacm-sync@latest init --standalone
npx gacm-sync@latest sync
npx gacm-sync@latest run
npx gacm-sync@latest status
npx gacm-sync@latest repair
npx gacm-sync@latest install-hooks

npx gacm-sync run is kept as an alias for sync.

Use init --standalone when the target repository is not a Node/npm project or when you do not want the Git hook to call npx. The standalone hook calls the current GACM CLI through node directly.

Use @latest when you want to bypass older npx cache entries.

If installed globally, the shorter binary is also available:

npm install -g gacm-sync
gacm init
gacm sync
gacm status
gacm repair

Update a global install:

npm update -g gacm-sync

Daily Workflow

After init, keep using Git normally:

git add .
git commit -m "Your change"
git push

The post-commit hook runs GACM automatically after each commit. If AGENTS.md changes after the hook runs, commit it:

git add AGENTS.md
git commit -m "Update GACM context"
git push

You can also sync manually:

npx gacm-sync@latest sync
git status

Configuration

init creates .gacmrc.json if it does not exist:

{
  "recentCommitLimit": 20,
  "treeDepth": 2,
  "dependencyScanDepth": 3,
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "coverage"
  ],
  "syncTargets": [],
  "preferSymlink": true
}

Supported options:

• recentCommitLimit: number of recent commits rendered in AGENTS.md.
• treeDepth: maximum project tree depth.
• dependencyScanDepth: maximum depth for dependency manifest discovery.
• exclude: additional exact or glob-style file tree and dependency scan exclusions.
• syncTargets: extra files to sync from AGENTS.md, such as docs/context.md.
• preferSymlink: use symlinks when possible; set false to generate copies.

Stack Support

GACM scans dependency manifests without requiring node_modules or package installation in the target project.

Supported manifests:

• package.json
• requirements.txt
• pyproject.toml
• Cargo.toml
• go.mod

pyproject.toml and Cargo.toml are parsed with a TOML parser rather than ad hoc string matching. go.mod parsing supports require blocks, single require lines, inline comments, and deterministic whitespace normalization.

For basic monorepos, GACM scans manifests below the repository root up to dependencyScanDepth, respecting configured exclusions.

The dependency section also includes dependency delta for the latest commit: added and removed dependencies compared with the first parent commit.

Update Existing Project

In a project that already has GACM installed:

npx gacm-sync@latest init
npx gacm-sync@latest status
npx gacm-sync@latest sync

init is idempotent. Running it again does not duplicate managed markers, hooks, or existing files.

Verify Package Version

npm view gacm-sync version
npx gacm-sync@latest status

Status Output

gacm status reports:

• repo root
• post-commit hook active/missing
• AGENTS.md found/missing
• managed markers valid/broken
• sync targets such as CLAUDE.md, GEMINI.md, Copilot instructions, and Cursor .mdc
• additional sync targets configured in .gacmrc.json

Repair

If managed markers are broken, run:

npx gacm-sync repair

Repair rebuilds GACM marker blocks and preserves developer-authored content. A backup is written to AGENTS.md.bak.

Development Test

From this repository:

npm install
npm run lint
npm test
npm run test:install
npm run syntax
npm pack --dry-run

npm run test:install creates a clean temporary Git repository and runs gacm init twice to verify idempotent install behavior.

Publish

For maintainers publishing a new version:

npm test
npm run lint
npm run syntax
npm run test:install
npm pack --dry-run
npm version patch|minor|major
npm publish
git push
git push --tags

If npm asks for two-factor authentication:

npm publish --otp YOUR_2FA_CODE

Safety Guarantees

• GACM only rewrites content between documented managed markers in AGENTS.md.
• Developer-authored content outside managed markers is preserved during sync.
• repair writes an AGENTS.md.bak backup before rebuilding marker blocks.
• sync uses a local lock file so nested or concurrent hook runs skip safely.
• Stale sync locks are detected and recovered automatically.
• Managed writes use a temporary file and replace flow with backup restore on failure.
• Repositories with no commits render a deterministic "No commits yet" state.
• GACM works in repositories without node_modules.
• init --standalone avoids npm/npx usage from the installed Git hook.
• Hook failures are recoverable and do not fail the user's Git commit.
• GACM does not use network calls during sync.
• GACM does not use AI or external APIs to infer project state.
• GACM does not auto-inject a prepare script.
• If a symlink cannot be created, GACM falls back to a generated copy.
• Published npm package contents are restricted by the package.json files allowlist.
• CI runs on Ubuntu, Windows, and macOS.

Versioning

GACM follows Semantic Versioning:

• Patch versions contain bug fixes and documentation-only changes.
• Minor versions add backward-compatible commands, output, or safety improvements.
• Major versions may change command behavior, managed marker contracts, or package layout.

See CHANGELOG.md for release notes.

Managed Markers

<!-- GACM:TOPOLOGY:START -->
<!-- GACM:TOPOLOGY:END -->

<!-- GACM:RECENT_CHANGES:START -->
<!-- GACM:RECENT_CHANGES:END -->

<!-- GACM:DEPENDENCIES:START -->
<!-- GACM:DEPENDENCIES:END -->

License

MIT