Ask My Folder Agent

npm package that exposes an agent which reads a local directory, understands files, and answers questions.

Install

npm install @vaibhav-iyer/ask-my-folder-agent

Usage (Mastra Agent)

import { createAskMyFolderAgent } from "@vaibhav-iyer/ask-my-folder-agent";

const agent = createAskMyFolderAgent({
  root: ".",
  model: "openai/gpt-4.1"
});

console.log(await agent.ask({ question: "Summarize this folder." }));

To use OpenAI, set OPENAI_API_KEY in your environment before running.

CLI

ask-my-folder -q "Where is the API client defined?"
ask-my-folder --root ./src --include .ts,.md "How does auth work?"
ask-my-folder --model openai/gpt-4.1 -q "Summarize this folder"

API

• createAskMyFolderAgent({ root, model?, readOptions?, instructions?, id?, name? })

  • root: folder path to read
  • model: LLM model id (e.g. openai/gpt-4.1)
  • readOptions: tweak max files, sizes, include/exclude
  • returns { root, agent, index, ask } where agent is a Mastra Agent

• readFolder(options)

• buildContext(files, maxChars)

• simpleSearchAnswer({ question, files })

Notes

• Skips binary files and common build folders by default.
• Uses Mastra's Agent + tool system internally.
• When using OpenAI, set OPENAI_API_KEY in your environment.
• simpleSearchAnswer is an optional helper; ask() uses the model.