ek9_list_files

Answers first: entryCount and paths[] (workspace-relative, the value ek9_read_file takes), then entries[{path, name, kind, size, lastModified}] - never content; direct children unless pathPattern recurses.

Category: Enquiry · Compare: ls / fs.readdir / Glob (Claude Code)

When to use it

You want to know what files exist - one call with no arguments for the workspace root, path:'src' for a directory, pathPattern:'**/*.ek9' to recurse. The discovery primitive when you don't yet know exact filenames.

When not to use it

You want a file's CONTENT, not just its existence/metadata — use ek9_read_file with an entry's path.
You want keyword search across file CONTENTS — use ek9_search_text.
You want the logical workspace structure (modules/packages) not a raw filesystem listing — use ek9_query_workspace.
You want EK9-module-level structure (constructs, deps) not raw files — use ek9_query_module.

Details

Default (no pathPattern) lists DIRECT CHILDREN only — recurse via pathPattern:'**/*'; glob mode returns files only, while direct listings also include directories (kind 'directory', size:null). Every entry's path is workspace-relative — the exact value ek9_read_file / ek9_edit_file take. Entries are sorted by path. maxResults defaults 500 (clamped to 5000); a cut listing opens with truncated:true and entryTotal — narrow the glob or raise maxResults. Errors until ek9_compile has established workspace roots; beyond that, compile-state independent.

Arguments

Argument	Type	What it is
`includeHidden`	boolean	When true, includes dot-files and otherwise-excluded build directories.
`maxResults`	integer	Cap on entries[] (default 500, max 5000). A cut listing opens with truncated:true and entryTotal.
`path`	string	Directory path: workspace-relative (preferred) or absolute inside the workspace. Defaults to the workspace root.
`pathPattern`	string	Optional glob (e.g. "*/.ek9", "test/*/Test.ek9"), applied recursively from path; files only.
`verbosity`	string: full \| summary \| none	full (default) returns entries[] records; summary keeps paths[] and the counts; none collapses the lists to counts.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

List recursively by path pattern

Request

{
  "pathPattern" : "**/*.md"
}

Response

{
  "directory" : ".",
  "entries" : [ {
    "kind" : "file",
    "lastModified" : "<timing>",
    "name" : "README.md",
    "path" : "README.md",
    "size" : 9
  }, {
    "kind" : "file",
    "lastModified" : "<timing>",
    "name" : "NOTES.md",
    "path" : "docs/NOTES.md",
    "size" : 8
  } ],
  "entryCount" : 2,
  "meta" : {
    "serverMs" : "<timing>"
  },
  "pathPattern" : "**/*.md",
  "paths" : [ "README.md", "docs/NOTES.md" ],
  "status" : "ok"
}

List direct children of root

Request

{ }

Response

{
  "directory" : ".",
  "entries" : [ {
    "kind" : "file",
    "lastModified" : "<timing>",
    "name" : "README.md",
    "path" : "README.md",
    "size" : 9
  }, {
    "kind" : "directory",
    "lastModified" : "<timing>",
    "name" : "docs",
    "path" : "docs",
    "size" : null
  }, {
    "kind" : "file",
    "lastModified" : "<timing>",
    "name" : "seed.ek9",
    "path" : "seed.ek9",
    "size" : 130
  } ],
  "entryCount" : 3,
  "meta" : {
    "serverMs" : "<timing>"
...

Cut short here: 4 more lines. The whole recorded call.