ai-context-sync (acs)

Git-native AI team memory. Every commit gets a structured changelog in .ai/changelogs/ — automatically, without changing how your team works.

Your AI tools read it before starting. Your teammates read it during review. The context that usually disappears after a session stays in the repo forever.

The problem

Teams using AI coding tools ship features without leaving behind usable context. The AI generates artifacts but swallows the reasoning. Git captures what changed. Nobody captures why, what was tried, what was rejected, or how to extend it.

The result: Bob pulls John's feature branch and has to ask John what the AI did. Mark reviews a PR and can't explain the AI-generated code he's responsible for.

How it works

You commit code
      │
      ▼
pre-commit hook fires
  ├── Claude Code already staged a changelog? → exit (it handled it)
  ├── llm_command configured? → call it, generate rich changelog
  └── no AI tool? → write minimal changelog (enrichable later)
      │
      ▼
.ai/changelogs/changelog-2026-04-03T15-30-00Z-a3f2.md committed

post-commit hook
  └── patch commit hash → validate schema → log errors if any

Next developer pulls the branch, asks their AI tool anything about the code — it reads .ai/ first (via AGENTS.md / CLAUDE.md installed by acs init) and actually knows what happened.

Install

Mac / Linux / WSL:

curl -fsSL https://raw.githubusercontent.com/USER/ai-context-sync/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/USER/ai-context-sync/main/install.ps1 | iex

Already have Node.js >= 18:

npm install -g @tosanoob/acs

Windows note: git hooks run in Git Bash. WSL also works. Native cmd.exe does not.

Quickstart

cd your-repo
acs init

That's it. Make a commit. Check .ai/changelogs/.

acs init will:

• Create .ai/changelogs/, .ai/CONSTITUTION.md, .aiignore
• Detect Claude Code, Codex, or Gemini in your PATH
• Install the AI skill so Claude/Codex generates changelogs automatically
• Install pre-commit and post-commit git hooks
• Write AGENTS.md so AI tools know to read .ai/ before starting

Commands

acs init

Set up acs in the current repository. Safe to re-run — skips anything already present.

acs init
acs init --skip-verify   # skip Claude Code smoke test

acs why <file>

Explain why a file looks the way it does. Aggregates all changelogs for commits that touched the file.

acs why src/auth.ts
acs why src/auth.ts --budget 40000   # default: 20k chars

acs status

Show what's been captured, what failed schema validation, and what needs enrichment.

acs status

acs retry

Find minimal changelogs (written without AI) and enrich them using your configured LLM.

acs retry

acs onboard

Print a full project context bundle — CONSTITUTION.md plus the last 20 changelogs — for onboarding a new developer or AI agent.

acs onboard

acs pr prepare

Aggregate changelogs from the current branch (not on main) for a PR description.

acs pr prepare
acs pr prepare --format markdown
acs pr prepare --no-llm-fallback   # metadata only, safe for fork PRs in CI

acs skip <pattern>

Add a commit prefix pattern to .ai/.skiprc. Commits matching this prefix skip changelog generation silently.

acs skip "chore:"
acs skip "docs:"

What gets generated

Every commit produces a file like .ai/changelogs/changelog-2026-04-03T15-30-00Z-a3f2.md:

# AI Changelog
Commit: abc123def456...
Date: 2026-04-03T15:30:00Z
Author: John Smith <[email protected]>
Branch: feat/auth-refactor
AI-Tool: claude-code
Session-Quality: INFERRED

## What Changed
Refactored JWT middleware in src/auth/jwt.ts to support refresh token rotation.
Added a new `refreshToken()` function and updated the session store interface.

## Why (AI Context)
The previous implementation stored tokens in memory, which caused session loss
on server restart. Switched to Redis-backed storage to support horizontal scaling.

## Architectural Impact
The auth middleware now depends on the Redis client. Any new service that handles
authentication must initialize the Redis connection before mounting the middleware.

## Patterns Used
Follows the middleware factory pattern established in CONSTITUTION.md. Uses the
project's standard error boundary wrapper for async middleware functions.

## Integration Points
`src/api/routes.ts` imports the middleware directly. The session store interface
in `src/core/session.ts` was updated — any code using `SessionStore` needs to
account for the new `refresh()` method.

## Gotchas
Refresh tokens are single-use. If the client calls refresh twice before the first
response arrives (e.g., tab duplication), the second call will receive a 401.
This is intentional — use the `X-Refresh-Nonce` header pattern described in CONSTITUTION.md.

## How to Extend
Start at `src/auth/jwt.ts:refreshToken()`. The token rotation logic is isolated
there. To add device fingerprinting, extend the `TokenPayload` interface first.

How AI tools use it

When Claude Code (or Codex) opens a session in a repo with acs installed:

1. It reads AGENTS.md / CLAUDE.md (installed by acs init)
2. Those files tell it: read .ai/CONSTITUTION.md and recent changelogs first
3. It has real context — what decisions were made, what patterns to follow, what gotchas exist
4. After committing, it generates and stages a changelog automatically

You get consistent AI behavior across sessions without re-explaining the codebase every time.

Slash commands (Claude Code)

After acs init, these work in any Claude Code session:

• /acs-why <file> — explain why a file looks the way it does
• /acs-onboard — get a full project briefing
• /acs-commit — propose a conventional commit message for staged changes

The .ai/ directory

.ai/
  CONSTITUTION.md     # Project patterns, conventions, anti-patterns
                      # Updated via: acs update-constitution (coming in v1.1)
  changelogs/         # One file per commit, append-only
    changelog-*.md    # Named by timestamp — sorts chronologically, no merge conflicts
  .errors             # Failed generations and schema errors (gitignored)
  .skiprc             # Commit prefix patterns to skip (committed)

.aiignore at the repo root works like .gitignore for AI: files matching it are redacted from the diff before it's sent to the LLM. Secrets, lock files, and binaries are excluded by default.

Sharing with your team

The hooks are installed per-machine (acs init per developer). Changelogs and CONSTITUTION.md live in the repo and are shared automatically via git.

Share acs itself with your team:

# Mac/Linux/WSL
curl -fsSL https://raw.githubusercontent.com/USER/ai-context-sync/main/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/USER/ai-context-sync/main/install.ps1 | iex

After each teammate installs, they run acs init once per repo.

Configuration

acs.config.json is created by acs init at the repo root:

{
  "llm_command": "claude -p",
  "version": "1"
}

llm_command is the headless AI tool subprocess. Detected automatically from your PATH. Supports claude -p, codex exec, or any command that reads stdin and writes to stdout.

Set ACS_AI_TOOL in your environment to override the tool name recorded in changelogs.

Requirements

• Node.js >= 18
• Git >= 2.x
• An AI tool in PATH (optional — changelogs are written without one, enrichable later via acs retry)
• Git for Windows or WSL on Windows

License

MIT