1. Install locally or globally

#npm|pnpm|yarn
# global install
npm install -g showsignature
# local install
npm install showsignature

2. Set the Agent

/plugin marketplace add FredySandoval/showsignature

/plugin install showsignature@showsignature

(You have to send two separate prompts for the install to work)

The desktop app has no /plugin command. Install it from the UI instead: Customize, the + by personal plugins, Create plugin and add marketplace, Add from repository, then enter the repo URL.

The agent invokes showsignature as a bash command.

1. Install locally or globally

#npm|pnpm|yarn
# global install
npm install -g showsignature
# local install
npm install showsignature

2. Set the Agent

codex plugin marketplace add FredySandoval/showsignature
codex

Open /plugins, select the showsignature marketplace, and install showsignature. Then open /hooks, review and trust its lifecycle hook, and start a new thread.

This same install also covers the Codex desktop app: restart the app after installing and it picks up the plugin.

The agent invokes showsignature as a bash command.

# option 1
pi install npm:showsignature
# option 2
pi install git:github.com/FredySandoval/showsignature
# option 3
pi install https://github.com/FredySandoval/showsignature

The extension registers showsignature as a native tool call.

Option 1: CLI

opencode plugin showsignature@0.2.2 --global

Option 2: config file

Add the plugin to your opencode.json (project or ~/.config/opencode/opencode.json for global):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["showsignature@0.2.2"]
}

OpenCode installs the package automatically at startup and registers the map and outline_read tools — the agent calls them as native tools, no shell involved.

[!NOTE] Pin an exact version as shown above and update it manually on new releases. OpenCode caches the plugin by its version specifier, so an unpinned (or @latest) install is resolved once and never refreshed — publishing a new version to npm won't reach you until the pinned version changes (or you clear ~/.cache/opencode/packages/).

[!NOTE] You may need to have installed node or bun.

For any MCP-capable host, showsignature ships an MCP server over stdio that exposes map and read as the tools map and outline_read. The host injects them into the model's tool list — the model calls them directly instead of shelling out.

1. Install

# global install — lets the host launch `showsignature mcp` directly
npm install -g showsignature

2. Register the server

# For Claude Code
claude mcp add showsignature -- showsignature mcp

# For Codex
codex mcp add showsignature -- showsignature mcp

Other Agents (Manual installation)

Manual — add to the MCP servers config:

{
  "mcpServers": {
    "showsignature": {
      "command": "showsignature",
      "args": [ "mcp" ],
      "type": "stdio"
    }
  }
}

Working directory

MCP has no per-call working directory, so the server resolves paths against a root chosen in this order:

1. the MCP_SHOWSIGNATURE_ROOT environment variable, if set;
2. the host's first workspace root (roots/list), if the host advertises it;
3. the server process's current directory.

Pass absolute paths when in doubt. If the resolved root is / (some hosts launch stdio servers there) and a call uses relative or default paths, the tool returns an error instead of scanning the filesystem root — set MCP_SHOWSIGNATURE_ROOT or use absolute paths. Run showsignature mcp --help for the same reference.

[!NOTE] You may need to have node or bun installed. Pi and OpenCode keep their native adapters above — the MCP server is additive, for MCP-only hosts.

1. Install locally or globally

#npm|pnpm|yarn
# global install
npm install -g showsignature
# local install
npm install showsignature

2. install the agent skill

# All agents
npx skills add https://github.com/FredySandoval/showsignature --skill showsignature

git clone https://github.com/FredySandoval/showsignature.git
cd showsignature
pnpm install
pnpm build
pnpm link --global

Description

In an unfamiliar repository, the first search is usually a blind one: names are guessed from generic conventions ("it's probably called DATABASE_URL") rather than taken from the code itself. The repository may use its own naming conventions, a different stack, or names its documentation no longer reflects.

--symbol-summary closes this gap. It reuses map's existing extraction, but instead of formatted structural output it emits the vocabulary that literally exists in the code — a compendium of real identifiers to start searching from. Scan the output, spot the suspicious name, then rg or showsignature map that — no more guessing.

The flag is deliberately verbose: a primary consumer is LLM agents, and --symbol-summary is self-describing at the call site.

The flag exists on map only. It is not available on read; use read --offset --outline to orient around a location.

Output format

One line per (extractor, file) pair, tokens separated by single spaces; paths containing spaces are double-quoted:

<extractor>:<relative/path/to/file> token1 token2 token3

Example:

$ showsignature map --symbol-summary ./src
exports:src/db/pool.ts PgPool createPool POOL_MAX acquireConn
imports:src/db/migrate.ts runMigrations MigrationLock schemaVersion LogErrMig
exports:src/db/migrate.ts runMigrations MigrationLock
json:shape:src/config/default.json db host port poolMax migrationTable

• The extractor prefix says why a token is listed: an export is API surface, an import is dependency vocabulary, a variable is config vocabulary.
• A file may produce multiple lines — one per extractor that yielded tokens for it. They are never merged.
• Ordering is stable: file order first (same traversal order as normal map), extractor order second — output is diffable and deterministic across runs on an unchanged tree.
• Lines whose every token was stopworded are omitted.
• No line numbers appear, ever, regardless of --no-line-number. Regular map is the discovery tool for locations.

