obsidian_list_files

Instructions

Implementation Reference

• src/tools.ts:99-118 (registration)

  Registration of the 'obsidian_list_files' tool with its Zod schema and handler. The handler delegates to vaults.listEntries() and then paginates results.

  tool(
    "obsidian_list_files",
    "List files and folders in a vault folder. Supports recursive walks, max depth, and extension filtering.",
    {
      vault: vaultArg,
      folder: z.string().optional().default("."),
      recursive: z.boolean().optional().default(false),
      maxDepth: z.number().int().min(1).max(20).optional().default(4),
      extension: z.string().optional(),
      includeDirectories: z.boolean().optional().default(true),
      limit: z.number().int().min(1).max(5000).optional().default(1000),
      offset: z.number().int().min(0).optional().default(0),
    },
    async (args) => {
      const entries = await vaults.listEntries(args.vault, args);
      const page = entries.slice(args.offset, args.offset + args.limit);
      return { entries: page, total: entries.length, offset: args.offset, truncated: args.offset + args.limit < entries.length };
    },
    { readOnlyHint: true },
  );

• src/tools.ts:103-110 (schema)

  Input schema for obsidian_list_files: vault, folder, recursive, maxDepth, extension, includeDirectories, limit, offset.

  vault: vaultArg,
  folder: z.string().optional().default("."),
  recursive: z.boolean().optional().default(false),
  maxDepth: z.number().int().min(1).max(20).optional().default(4),
  extension: z.string().optional(),
  includeDirectories: z.boolean().optional().default(true),
  limit: z.number().int().min(1).max(5000).optional().default(1000),
  offset: z.number().int().min(0).optional().default(0),

• src/tools.ts:112-116 (handler)

  Handler function for obsidian_list_files: calls vaults.listEntries() then paginates the results with offset/limit.

  async (args) => {
    const entries = await vaults.listEntries(args.vault, args);
    const page = entries.slice(args.offset, args.offset + args.limit);
    return { entries: page, total: entries.length, offset: args.offset, truncated: args.offset + args.limit < entries.length };
  },

• src/vault.ts:209-248 (helper)

  VaultManager.listEntries() - the core helper that performs the actual file listing using fast-glob, filtering by folder, recursion, depth, extension, and directory inclusion.

  async listEntries(
    vaultName?: string | null,
    options: { folder?: string; recursive?: boolean; maxDepth?: number; extension?: string; includeDirectories?: boolean } = {},
  ): Promise<VaultFileEntry[]> {
    const vault = this.getVault(vaultName);
    const folder = normalizeRelativePath(options.folder || ".");
    const base = this.resolvePath(folder, vault.name);
    const depth = options.recursive ? options.maxDepth ?? 20 : 1;
    const pattern = options.recursive ? "**/*" : "*";
    const entries = await fg(pattern, {
      cwd: base.absolute,
      dot: false,
      onlyFiles: false,
      markDirectories: false,
      ignore: DEFAULT_IGNORES,
      deep: depth,
      stats: true,
      followSymbolicLinks: false,
    });
    const out: VaultFileEntry[] = [];
    for (const item of entries) {
      if (typeof item === "string") continue;
      const rel = toPosix(path.join(base.relative === "." ? "" : base.relative, item.path));
      const stats = item.stats;
      if (!stats) continue;
      const isDir = stats.isDirectory();
      if (isDir && options.includeDirectories === false) continue;
      const ext = path.posix.extname(rel);
      if (options.extension && ext.toLowerCase() !== normalizeExtension(options.extension)) continue;
      out.push({
        path: rel,
        name: path.posix.basename(rel),
        type: isDir ? "directory" : "file",
        size: stats.size,
        mtime: stats.mtime.toISOString(),
        extension: ext,
      });
    }
    return out.sort((a, b) => a.path.localeCompare(b.path));
  }

• src/vault.ts:29-36 (helper)

  Return type VaultFileEntry used by listEntries, defining the structure of each entry in the file listing.

  export type VaultFileEntry = {
    path: string;
    name: string;
    type: "file" | "directory";
    size: number;
    mtime: string;
    extension: string;
  };