Agent Context Tracker

Scaffold a tool-agnostic .ACT/ agent-context directory into any project, using a lightweight context-routing model so AI agents (Claude Code, Codex, Gemini, Cursor, Copilot…) load only the reference they need for a task. Ships with a zero-dependency drift detector that scores how in-sync the docs are with the code.

Zero runtime dependencies — Node.js stdlib only. No build step.

Install

Install it globally from the repo. The repo is private, so this uses your existing GitHub git credentials (the same ones you push with) — nothing is published to a public registry.

npm i -g github:WMDragstrem/agent-context-tracker

That puts an act command on your PATH. Verify it:

act --dry-run

If the command isn't found, make sure npm's global bin dir is on your PATH — npm config get prefix (on Windows that folder, e.g. %AppData%\npm, must be in PATH; reopen the terminal after a fresh Node install).

Update (after new commits are pushed): re-run the same install command (append #main or a tag to force a specific ref):

npm i -g github:WMDragstrem/agent-context-tracker#main

Uninstall: npm uninstall -g agent-context-tracker.

Global install is recommended on Windows: it builds a proper Node shim on your PATH, avoiding the npx github: "select an app to open this .js file" prompt some setups hit.

Usage

Run it from the root of the project you want to set up — it scaffolds the current working directory:

# Interactive: prompts for which agent tools + context categories you use
act

That's it. It creates the .ACT/ directory, the root bootstrap files for the agents you pick, and adds .ACT/temp/ to .gitignore. Commit the result.

Always run from the target repo root — output goes to the current directory.

What it generates

.ACT/
  instructions.md            # universal rules & conventions for all agents
  routing.md                 # task-type → which context file(s) to load
  context/
    overview.md              # small always-load: stack, dir map, entry points
    <category>.md            # one per category you select (frontend, backend, …)
  drift.js                   # the drift detector (run: node .ACT/drift.js)
  drift.manifest.json        # paths/symbols/versions the detector validates
  temp/                      # gitignored scratch space (plans, specs, scratch SQL)

CLAUDE.md                    # ┐ thin pointers → .ACT/  (only the agents you pick)
AGENTS.md                    # │ each tool auto-discovers its own file
GEMINI.md                    # │
.cursor/rules/act.mdc        # │
.github/copilot-instructions.md  # ┘
.gitignore                   # ".ACT/temp/" appended if missing

The thin CLAUDE.md/AGENTS.md/etc. exist because each tool natively auto-loads its own root file — they all just redirect to the shared .ACT/. Existing files are never clobbered: if you already have a CLAUDE.md, a small marked pointer block is appended (and skipped on re-runs), not overwritten.

The two choices it asks for

1. Agent tools — which AI assistants this project targets. Each maps to the file that tool reads:

| Key | Generates | Tool | |-----|-----------|------| | claude | CLAUDE.md | Claude Code | | codex | AGENTS.md | Codex + the generic AGENTS.md convention | | gemini | GEMINI.md | Gemini CLI | | cursor | .cursor/rules/act.mdc | Cursor | | copilot | .github/copilot-instructions.md | GitHub Copilot |

Default (when non-interactive): claude,codex.

2. Context categories — broad areas of the codebase. Each creates a context/<category>.md stub and a row in routing.md. Starter set: frontend · backend · auth · database · infra · testing · data. Keep them broad — over-specific files defeat the point (token efficiency). Default: none (you can add them later).

On the first session, the agent fills in overview.md and each category stub (they carry a SETUP REQUIRED marker until then), then runs the drift detector.

Flags

| Flag | Behavior | |------|----------| | --project-name="My App" | Name injected into generated files (default: directory basename) | | --agents=claude,codex,gemini | Pick agent tools non-interactively | | --categories=frontend,backend | Create these category stubs non-interactively | | --yes / --defaults | Skip all prompts; use flags + defaults (for CI / scripts) | | --migrate | Migrate an existing .claude/ agent-context dir to .ACT/ (see below) | | --force | Overwrite existing files instead of skip/append | | --dry-run | Print planned actions, write nothing |

Interactivity: prompts only when run in a real terminal (TTY) without --yes. In CI / piped / non-TTY runs it falls back to flags + defaults, so it never hangs.

Examples

# Fully scripted fresh scaffold
act --project-name="MyApp" --agents=claude,codex,gemini --categories=frontend,backend --yes

# See what would happen, write nothing
act --dry-run

Migrating an existing .claude/ setup

If a project already keeps agent context in .claude/, --migrate moves it to .ACT/ non-destructively:

act --migrate --project-name="MyApp" --agents=claude,codex,gemini,cursor,copilot --yes

• Copies .claude/instructions.md → .ACT/instructions.md and any *project_reference*.txt → .ACT/context/overview.md, rewriting .claude/ path references to .ACT/.
• Moves .claude/temp/ → .ACT/temp/; seeds routing.md + drift.js + manifest.
• Rewrites root CLAUDE.md/AGENTS.md/.gitignore; generates any additional selected agent files.
• Leaves .claude/settings.json + .claude/settings.local.json in place (Claude Code owns those).
• Prints manual follow-ups (split the reference into category files, update memory, etc.).

Drift detector

node .ACT/drift.js

Validates the manifest's declared paths, symbols (string-search), and package major versions, plus auto-extracted paths found in your context/*.md prose. Prints a 0–100 score and exits 0 clean / 1 on real drift — safe as a CI step or pre-commit hook.

• Hard checks (manifest paths/symbols/versions) drive the score and exit code.
• AUTO findings (paths auto-extracted from prose) are advisories — reported but never fail the run, since prose often uses shorthand paths.
• Docs still carrying a SETUP REQUIRED / FIRST-SESSION SETUP marker are skipped (un-filled scaffolding).

Local development

git clone https://github.com/WMDragstrem/agent-context-tracker
cd agent-context-tracker
node act.js --dry-run   # preview a scaffold of the current directory

Requires Node.js >= 18.