Skip to content

README.md

Latest commit

 

History

History
304 lines (216 loc) · 12.6 KB

README.md

File metadata and controls

304 lines (216 loc) · 12.6 KB
Raw

AgentContextMap

CI Action smoke Release License Rust 1.74+

Map which repository instructions can affect your coding agents.

AgentContextMap is a local, read-only tool for mapping repository instruction files across Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, and Cline. Give it a repository — and optionally a target file — to see the relevant instruction sources, activation state, obvious conflicts, approximate context size, and a self-contained HTML report.

AgentContextMap report showing instruction sources, activation states, filters and findings

Status: v0.2.3 is the current stable release line published through the GitHub Marketplace Action release flow. It includes SARIF 2.1.0 CLI and GitHub Action output, explicit GitHub Code Scanning integration, release checksum verification, GitHub Actions job summaries, and correct release resolution for immutable SHA-pinned Action references. Use versioned release tags for production workflows. Agent behavior changes quickly, so support is deliberately conservative and tied to documented vendor behavior. See docs/SEMANTICS.md for the verification matrix and known limits.

Use it

GitHub Actions Local CLI
Inspect repository instruction sources during CI, optionally fail on high-confidence active conflicts, write a GitHub job summary, and emit SARIF for Code Scanning. Inspect locally, emit terminal/JSON output, write SARIF 2.1.0, or generate a self-contained interactive HTML report.
Linux x86_64 runner Linux x86_64 standalone binary; source builds may work elsewhere

GitHub Actions

Use the versioned release tag for normal workflows. Pin a full commit SHA when your security policy requires immutable third-party Action references.

name: Agent instruction check

on:
  pull_request:

permissions:
  contents: read

jobs:
  agent-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Inspect coding-agent instructions
        uses: BLCCoreStudio/AgentContextMap@v0.2.3
        with:
          path: .
          format: terminal

Start report-only. When you want a CI gate for high-confidence active conflicts:

      - name: Enforce active instruction conflicts
        uses: BLCCoreStudio/AgentContextMap@v0.2.3
        with:
          path: .
          target: src/api/auth.rs
          fail-on-conflict: "true"

The composite Action downloads the matching versioned Linux binary and verifies it against the SHA-256 file published with the same release. For immutable SHA/branch references, the wrapper resolves the matching release version from the pinned Action source itself instead of falling back to an unrelated older binary. The requested repository path must remain inside GITHUB_WORKSPACE.

By default the Action also appends its result and report to the GitHub Actions job summary, so the scan is visible without opening raw logs. Set job-summary: "false" if a workflow deliberately does not want that summary. This does not require any additional repository write permission.

SARIF and GitHub Code Scanning

AgentContextMap can write SARIF 2.1.0 for GitHub Code Scanning and other SARIF-compatible tooling.

Stable rule IDs are ACM001–ACM004. High, medium, and low findings map to SARIF error, warning, and note.

The Action accepts a workspace-relative sarif path and exposes the generated absolute path as the sarif output:

name: Agent instruction code scanning

on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  agent-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Generate AgentContextMap SARIF
        id: agentcontext
        uses: BLCCoreStudio/AgentContextMap@v0.2.3
        with:
          path: .
          sarif: agentcontext.sarif

      - name: Upload AgentContextMap SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ${{ steps.agentcontext.outputs.sarif }}

The upload remains a separate step intentionally: AgentContextMap itself keeps its default workflow permission needs at contents: read, while repositories that opt into GitHub Code Scanning explicitly grant security-events: write.

Linux x86_64 — download one file and run

No Rust toolchain and no archive extraction are required.

Download agentcontext-linux-x86_64 from v0.2.3

Then:

chmod +x agentcontext-linux-x86_64
./agentcontext-linux-x86_64 --help
./agentcontext-linux-x86_64 .

Inspect one target path and generate the interactive report:

./agentcontext-linux-x86_64 . \
  --target src/api/auth.rs \
  --html report.html

Or download it from the Releases page. Each standalone binary has a matching .sha256 file. A tar.gz package is also published for users who prefer an archive.

Build from source

Requires Rust 1.74+.

cargo install --git https://github.com/BLCCoreStudio/AgentContextMap --bin agentcontext

What it helps you inspect

A modern repository can contain several instruction systems at once:

  • AGENTS.md and Codex AGENTS.override.md
  • CLAUDE.md
  • GEMINI.md
  • .github/copilot-instructions.md
  • .github/instructions/**/*.instructions.md
  • .cursor/rules/**/*.mdc
  • .windsurf/rules/**/*.md
  • .clinerules/**/*.md / *.txt

Once these become nested, path-specific, model-decided, or manual, a simple question becomes surprisingly hard:

Which instructions can affect this file, and which ones are definitely active versus merely conditional?

AgentContextMap answers that without calling an LLM, executing repository instructions, or sending repository content to a remote service.

Generate a local HTML report:

agentcontext . --target src/api/auth.rs --html report.html