The output contract

Every token is a valid ripgrep pattern in default (regex) mode.

Every token exists verbatim in the corresponding source file (modulo escaping). Regex metacharacters occurring in identifiers are escaped rather than dropped — e.g. Svelte/PHP-style $name is emitted as \$name. Any token is safe to paste, and joining tokens with | yields a valid alternation:

rg "PgPool|createPool|POOL_MAX|acquireConn" src/db/pool.ts

Token rules

• Verbatim identifiers. No splitting of compound identifiers: getUserById stays whole, DATABASE_URL stays whole. Splitting would break the output contract and produce noisy greps.

• Import specifiers are emitted whole. The quoted module specifier in an imports/exports entry contributes exactly one token, never path fragments. A relative specifier is reduced to its basename — the leading .//../ segments vary per importing file and would break cross-file correlation — while package and module names are kept verbatim (metacharacters escaped):

  import type { Range } from "../../00-core-types.js";   →  Range 00-core-types\.js
  import * as ts from "typescript";                      →  ts typescript
  import "github.com/pkg/errors"                         →  github\.com/pkg/errors
  

  The same specifier token under imports: of several files tells you exactly who depends on that module.

• First-occurrence order per line, mirroring source order, so related terms cluster naturally. Exception: json:shape tokens follow the shape rendering, which sorts object keys lexicographically — order there mirrors the (sorted) rendering, not the source file.

• Dedup within a line only. A token appears at most once per line but may appear on multiple lines — seeing runMigrations under both exports:src/db/migrate.ts and imports:src/cli.ts tells you who defines it and who uses it. Repetition across lines is information; repetition within a line is noise.

• Stopwords are purely syntactic. Language keywords (function, def, fn, pub, local, …), primitive/builtin type names (string, int, bool, void, common JS/TS globals and utility types like Promise, Set, Record, …), and structural noise (self, this) are removed. The tables are per-language: each language drops its own keywords and builtins. Nothing is filtered for perceived relevance — if it's a name someone chose, it is kept.

Extractor scope

Only extractors whose output is symbols — names that verifiably exist in code or config — contribute:

Code and JSON config are ground truth; comments and Markdown are prose that can reference names which no longer exist. JSON is deliberately included: config keys are exactly the kind of token users grep for.

Explicitly requesting an excluded extractor is an error, not a silent drop:

$ showsignature map --symbol-summary --only comments ./src
[error] --symbol-summary only applies to symbol extractors (names that
exist in code or config); comments is a prose extractor and cannot
contribute. Remove it from --only.

When --only is not given, the default extractor set applies with the excluded extractors simply not contributing (Markdown files therefore produce no output in this mode).

Interaction with other options

Output is capped at 2000 lines / 50 KB as in normal map. When paging or a cap truncates output, the trailing note: names the exact resume command — the skip count is handed over, never guessed:

note: showing summary lines 1-2 of 6 — rerun with --symbol-summary --skip 2 --take 2 src

Examples

# Full vocabulary of a source tree
showsignature map --symbol-summary ./src

# Domain vocabulary only (data shapes)
showsignature map --symbol-summary --only interfaces,types ./src

# Dependency vocabulary only
showsignature map --symbol-summary --only imports ./src

# Page through a large tree, two lines at a time
showsignature map --symbol-summary --take 2 ./src

# Follow up on a discovered name
rg "LogErrMig" src/
showsignature map src/db/migrate.ts

Caveats

• Relative import specifiers are reduced to their basename. A line like import { x } from "../../00-core-types.js" contributes 00-core-types\.js, not the full relative path — the ../ prefix differs per importing file, so the basename is what correlates across files. The basename still exists verbatim in the source (the contract holds), but grepping it may also match other references to the same filename, e.g. in build config.
• JSON keys are kept whole (pool.max → pool\.max), except keys containing whitespace, which split on the space — the shape rendering itself is space-delimited and cannot represent them unambiguously.
• json:shape truncation drops keys. Objects with more than 20 keys (or nesting past depth 5) are elided by the shape rendering; the elided keys do not appear in the vocabulary, the ... marker itself is never emitted as a token (a literal "..." key is likewise dropped), and the trailing note: discloses the truncation. The cap is fixed — --all does not lift it.
• Single-character tokens can appear (e.g. a lone s from a template literal in a signature). They are verbatim and harmless, but rarely useful grep targets on their own.
• Stopword tables are per-language and finite. An unlisted builtin (e.g. a niche global type) may slip through as a token. This errs on the side of the feature's principle: keep chosen names, drop syntax.
• Tokens are not scoped. A parameter name and a top-level export look the same in the payload; the extractor prefix is the only context given.
• Prose is invisible. Comments and Markdown never contribute, by design — a name that exists only in documentation will not appear here. Use map --only comments or map --only md:headings for those.
• Redaction applies. Secret-looking values are redacted as elsewhere in map (disclosed in the note:); pass --no-redact for literal bytes.

Out of scope (v1)

• read --symbol-summary
• Identifier splitting (a possible future --split-identifiers opt-in)
• Comments / Markdown extractors (would need natural-language stopwords)
• Any semantic relevance filtering