README

Compact PHP symbol maps for coding-agent navigation.

agent-map builds a small JSON index of PHP files, symbols, and methods, then answers targeted questions such as "where is this class?", "what changed?", and "what tests look nearby?". It is designed for token hygiene: agents should find the right files before reading large chunks of a repository.

agent-map helps agents find the right files faster. It does not decide what the repository has learned.

Why This Exists

Coding agents often start by running broad searches and reading whole files. That works, but it wastes context. agent-map gives agents a boring first stop:

vendor/bin/agent-map related EvidenceValidator
vendor/bin/agent-map file src/EvidenceValidator.php
vendor/bin/agent-map changed --base=main

Use the output to choose the smallest useful file or range to inspect next. Do not paste the generated index into a prompt.

What It Is Not

Not a memory system.
Not an LLM caller.
Not a daemon.
Not a database.
Not a PHPStan replacement.
Not an agent-loop or agent-learning dependency.

Boundaries

agent-map builds and queries a compact PHP symbol map.

agent-loop may later orchestrate workflows and call agent-map.

agent-learning stores validated findings, proposals, and decisions. It must not own repo maps.

agent-recall-compiler may later use map output to select context.

PHPStan remains the authoritative correctness/type validation gate.

RTK handles shell-output compression separately.

agent-map guides agent navigation. PHPStan judges agent claims.

Requirements

PHP 8.3 or newer
Composer

Installation

In a project:

composer require voku/agent-map --dev

When working from this repository checkout:

composer install

For root-checkout development, Composer creates vendor/bin/agent-map through the package post-install/update script. As a dependency, Composer exposes the package binary normally.

Quick Start

Build an index:

vendor/bin/agent-map build \
  --root=. \
  --paths=src,tests \
  --out=.agent-map/php-symbols.json

Inspect the map:

vendor/bin/agent-map summary
vendor/bin/agent-map query EvidenceValidator
vendor/bin/agent-map related EvidenceValidator
vendor/bin/agent-map file src/EvidenceValidator.php
vendor/bin/agent-map stale

For changed work:

vendor/bin/agent-map changed --base=main

Commands

`build`

Scans PHP files and writes the JSON index.

vendor/bin/agent-map build \
  --root=. \
  --paths=src,tests \
  --out=.agent-map/php-symbols.json \
  --exclude='~Generated.*\.php$~'

Options:

--root: repository root. Defaults to the current working directory.
--paths: comma-separated directories or PHP files relative to root. Defaults to ..
--out: output JSON file. Defaults to .agent-map/php-symbols.json.
--exclude: repeatable PHP regex applied to normalized relative and absolute paths.

Default excludes:

vendor/
.git/
node_modules/
var/cache/

Invalid exclude regexes fail before scanning.

`query <term>`

Finds files by file path, symbol name, fully-qualified name, or method name. Literal hits and case/separator-normalized peers are combined, so a DTO named M365EntraApp does not hide a module named M365_EntraApp. Method-only queries show only the matching method under its containing symbol, rather than spending output on every unrelated method in that class.

vendor/bin/agent-map query EvidenceValidator

`file <path>`

Shows indexed symbols for one file.

vendor/bin/agent-map file src/EvidenceValidator.php

`related <term>`

Finds likely related files without pretending to be a semantic graph.

It currently combines:

exact symbol/file/method matches
likely test files with matching basename
same-namespace files
files that mention the term

vendor/bin/agent-map related EvidenceValidator

`changed`

Shows changed PHP files against a base branch plus staged and unstaged working tree PHP changes.

vendor/bin/agent-map changed --base=main

This command requires the index root to be a Git repository.

If the base comparison fails, changed warns and still reports working-tree changes when possible.

`summary`

Prints a compact repository overview.

vendor/bin/agent-map summary

`stats`

Prints map size, symbol/method counts, and largest indexed files.

vendor/bin/agent-map stats

`stale`

Checks whether indexed files changed or disappeared.

vendor/bin/agent-map stale

Exit codes:

0: index is fresh
1: one or more indexed files are stale or missing

Shared Options

Parsing

build parses every file in-process with voku/simple-php-code-parser (nikic/php-parser under the hood). If a file fails to parse, the command fails clearly rather than silently skipping it.

Beyond class/interface/trait/enum/function names and line numbers, the index records the signature detail an agent needs to judge relevance without opening the file:

extends / implements for classes, interfaces, and enums
uses for the traits a class or trait composes (use LoggerTrait;), resolved to the same fully-qualified names used for extends and implements
method and function parameters (Type $name) and return types
method visibility and static
line_start / line_end for every class-like symbol, method, and function — precise enough to sed -n 'start,endp' file.php out exactly one method instead of reading the rest of the file. (Leading #[...] attribute lines are included in the range.)
PHP 8 attributes on classes, interfaces, traits, enums, methods, and functions, rendered as Name(arg, key: arg, ...) (e.g. #[Route('/widgets', priority: 5)]). Parameter- and property-level attributes are not extracted. Attribute arguments that are enum cases or class constants render as a bare name string (e.g. Foo instead of SomeEnum::Foo) and array-literal arguments render as ... — both are limitations of the underlying AST value resolver, not of agent-map.

Trait-contributed methods are not merged into a class's own method list — if Widget composes LoggerTrait, only Widget's own directly-declared methods appear under Widget; LoggerTrait's methods appear only under the trait's own entry. The underlying parser resolves trait method inlining at runtime/reflection time, not statically, so agent-map doesn't have it either.

Index File

The JSON index stores:

relative paths
file mtimes and SHA1 hashes
namespace
symbols, with line numbers, extends/implements, and method/function signatures

It does not store source code or AST blobs.

Recommended .gitignore entry:

.agent-map/

Commit the generated index only when a project explicitly wants that.

Makefile Template

Projects can include Makefile.agent-map.mk to expose stable agent-facing commands:

include Makefile.agent-map.mk

Then agents can use:

make ai-map-build
make ai-map-stale
make ai-map-summary
make ai-map-query q=EvidenceValidator
make ai-map-file f=src/EvidenceValidator.php
make ai-map-changed base=main
make ai-map-related q=EvidenceValidator
make ai-map-stats

Optional Make variables mirror the CLI read controls:

make ai-map-query q=Service limit=10 symbol_limit=5 method_limit=5
make ai-map-related q=EvidenceValidator format=toon

Project defaults can be overridden with:

AGENT_MAP_PATHS = src,tests,bin
AGENT_MAP_BASE = develop
AGENT_MAP_LIMIT = 10

See docs/agent-usage.md for an AGENTS.md-ready token hygiene snippet.

Development

Install dependencies:

composer install

Run tests and static analysis:

vendor/bin/phpunit
vendor/bin/phpstan analyse --configuration=phpstan.neon.dist
find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l

Dogfood the focused IT-Portal discovery contract when that checkout is available alongside this repository:

IT_PORTAL_ROOT=../IT-Portal vendor/bin/phpunit --filter ItPortalDogfoodTest

Validate Composer metadata:

composer validate --strict

License

MIT

voku / agent-map

Maintainers

Package info

Statistics

Security