GitHub - remorses/agentmap: A tree of your codebase at the start of every agent session, with descriptions. Like SKILL spec but for source code files. A frontmatter for source code file

4 min read Original article ↗

agentmap

A compact, YAML-based inventory of your codebase, intended to be prepended to a coding agent's context at session start.

Purpose

  • Give the agent a fast, structured overview of files and responsibilities
  • Provide jump targets via top-level defs (functions/classes with line numbers)

Example Output

my-project:
  src:
    cli.ts:
      description: CLI entrypoint for generating codebase maps.
    lib:
      parser.ts:
        description: Tree-sitter parser initialization and code parsing.
        defs:
          parseCode: line 32, function, exported
          resetParser: line 45, function, exported
      types.ts:
        description: Core type definitions for the codebase map.
        defs:
          FileResult: line 101, interface, exported
          GenerateOptions: line 111, interface, exported

Note

Descriptions are extracted from header comments or docstrings at the top of each file. Files without a header comment are not included in the map. See File Detection below for examples.

The map contains:

  • File tree structure - nested directories and files
  • Descriptions - extracted from header comments/docstrings in each file
  • Definitions - top-level functions, classes, interfaces, types with line numbers and export status

This gives the agent a workflow for checking codebase structure at session start and keeping file descriptions up to date.

OpenCode Plugin

agentmap includes a plugin for OpenCode that automatically injects the codebase map into the system prompt at session start.

Add the plugin to your opencode.json:

{
  "plugin": ["@agentmap/opencode"]
}

The plugin will scan your project for files with header comments and inject the map into the system prompt wrapped in <agentmap> tags. This gives the AI agent immediate context about your codebase structure without needing to explore files first.

Quick Setup

The agentmap prompt command generates instructions for an AI agent to add header comments to your most important files. This bootstraps your codebase so agentmap can discover and describe files automatically.

Why add descriptions? Without them, agents must read files to understand what they do. With descriptions in the map, agents can navigate your codebase structure instantly and jump directly to relevant code.

opencode run "$(npx -y agentmap prompt)"

This generates a prompt that instructs the agent to:

  1. Analyze your repository structure
  2. Identify the most important files (entry points, core modules, utilities)
  3. Add descriptive comments at the top of each file
  4. Mark entry points as such
  5. Set up the @agentmap/opencode plugin in opencode.json

These comments make your files discoverable in the agentmap. The plugin automatically injects the map into future sessions.

CLI Usage

# Map current directory
npx agentmap

# Map specific directory
npx agentmap ./src

# Write to file
npx agentmap -o map.yaml

# Filter to specific directories or files
npx agentmap --filter "src/**" --filter "lib/**"

# Ignore patterns
npx agentmap --ignore "dist/**" --ignore "**/test/**"

Options

-o, --output <file>      Write output to file (default: stdout)
-f, --filter <pattern>   Filter pattern - only include matching files (can be repeated)
-i, --ignore <pattern>   Ignore pattern (can be repeated)
-h, --help               Show help
-v, --version            Show version

Commands

# Generate a prompt to help AI agents add file descriptions
npx agentmap prompt

File Detection

Files with a header comment or docstring are automatically included. agentmap detects standard comment styles used in existing projects - no special markers needed. Place the header comment above any import statements in the file.

TypeScript / JavaScript:

// CLI entrypoint.
// Parses args, wires deps, calls into lib/.
import { parseArgs } from "./args"

export function main() { ... }
/**
 * Core data structures.
 * Used throughout the application.
 */
import type { Config } from "./config"

export class App { ... }

Python:

"""
Parsing and normalization utilities.
Handles input validation and transformation.
"""

from .schema import InputSchema

def parse_input(): ...
# Configuration loader.
# Reads from environment and config files.

import os

def load_config(): ...

Rust:

//! HTTP client module.
//! Provides async request handling.

use crate::http::client

pub fn fetch() { ... }

Go:

// Package utils provides helper functions.
// Includes string manipulation and validation.

import "strings"

func Helper() { ... }

Descriptions are limited to the first 20 lines of the header comment.

Supported Languages

Language Extensions
TypeScript .ts .tsx .mts .cts
JavaScript .js .jsx .mjs .cjs
Python .py .pyi
Rust .rs
Go .go
Zig .zig
C/C++ .c .h .cpp .hpp .cc .cxx

Library Usage

import { generateMap, generateMapYaml } from 'agentmap'

// Get as object
const map = await generateMap({ dir: './src' })

// Get as YAML string
const yaml = await generateMapYaml({ dir: './src' })

// With filter patterns (only include matching files)
const yaml = await generateMapYaml({
  dir: './src',
  filter: ['src/**', 'lib/**']
})

// With ignore patterns
const yaml = await generateMapYaml({
  dir: './src',
  ignore: ['**/test/**', '**/*.spec.ts']
})

License

MIT