python-explore
Skill0 starsChanged yesterdayMITView on GitHub
Use when understanding, navigating, debugging, refactoring, or extending Python code with the pyeye MCP server. Triggers on "how does X work", "what does", "why is X doing", "what calls/imports/subclasses this", "add feature", "implement", "refactor", "trace", "debug", "extend". Does NOT trigger for explicit "show me"/"read this file"/"print"/"display" requests, "what's the syntax for" language questions, single-line typo/string fixes with an exact location given, adding a new test case only, or when pyeye output for the symbol is already in context. Requires the pyeye MCP server.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pyeye-scenariosSkill
- pyeye-verifySkill
- architecture-reviewSkill
- decision-logSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Never re-explore what pyeye already surfaced in this conversation.
- Distinctive: line 85
When nothing was cut, none of the three is present.
- Very specific: line 100
Not found: check found on every resolve/resolve_at/inspect/outline/expand result.
- Very specific: line 113
Only a handle key is ever a handle.
- Distinctive: line 121
Unparseable source: if a file can't be parsed by the Python pyeye runs on (e.g.
- Very specific: line 151
importsandimported_byare not exact inverses: If imports(M) shows module B, then M is in imported_by(B). - Very specific: line 205
When you ask for one, pyeye refuses (reports it as unsupported) rather than returning a wrong or empty answer.
- Very specific: line 212
Do not fall back to grep to guess who calls or references a symbol.
- Distinctive: line 253
If your harness has no language-server tool, say so plainly: "pyeye can't give reliable caller/reference data (deferred to #333), and …
- Very specific: line 278
When you read edge_counts, a missing key means "not measured," not "zero." A present superclasses: 0 means measured-and-none (the class has …
- Very specific: line 333
When pyeye detects Pydantic, Django or Flask (in the project or a configured package), it also registers that framework's tools …
- Very specific: line 445
Check the root's truncation_reasons first: it lists every reason any node was cut for (absent when nothing was).
- Very specific: line 570
When it helps the user — a non-trivial change, an ambiguous request, a risky edit — state what you found before proceeding.
- Distinctive: line 587
If pyeye is unavailable (server down, tools not responding):
- Distinctive: line 593
Don't block — degrade gracefully, but make the limitation visible.
- Distinctive: line 604
Faking "who calls this" with grep: instead of delegating to your LSP (or, with no LSP, stating the limit honestly).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Python Explore
Build a structural model of Python code with pyeye before reading or changing it — orient cheap, drill on demand.
The Model: Progressive Disclosure
pyeye answers questions in three widening steps. Start at the cheapest that answers your question; only go wider when you need to.
- Orient (cheap):
resolvea name to a canonical handle, theninspectit for structure, oroutlinea module/class for its skeleton. - Drill (on demand):
expandone edge from a handle to see its immediate neighbours (members, callees, importers, subclasses…). - Trace (across hops):
tracefollows edges multiple hops to see structure across a call chain, import closure, or member tree.
Canonical handles are the currency. A handle is Python's own dotted notation —
a.b.c.Name — anchored at the definition site, stable across edits, and the same
no matter which import alias you arrived through. Everything downstream takes a handle.
pyeye returns pointers and structured facts, never source — when you need the actual
code, Read the file:line it points you at.
Skill Type: Mixed Rigid/Flexible
Rigid gates (non-negotiable):
- Your first move on unfamiliar Python is pyeye, not a blind
Read(). - Never re-explore what pyeye already surfaced in this conversation.
Flexible (use judgement):
- How deep to go (a single
inspect, or a multi-hoptrace). - Which primitives and edges to call.
- Whether to write out a mental-model summary — do it when it helps the user, not as ceremony (see Stating Your Mental Model).
Do NOT Trigger When
- User says "show me", "print", "display", "read this file" — respect explicit requests,
use
Read(). - User says "run", "execute" — that is not exploration.
- User asks "what's the syntax for" — a language question, not a codebase question.
- Single-line typo/string fix where the user gives the exact location.
- Adding a new test case only (not modifying the code under test).
- pyeye output for this symbol is already visible in conversation context — skip straight to using it.
The Primitives
| Primitive | Use it to | Returns |
resolve(identifier) | Turn a name, dotted path, or file:line into a canonical handle | {handle, kind, scope, location} — or {ambiguous, candidates} |
resolve_at(file, line, column) | Turn a position (stack frame, pasted line) into a handle | same shape as resolve |
inspect(handle) | Answer "what is this?" — kind, signature, docstring, edge_counts | a structural Node, plus kind-dependent fields (e.g. superclasses; re_exports is deprecated, use the re_exports edge); no source |
outline(handle) | See the structural skeleton of a module or class in one call | a tree of member stubs (direct members by default; max_depth to go deeper) |
expand(handle, edge) | Walk ONE edge to the immediate neighbours | a list of stubs |
trace(start, follow, …) | Walk edges across multiple hops | a subgraph (nodes + edges) |
Notes that matter:
kindis one ofclass,function,method,module,variable,attribute,property,enum_member. A name bound in a class body isattribute(module- and function-level names arevariable); a member of anenum.Enumsubclass isenum_member. Where pyeye can't tell statically that a binding is a member, it saysattribute, neverenum_member.resolvealready includes alocationpointer, so it answers "where is this defined?" on its own — you do not need a follow-upinspectjust for location. Useinspectwhen you want signature/docstring/edge_counts.- Ambiguity: a bare name can match several symbols.
resolvethen returns{found: true, ambiguous: true, candidates: [...]}, each candidate carryinghandle/kind/scope/location. Pick the right one, or re-resolve with the full dotted handle. At most 50 candidates come back by default (max_candidates); when more matched, the result also saystruncated: true,truncation_reasons: ["max_candidates"]andtotal. Resolve a dotted handle, or passmax_candidates=None, to see them all. - Capped lists:
expandreturns at most 200 stubs by default (max_stubs). When the edge has more, the result saystruncated: true,truncation_reasons: ["max_stubs"]andtotal(the edge's full size); passmax_stubs=Nonefor all. When nothing was cut, none of the three is present. - A bare name that is a top-level module resolves to that module.
resolve("functools")is stdlibfunctoolsandresolve("inspect")is stdlibinspect, even when the project also defines something with that name. To reach the project's symbol or submodule, use its dotted handle:resolve("jaraco.functools"), orpyeye.mcp.operations.inspectin pyeye's own repo. Only two top-level packages sharing a name across project roots stay ambiguous. - A bare method or class-attribute name is a fallback. Bare names are looked up
among modules and top-level definitions first; only if none match does
resolvelook at methods and class-body attributes. One match → that member (resolve("load_settings")→pkg.config.Loader.load_settings); several →ambiguouswith every candidate. Because it's a fallback, a top-levelhelperanswersresolve("helper")and a same-namedClass.helperis not listed. UseClass.helper's dotted handle for it. Dunder names (__eq__,__repr__) are never matched this way; they returnunresolvedwith a hint to use the class's dotted handle orexpand(<class>, "members"). Not found: check
foundon everyresolve/resolve_at/inspect/outline/expandresult. A miss returns{found: false, <your input echoed>, reason, detail}with no node, tree, or stubs, anddetailnaming the next step:inspect/outline/expandechohandle(plusedgeforexpand), withreason: "unresolved". That means "pyeye couldn't resolve this handle as written": unknown, not evidence the symbol is absent, and not an empty symbol. Often it is the right name under the wrong module path, but some real symbols never resolve (an instance attribute assigned in__init__, such asself.project_path = …). Re-resolvethe bare name to get the canonical handle; if that misses too, fall back toReador your LSP before concluding anything.resolveechoesidentifier, andresolve_atechoesfile/line/column. Theirreasonisunresolved,file_not_foundorno_symbol_at_position. A missing file is not a spelling problem, so don't retryresolvewith other names for it.- Only a
handlekey is ever a handle. Never passidentifierorfiletoinspect.
By contrast,
expand'sstubs: []withfound: trueis a measured zero.- Errors vs misses: a call that ran is always a response (found,
found: false, or unsupported). A miss is never an error. A call fails with an MCP tool error only when it can't run: an invalid argument (e.g.line=0), aproject_paththat doesn't exist, an unusable config, or an unreadable file. The error message names what to fix, so fix that argument and call again; don't read a tool error as "not found". - Unparseable source: if a file can't be parsed by the Python pyeye runs on (e.g.
the code uses newer syntax), its edges weren't measured.
expand/tracesayreason: "unparseable"andoutlinemarks the nodetruncation_reason: "unparseable"with nochildren;inspectleaves the count out. That is unknown, not empty:Readthe file (thedetailnames the line), or run pyeye on a newer Python. scopeis"project"or"external". Project symbols get full-graph answers; external symbols (stdlib, site-packages) get project-scoped answers — see the scope example below.- No source content, ever.
inspect/outline/expand/tracereturn pointers and structured facts.Readis the content layer.
Supported Edges
expand and trace walk these edges. This is the complete set pyeye can answer
reliably today:
<!-- pyeye-supported-edges: members callees imported_by subclasses superclasses imports enclosing_scope submodules re_exports -->| Edge | Direction | Meaning |
members | container → children | a class's methods/attributes, or a module's top-level defs (imported names belong to imports, not here) |
submodules | package → child modules/subpackages | a package's direct child modules and subpackages (one hop; full tree via trace) |
enclosing_scope | child → parent | the one lexical scope containing this symbol (method → class, etc.) |
callees | function → what it calls | forward call targets resolved from the body |
subclasses | class → its direct subclasses | project classes that directly extend this class (one hop; full closure via trace) |
superclasses | class → its bases | the class's direct base classes, in declaration order; bases that don't resolve are listed in unresolved_superclasses |
imports | module → what it imports | every import that binds a module-scope name — including ones under if TYPE_CHECKING: or a try/except ImportError shim (both branches); imports inside a def/class body are not module imports |
imported_by | module → its importers | project modules that import this module, wherever the import sits (inside a def/class body too: a lazy import is still a dependency) |
re_exports | symbol → the public modules that re-export it | each stub is the re-exporting module; its bindings lists the public paths it provides (["pkg.Foo"]). Public = a package __init__, a name in __all__, or a public module importing from a _private one. Not counted in edge_counts; unparseable package files are listed in unparseable_files |
imports and imported_by are not exact inverses. If imports(M) shows
module B, then M is in imported_by(B). The reverse can fail: a module that
imports B only inside a function shows up in imported_by(B) but not in its
own imports, and imports reports a re-exported name at its definition site,
not the module it was imported from.
Pointer-only stubs. subclasses and imported_by stubs are pointers
(handle + location + kind) and intentionally omit signature — even though a
subclass stub's kind is class. Drill with inspect(<handle>) when you need a
subclass's constructor signature or docstring.
Static-surface ceiling. Each structural edge measures a stated scope, and a
returned list is complete only over that scope. A class's members (and so its
outline) are its class-body definitions: methods, nested classes and
class-level assignments. Instance attributes assigned in methods (self.x = …)
are not measured, so self.project_path set in __init__ is absent from
members although it is in source. A module's members are its module-level
definitions. None of these edges covers what exists only at runtime: members / outline /
subclasses do not see runtime-injected relationships — metaclass injection,
setattr, __getattr__, type(...), __init_subclass__ registration, or
importlib with computed targets. So outline of a Django Model omits its
metaclass-injected _meta / objects / DoesNotExist, and the subclasses
edge (direct children) plus a trace subclass closure cover literal
class B(A): subclassing only. An absent member or subclass means "not
measured in that scope": unknown beyond it, not proof of absence. Don't
report a static result as exhaustive over instance attributes or the runtime.
(Same boundary imported_by already names for dynamic imports.)
The boundary is also in the response (#417): expand carries ceiling, the root
of outline carries ceiling, and trace carries ceilings: {edge: id}. The ids:
<!-- markdownlint-disable MD050 -- dunder names are quoted verbatim from edges.CEILING_MEANINGS -->static_definitions: definitions written in source: a class body (methods, nested classes, class-level assignments) or a module's top level. Instance attributes assigned in methods (self.x = ...) and anything injected at runtime (metaclass, setattr, getattr, type(), init_subclass) are not included.literal_subclassing: project classes whose class statement names this class as a base; classes built with type(), class factories or init_subclass registration are not included.declared_bases: the bases written in the class statement; bases added at runtime are not included, and bases that don't resolve are listed in unresolved_superclasses.static_imports: import statements written in source; importlib / import with a computed name is not included.static_calls: calls whose target static analysis resolves; dynamic calls are counted in unresolved_call_sites, not listed.on_disk_modules: modules and subpackages present on disk under the package; entries added to path at runtime are not included.package_reexports: import bindings written in source in the public modules of the symbol's own package (#712); re-exports from other packages and names provided lazily by a module getattr are not included.
<!-- markdownlint-enable MD050 -->enclosing_scope has none: lexical nesting is exact.
⭐ Honest Limits — pyeye Has No Reverse References (Delegate to Your LSP)
This is the most important rule in this skill.
"Who calls this?" and "what references this?" cannot be answered by pyeye — delegate
them to your LSP (below). The
edges callers, references, read_by, written_by, passed_by, overrides,
overridden_by, decorated_by, and decorates are deferred — they need an indexed
reference backend (Pyright) that isn't wired up yet (#333).
When you ask for one, pyeye refuses (reports it as unsupported) rather than returning
a wrong or empty answer. Likewise, inspect's edge_counts simply omits callers
and references — it does not report them as 0.
Do NOT fake reverse-reference data. Delegating to a real reference backend (your editor's LSP — see below) is not faking; this is the cheat to avoid:
- Do not fall back to
grepto guess who calls or references a symbol.
There is no legacy escape hatch. Earlier versions shipped
find_references,get_call_hierarchy, andanalyze_dependencies. They were removed in v2.0, not deprecated, because they answered confidently and wrongly —get_call_hierarchyreturned a structurally always-emptycalleeslist and anchored bare names on the first match with no ambiguity signal;analyze_dependenciesclassified every first-party module as third-party on asrc/layout, which silently disabled its own cycle detection;find_referencesclaimed "ALL usages" with no way to tell an empty result from a failed search. If you remember them, they are gone — a confident wrong answer is worse than an honest "not available."
Why the line falls here: pyeye answers structural facts from the AST, semantic questions with bounded Jedi inference, and leaves the reverse queries Jedi gets wrong to a deterministic backend. The contract behind that split, and how a name becomes a canonical handle, is in Resolution and Determinism.
The reliable path: delegate to your LSP
A real reference index is almost certainly already in your toolbox — a language-server
(LSP) tool backed by Pyright/Pylance (e.g. Claude Code's LSP tool). Use it. pyeye and
the LSP compose: pyeye hands you the definition-site location (file:line:column)
from resolve / inspect / resolve_at — exactly the position an LSP reference query
needs.
Pipeline for "who calls / references this?":
resolve(name)→ canonical handle +location {file, line_start, column_start}.- Feed that position to the LSP:
findReferences,incomingCalls(callers), orgoToImplementation. - The LSP answers in positions;
resolve_at(file, line, column)maps any of them back into pyeye handle space when you want to keep working there.
Roles, not redundancy. pyeye drives orientation, structure, and forward facts; the LSP is the reference specialist you delegate the inbound questions to. Do not run them as two interchangeable navigators, or consult both for the same fact — they infer independently (Jedi vs Pyright) and can disagree, and two oracles voting erodes the trust a single honest answer is for.
When no LSP is available
If your harness has no language-server tool, say so plainly: "pyeye can't give reliable caller/reference data (deferred to #333), and there's no LSP here to delegate to." Then offer what you can answer — and still do not substitute grep:
- Forward from a function:
callees(what it calls). - Around a module:
imported_by(who imports it) andimports(what it imports). - Inheritance:
subclasses/superclasses. - Structure:
members,enclosing_scope.
Hit a pyeye bug or limitation? Report it in-band
pyeye tells you where to file. Every unsupported result from expand, and any
trace that names an unsupported edge, carries a report_issues URL. The
pyeye://about resource returns pyeye's version + repository + issues URL on
demand — fetch it instead of guessing the repo slug. If a limitation looks like a
real defect (not an expected static-surface ceiling), surface that URL to the user.
Absence vs zero
The general rule: a value pyeye returns is a measured claim over a stated scope;
anything it doesn't return, or can't resolve, is unknown, not absent. That covers
found: false (a resolution miss, not proof of absence), returned lists
(complete only over their stated scope, see the static-surface ceiling above), and
optional fields (absent means not measured).
When you read edge_counts, a missing key means "not measured," not "zero." A
present superclasses: 0 means measured-and-none (the class has no bases). An absent
callers key means pyeye didn't measure it — don't read that as "no callers."
trace honesty fields — an empty subgraph is not always "nothing there"
A trace Subgraph carries several honesty fields. Read them before treating the graph as
complete — an empty or clean-looking subgraph can mean a resolution miss, not a real zero:
unresolved_roots(always present):[]means every root resolved. A non-empty list means those start handles did not resolve — sonodes: {}with a non-emptyunresolved_rootsis "I couldn't resolve the root" (a cold-start miss is possible, #419), not "this root has no neighbours." Retry,resolve/inspectthe handle, or fall back toRead/your LSP — do not conclude the symbol calls/contains nothing.unresolved_nodes(always present): interior nodestracereached but could not resolve (the same handlesexpandanswersfound: falsefor), so it did not walk them. A node listed here is a dead end of the walk, not a node with no neighbours.unsupported_edgesalso lists an edge that doesn't apply to some node's kind (e.g.importson a class), withreason: "not_applicable": itsdetailnames the kind and the kinds the edge does apply to. Those nodes were not walked along that edge — that's "not applicable", not "measured, none".expandgives the samenot_applicableanswer directly (e.g.memberson a function,subclasseson a module), never astubs: [].unresolved_call_sites(present only when you tracedcallees): a{handle: count}map of nodes whose outbound calls were not fully resolved (dynamic/un-inferable sites, or a flaky miss). A node listed here has incomplete callees — don't treat its part of the call graph as exhaustive. An absent field means call sites weren't measured (you didn't tracecallees);{}means traced and all resolved.unresolved_imports(present only when you tracedimports): a{handle: [target, …]}map of nodes whoseimportswalk couldn't resolve a statically-presentfrom X import Y(each entry is the intended dotted target). A node listed here has an incomplete import set — a dependency closure is missing those edges.expand(handle, "imports")carries the same signal as a flatunresolved_imports: [target, …]list ([]when all resolved).unresolved_importers(present only when you tracedimported_by): a{handle: [file, …]}map of files that import that module but have no module name (a path part that isn't a Python identifier, e.g.my-script.py,tools-dir/x.py), so they can't be stubs. They are still dependents: count them when sizing fan-in.expand(handle, "imported_by")carries the same flatunresolved_importers: [file, …]list ([]when every importer has a handle).unparseable_files(present only when you tracedsubclasses,imported_byorre_exports): a{handle: [file, …]}map of project files the server's Python couldn't parse (often newer syntax than its interpreter), so the reverse scan never read them. A subclass or importer defined there is unknown, not absent.expand(handle, "subclasses" | "imported_by" | "re_exports")carries the same flatunparseable_files: [file, …]list ([]when every file parsed). Read those files, or run pyeye on a newer Python, before concluding.
So "no callers"-style reasoning from a trace result requires unresolved_roots == [] and
(for call graphs) the relevant node absent from unresolved_call_sites; a dependency-closure
claim from imports likewise requires the node absent from unresolved_imports, and a
"nothing depends on this" claim from imported_by requires it absent from unresolved_importers
— and, for imported_by and subclasses, an empty unparseable_files.
Framework plugin tools — always pass envelope=true
When pyeye detects Pydantic, Django or Flask (in the project or a configured package),
it also registers that framework's tools (find_pydantic_models, get_model_schema,
find_django_models, find_flask_routes, find_error_handlers, …). After
configure_packages adds a package that brings a new framework, its result lists the
newly activated plugins in activated_plugins, and their tools are callable by name
at once: call them even if your tool list hasn't refreshed (pyeye sends no
list-changed notification). By default they return a bare list:
an empty answer is zero content items, and nothing says which scope was searched.
"These are all the models" looks the same as "these are the main repo's models".
Another project: pass project_path, as on the core tools. Plugin tools run against
the given project even if its framework wasn't auto-detected there; an empty result means
the scan found none. Omitted, they answer about the project the server started in. A
project_path that doesn't exist is a tool error.
Always call them with envelope=true. You get one object back:
{ scope: "main", searched: ["main"], unsearched_scopes: ["namespace:company"], results: [...] }resultsis the tool's normal answer ([]means searched and found none).searchedlists the configured scopes that were fully searched.unsearched_scopeslists configured scopes the search did not cover. If it is non-empty, don't call the result complete: retry withscope="all", or say which scopes you didn't search.
These tools read source as text and only skip files that can't be read or parsed. A tool error means the search failed. Report it; don't treat it as an empty result.
Each result record carries a handle when it names a symbol: pass that to inspect,
outline, expand or trace, rather than re-resolving the record's name, which can
be ambiguous. A record with unresolved instead has no handle; say so rather than
guessing one.
Workflow
digraph python_explore {
rankdir=TB;
"Task involves Python code" [shape=diamond];
"Explicit read/show request?" [shape=diamond];
"Already explored in context?" [shape=diamond];
"Reverse-reference question?" [shape=diamond];
"Respect request, use Read()" [shape=box];
"Use what's in context" [shape=box];
"Delegate to LSP; else state limit + forward edges" [shape=box];
"Orient: resolve then inspect / outline" [shape=box];
"Drill / trace as needed" [shape=box];
"Proceed with task" [shape=box];
"Task involves Python code" -> "Explicit read/show request?" [label="yes"];
"Task involves Python code" -> "Proceed with task" [label="no"];
"Explicit read/show request?" -> "Respect request, use Read()" [label="yes"];
"Explicit read/show request?" -> "Already explored in context?" [label="no"];
"Already explored in context?" -> "Use what's in context" [label="yes"];
"Already explored in context?" -> "Reverse-reference question?" [label="no"];
"Reverse-reference question?" -> "Delegate to LSP; else state limit + forward edges" [label="yes"];
"Reverse-reference question?" -> "Orient: resolve then inspect / outline" [label="no"];
"Orient: resolve then inspect / outline" -> "Drill / trace as needed";
"Drill / trace as needed" -> "Proceed with task";
"Use what's in context" -> "Proceed with task";
"Delegate to LSP; else state limit + forward edges" -> "Proceed with task";
}Worked Examples
Handles below use a placeholder project (myapp.…) — substitute your own. The
pathlib example is real and works anywhere.
"What is Settings?" — orient in one or two calls:
resolve("myapp.config.Settings") -> { handle: "myapp.config.Settings", kind: "class",
scope: "project", location: {...} }
inspect("myapp.config.Settings") -> kind, signature, docstring,
edge_counts: { members: 7, superclasses: 1 }Ambiguous name — let resolve disambiguate, don't guess:
resolve("Settings") -> { ambiguous: true, candidates: [
{ handle: "myapp.config.Settings", ... },
{ handle: "myapp.cli.Settings", ... } ] }Pick the candidate you meant, or re-resolve with the full dotted handle.
"I'm looking at this line / stack frame — what is it?" — position to handle:
resolve_at("myapp/cache.py", line=42, column=8) -> { handle: "myapp.cache.Cache.evict", ... }"What's inside this module?" — skeleton in one call:
outline("myapp.cache") -> direct members (Cache, DependencyTracker, ...); classes marked truncated: max_depth
outline("myapp.cache.Cache") -> drill into one class: its methods and attributes
outline("myapp.cache", max_depth=2) -> module + each class's members in one calloutline defaults to direct members only (max_depth=1) for every root.
A nested container that has members comes back truncated: max_depth with no
children, plus member_count saying how many it holds. That means "not walked
yet", not "empty": outline its handle to drill in, or pass a larger max_depth
(None = unbounded, still capped by max_nodes).
Check the root's truncation_reasons first: it lists every reason any node was
cut for (absent when nothing was). max_depth / max_nodes are budget cuts, so
raise the limit, and the node's count says how much is missing. external /
survey_leaf are boundaries by design, so outline that node instead.
Cold start: "what's in this package / project?" — orient top-down, drill on
demand. outline on a package surveys its child modules/subpackages (depth-1
by default — subpackages marked truncated: max_depth); pass a higher
max_depth, or expand/trace the submodules edge, to go deeper. A survey
lists modules, not their members: a module that has members comes back
truncated: survey_leaf (outline that module to see them), and only a
genuinely empty one is children: []. A package's own __init__ members are
not listed either — member_count: N on a walked package says how many were left
out (expand(pkg, "members") lists them). Counts are named for their edge and
match inspect's edge_counts: a survey cut by max_nodes carries
submodule_count. A package with no submodules is outlined
by its members instead:
resolve("myapp") -> { handle: "myapp", kind: "module", scope: "project" }
outline("myapp") -> direct submodules/subpackages (depth-1 survey)
expand("myapp.db", "submodules") -> one hop of a subpackage's children
trace("myapp", follow=["submodules"], max_depth=3) -> bounded package tree (capped + `truncated`)Then drill: resolve(root) → outline(pkg) | expand(pkg, "submodules") → pick a
module → inspect / expand("members") / trace.
Namespace-rooted packages work the same way. A PEP 420 namespace package (no
__init__.pyat its root) resolves tokind: "module", anchored on its directory, and namespaces configured in.pyeye.jsoncount asscope: "project", including repos that live outside the project root.
"What does this function call?" — forward, reliable:
expand("myapp.cache.Cache.evict", edge="callees") -> stubs for each call target"Who imports this module?" — reverse, but reliably static:
expand("myapp.cache", edge="imported_by") -> module stubs that import myapp.cache"What subclasses this base?" — inheritance down. expand returns the
direct children (one hop); for the full transitive closure use trace with
explicit bounds (the class result carries a static transitive_hint pointing
there):
expand("myapp.plugins.Base", edge="subclasses") -> project classes DIRECTLY extending Base
trace("myapp.plugins.Base", follow=["subclasses"], max_depth=3)
-> bounded subtree of the full subclass closure (capped + `truncated`)Multi-hop closure — structure across hops:
trace(start="myapp.cache.Cache.evict", follow=["callees"], max_depth=3)
-> subgraph of the 3-hop forward call structureProject vs external scope — pathlib.Path is external, so subclasses come back
project-scoped:
inspect("pathlib.Path") -> scope: "external", members/signature derived on demand
expand("pathlib.Path", edge="subclasses") -> only classes in THIS project that extend Path"Who calls Cache.evict?" — pyeye defers it; delegate to the LSP:
resolve("myapp.cache.Cache.evict") -> location: { file: "myapp/cache.py", line_start: 42, column_start: 8 }
# then hand that position to your LSP tool:
LSP.incomingCalls("myapp/cache.py", line=42, character=9) -> real callers, with call sitespyeye doesn't index callers (deferred to #333), so I delegated:
resolvegave the def-site location and the LSP'sincomingCallsreturned the real callers. (I can map any back to a handle withresolve_at.)
With no LSP tool in reach, the honest refusal instead:
Reliable caller data isn't available —
callersis deferred (#333), there's no LSP here to delegate to, and grep would under-report. What I can show: whatCache.evictitself calls (callees), and which modules importmyapp.cache(imported_by). Want either?
Dependency & Coupling Analysis
Module relationships are answerable from two static edges — imports (what a
module depends on) and imported_by (which project modules depend on it) — plus
trace(follow=["imports"]) for the multi-hop closure. From those you can compute
the standard coupling metrics by hand:
- Fan-out (efferent): size of
expand(mod, "imports")— how many things this module depends on. High fan-out = many reasons to change = fragile. - Fan-in (afferent): size of
expand(mod, "imported_by")— how many project modules depend on this one. High fan-in = changes here are risky. - Instability:
fan_out / (fan_in + fan_out).0= stable (depended on, depends on nothing);1= unstable (depends on others, nothing depends on it). Entry points sit near 1; core/shared modules near 0.
Detecting cycles: trace(start=mod, follow=["imports"]), then scan the
returned edges for one whose to is the start module. trace visits each node
once but still records edges back into already-visited nodes, so that back-edge is
exactly an A → … → A circular dependency. (Look in edges, not nodes — nodes
are deduped, so the start won't literally reappear.) Standard ways out: extract a
shared base module both can import, inject the dependency instead of importing it,
or move the import inside the function (lazy import).
Reading the architecture: a clean layered design shows imports flowing one
direction (API → services → models → external) with no back-edges; a "utility
hub" shows one low-instability module with high fan-in; a cycle is the
anti-pattern. Map a few key modules with expand(…, "imports") to see which
shape you have before refactoring.
Same static-surface ceiling as everywhere else: dynamic imports (
importlib.import_module(), plugin loaders, conditional imports) are invisible here — an absent edge means "not imported in source," not "never loaded."
Stating Your Mental Model
When it helps the user — a non-trivial change, an ambiguous request, a risky edit —
state what you found before proceeding. Use canonical handles + file:line so the
user can correct you:
**Mental model: `myapp.cache.Cache`** (`myapp/cache.py:31`)
- Depends on: `myapp.config.Settings`, `collections.OrderedDict`
- I can see: 7 members, 1 superclass (measured); subclasses on demand via `expand`
- Callers/references: pyeye defers them (#333) — get them from the LSP; without one, caller impact is unverifiedScale this to the task. A pure "how does X work?" answer may need no separate summary; a refactor that touches shared code deserves one — and should be explicit that caller impact can't be statically confirmed.
Failure Mode
If pyeye is unavailable (server down, tools not responding):
- Note it explicitly: "pyeye unavailable — falling back to
Read()." - Proceed with
Read(). - Warn that static structural analysis is unavailable.
Don't block — degrade gracefully, but make the limitation visible.
Red Flags — You're About to Violate This Skill
- Your first tool call is
Read()on a Python file you haven't oriented in pyeye. - Reaching for
grepto find a definition. - Reaching for
grepto answer a relationship/reference question. - Reaching for a pre-v2.0 tool name you remember — the primitives in the table above are the whole surface, plus the framework plugin tools when a framework is detected.
- Calling a framework plugin tool without
envelope=true, or reporting itsresultsas complete whileunsearched_scopesis non-empty. - Faking "who calls this" with grep instead of delegating to your LSP (or, with no LSP, stating the limit honestly).
- Re-exploring a symbol pyeye already surfaced in this conversation.
If you catch yourself doing any of these: STOP. Orient with pyeye, or say honestly what it can't answer.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