The HTML is an interactive viewer for the analysis already performed by the CLI. You can filter by agent and activation state, search sources, expand the exact instruction text, and highlight sources involved in findings. It does not silently rescan your filesystem from the browser; rerun the CLI after repository files change.

Machine-readable JSON output:

agentcontext . --json

Write SARIF 2.1.0 without changing the normal terminal output:

agentcontext . --target src/api/auth.rs --sarif agentcontext.sarif

Fail CI only on high-confidence conflicts that are definitely active for the requested target:

agentcontext . --target src/api/auth.rs --json --fail-on-conflict

What v0.2.3 models

Capability Support
Nested AGENTS.md across documented agent ecosystems Yes
Codex AGENTS.override.md Yes
Hierarchical CLAUDE.md and repository-contained @ imports Yes
Hierarchical GEMINI.md and repository-contained @ imports Yes
Copilot repo-wide + recursive path-specific instructions Yes
Cursor .mdc rules with always/glob/model/manual activation Yes
Windsurf .windsurf/rules/*.md activation modes Yes
Cline .clinerules/ plus paths conditions Yes
Correct * vs **, brace and basic character-class glob matching Yes
Agent-aware conflict detection Yes
Active vs path-specific vs conditional vs manual status Yes
Missing repository import findings Yes
Unrelated binary/non-UTF8 repository files ignored during discovery Yes
JSON output Yes
SARIF 2.1.0 output with stable ACM001–ACM004 rule IDs Yes
GitHub Action SARIF file output Yes
GitHub Actions job summary Yes
Immutable SHA-ref release resolution Yes
Interactive self-contained HTML viewer Yes
Executes instructions, tools, prompts, scripts, or MCP servers No
Reads imports outside the scanned repository No
Sends repository content to a remote service No

Example

AgentContextMap
===============
Root: /work/acme
Target: src/api/auth.rs
Sources: 5 | Approx. tokens: 812 | Findings: 1

Instruction sources
-------------------
1. AGENTS.md
   Agents: Codex, GitHub Copilot, Cursor, Windsurf, Cline
   Status: active | Scope: workspace tree
2. src/api/AGENTS.md
   Agents: Codex, GitHub Copilot, Cursor, Windsurf, Cline
   Status: active | Scope: src/api subtree

Findings
--------
CONFLICT [high] AGENTS.md <-> src/api/AGENTS.md
  Overlapping sources contain directives with opposite polarity.

Correctness model

AgentContextMap does not pretend every coding agent has identical semantics.

The scanner keeps source ownership and activation explicit. A manual Windsurf rule is not labeled active. A Cursor model-decided rule is not treated as certain. A conflict between Claude-only and Gemini-only files is not reported as if one agent saw both. Path-specific rules are evaluated against the supplied target.

For the exact vendor documentation used to implement these decisions, read docs/SEMANTICS.md.

Designed for inspection, not execution

AgentContextMap reads instruction text but never follows it. It does not run commands found in repository instructions, start agent skills, contact MCP servers, or call an AI API.

Claude/Gemini relative imports are followed only when they remain inside the scanned repository. Absolute, home-directory, or escaping imports are intentionally not read.

CLI

v0.2.3 supports:

agentcontext [ROOT] [OPTIONS]

--target <PATH>        Show sources that can affect a target path
--json                 Emit machine-readable JSON output
--html <PATH>          Write a self-contained interactive report viewer
--sarif <PATH>         Write SARIF 2.1.0
--fail-on-conflict     Exit with code 2 on a high-severity active conflict
-h, --help             Print help
-V, --version          Print version

Exit codes:

  • 0: analysis completed and no configured failure condition was hit
  • 1: invalid arguments or I/O failure
  • 2: a high-severity conflict was found with --fail-on-conflict

Known limits

This is not runtime instrumentation. User/global/org instruction sources outside the repository are not scanned, model-decided rules cannot be proven active from files alone, and deterministic natural-language conflict detection cannot understand every possible contradiction.

Those limits are documented rather than hidden. See docs/SEMANTICS.md.

GitHub App direction

The Marketplace Action is the preferred GitHub-native integration today because the scan runs inside the repository's GitHub Actions runner and preserves the current local-first privacy model. A future install-once GitHub App would require a hosted webhook/backend and therefore changes that privacy boundary.

The minimum-permission App design, webhook scope, Checks API model, and implementation decision gate are documented in docs/GITHUB_APP.md. The project will not silently move repository scanning to a hosted backend merely to add an App badge.

Roadmap

Near-term work is focused on correctness rather than adding every format possible:

  1. vendor-specific precedence visualizations;
  2. broader real-repository compatibility fixtures;
  3. richer conflict classes with measured false-positive rates;
  4. per-agent context-budget breakdown;
  5. SARIF baseline/suppression ergonomics and richer rule help;
  6. release attestations, easier package-manager installs, and broader runner support.

Contributing and support

Bug reports and small, well-scoped pull requests are welcome. For scope/precedence bugs, include the agent product, version if known, a minimal repository layout, and a documentation link or reproducible observation.

See CONTRIBUTING.md, SUPPORT.md, and SECURITY.md.

License

MIT