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. By default, generated AI context files are local-only and are added to .gitignore to avoid merge conflicts.

Check the install:

npx gacm-sync@latest status

Commit the shared GACM configuration:

git add .gacmrc.json .gitignore
git commit -m "Initialize GACM"
git push

If you explicitly want to version AGENTS.md and generated sync targets, run:

npx gacm-sync@latest init --track

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 --track
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 init --track when a team intentionally wants to commit AGENTS.md and generated sync targets. Without --track, GACM treats those files as local developer context and adds them to .gitignore.

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. By default, AGENTS.md is local-only and should not be committed. Commit code and shared configuration as usual:

git add .
git commit -m "Your change"
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. These generated targets are added to .gitignore by init unless --track is used.
• 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.
• init keeps generated AI context local-only by default by adding AGENTS.md and generated sync targets to .gitignore.
• 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.

Supported Environments

GACM targets:

• Node.js 18 or newer for running the CLI.
• Git repositories on Windows, macOS, and Linux.
• Git Bash, PowerShell-driven Git workflows, and POSIX-style shells.
• Repositories with or without node_modules.
• npm/npx usage and standalone hooks installed with init --standalone.

Known Limitations

• GACM syncs after git commit, not after git push.
• Git hooks are local to each clone and are not transferred by git push.
• Basic monorepo support scans manifests by depth and configured exclusions; it does not model every workspace/package-manager graph.
• go.mod parsing is internal and focuses on require dependencies. replace, exclude, and other directives are ignored for dependency rendering.
• Symlink creation can fail on locked-down Windows environments; GACM falls back to generated copies.

Troubleshooting

• If AGENTS.md is missing, run npx gacm-sync@latest init.
• If managed markers are broken, run npx gacm-sync@latest repair.
• If a commit does not update context, run npx gacm-sync@latest status and check whether the post-commit hook is active.
• If npm/npx is not desired in hooks, run npx gacm-sync@latest init --standalone.
• If sync targets are generated copies instead of symlinks, set "preferSymlink": false or keep the fallback copy.
• If a stale lock blocks sync, rerun npx gacm-sync@latest sync; stale locks are recovered automatically.

Reporting Parser Issues

When reporting dependency parser issues, include:

• the manifest file type, such as pyproject.toml, Cargo.toml, or go.mod
• a minimal manifest snippet that reproduces the issue
• the expected dependency output
• the GACM version from npx gacm-sync@latest status

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