@abhinav26104/agent-index

A deterministic, security-conscious repository index for any AI coding agent. It uses local repository metadata, without an LLM, API key, or external service.

One-file workflow

Run these commands from the repository you want to index:

npx @abhinav26104/agent-index init .
npx @abhinav26104/agent-index sync .
npx @abhinav26104/agent-index check .

init creates .indexAgent/index.md. sync refreshes its managed section, while preserving user content outside the managed markers. check exits 0 when the index is current and 1 when it is stale. Use --dry-run to preview changes or --json for machine-readable output.

Tell your coding agent to read .indexAgent/index.md before working. The index describes the project, technologies, frameworks, package managers, commands, entry points, important directories, structure, tests, and configuration files. Source code, tests, and configuration remain the final source of truth.

Generated file

.indexAgent/
  index.md

The generated section is enclosed by <!-- agent-index:start --> and <!-- agent-index:end -->. User content before, after, or around that section is preserved.

Upgrading from 0.1.x does not remove or modify .agent-index, AGENTS.md, CLAUDE.md, GEMINI.md, context files, or legacy configuration. Remove those legacy files manually if they are no longer needed.

Safety and determinism

The scanner respects .gitignore, uses a safe manifest and README allowlist, and does not read arbitrary source-code contents. It excludes secrets, credentials, environment files, private keys, certificates, dependencies, builds, and generated files; does not follow symbolic links; rejects symlinked output paths; enforces depth and file-count limits; and normalizes paths across operating systems.

Output is sorted, timestamp-free, atomic, and idempotent. No production dependency is added for indexing.

Local development

npm install
npm run typecheck
npm test
npm run build

Licensed under the MIT License.