What is portmap AGENTS.md?

A set of project instructions for working on portmap, a tool that maps local development services, ports, and localhost URL references.

Use it when changing portmap code, building it, running its tests, or understanding its CLI and read-only MCP server.

It gives coding agents the project's layout, build and test commands, and required conventions in one place.

portmap AGENTS.md — Instructions file by paladini

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/paladini/portmap/agents-md

Clone the repo

git clone --depth 1 https://github.com/paladini/portmap

Made for: Codex, OpenCode.

Per session 698 This file is loaded in full into every session.

When invoked 698 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00698	$0.00698
Opus 5	$0.00349	$0.00349
Sonnet 5	$0.00140	$0.00140
Haiku 4.5	$0.00070	$0.00070

Measured yesterday against content hash 61cc024e9570, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

portmap AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 65 lines

How it starts

The opening of the file, as written. The whole thing — 65 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Agent Guide — portmap

What this is

A deterministic CLI + MCP server that maps local dev topology for AI agents: declared ports (configs), runtime listeners (OS), and env URL references.

It does not start/stop processes, kill ports, or call an LLM. It reads the filesystem and OS socket table, then emits .portmap.json and actionable findings (PRT-01 … PRT-07).

Repo: https://github.com/paladini/portmap

Layout

src/cli.ts — CLI entry (portmap bin → dist/cli.js)
src/discover/static.ts — declared ports from configs
src/discover/runtime.ts — OS listeners (Windows + Unix)
src/discover/reconcile.ts — merge static + runtime + findings
src/discover/workspace.ts — multi-repo workspace scan
src/parsers/ — env, vite, package.json, docker-compose
src/mcp/server.ts — read-only MCP (4 tools)
src/format/output.ts — text, JSON, Markdown formatters
fixtures/ — mismatch, full-stack, frontend-only, workspace
docs/FINDINGS.md — full rule catalog
docs/SCHEMA.md — .portmap.json spec
docs/EXAMPLES.md — before/after fixes from fixtures

Build & test

npm ci
npm run build
npm test
npm run demo:mismatch   # expect PRT-01, PRT-04 findings
npm run demo:full-stack # multiple declared services
npm run demo:workspace  # cross-project env resolution

All tests must pass before commit.

Non-negotiable conventions

Deterministic only — no LLM, no network calls in the scan path.
Finding IDs are public API — never renumber (PRT-01, …).
Prefer false negatives over noisy false positives.
Read-only v1 — no start/stop/kill (Switchboard/PortPilot own lifecycle).
When adding a rule: update docs/FINDINGS.md, README, skills, and tests.

When agents need port context

Run portmap scan . (or portmap declare . if nothing is running).
Read references[] for correct localhost URLs — never guess :3000.
Fix findings: PRT-04 (broken env URL) before debugging API connectivity.
Use MCP tools portmap_graph / portmap_resolve_url when configured.
Never re-implement topology discovery with an LLM — trust CLI output.

Read the full file on GitHub · 65 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 65 lines · 698 tokens per session scan A 61cc024e9570

Subscribe to this mod's changes

portmap AGENTS.md is an instructions file published in the GitHub repository paladini/portmap (0 stars, last pushed 8d ago), licensed MIT. It adds 698 tokens to every session, about $0.0035 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Testing ai-agents cli developer-tools localhost mcp static-analysis

static-analysis AGENTS.md

Instructions for analysis-tools-dev/static-analysis, covering guidelines for ai agents and assistants and 🤖 instructions for the ai.

analysis-tools-dev/static-analysis · 332 tokens

CodeBoarding AGENTS.md

AGENTS.md instructions for CodeBoarding/CodeBoarding, covering system-wide recommendations for agent execution, 1. environment and virtual environment setup, 2. dependency and repository navigation, 3. code quality and testing standards and 4. execution flow and tool patterns.

CodeBoarding/CodeBoarding · 1,683 tokens

portmap AGENTS.md