Chat with your current directory's files using a local or API LLM.

dir-assistant is a CLI python application available through pip that recursively indexes all text files in the current working directory so you can chat with them using a local or API LLM. By "chat with them", it is meant that their contents will automatically be included in the prompts sent to the LLM, with the most contextually relevant files included first. dir-assistant is designed primarily for use as a coding aid and automation tool.

This tool is primarily aimed at developers and technical users who need to:

• Quickly understand a large or unfamiliar codebase.
• Get explanations for specific functions, classes, or modules.
• Ask high-level questions like "What is the main purpose of this application?".
• Perform targeted, highly accurate updates in large corpora of text/code.
• Automate file modifications, analysis, refactoring, or documentation tasks.

• Includes an interactive chat mode and a single prompt non-interactive mode.
• When enabled, it will automatically make file updates and commit to git.
• Local platform support for CPU (OpenBLAS), Cuda, ROCm, Metal, Vulkan, and SYCL.
• API support for all major LLM APIs. More info in the LiteLLM Docs.
• Uses a unique method for finding the most important files to include when submitting your prompt to an LLM called CGRAG (Contextually Guided Retrieval-Augmented Generation). You can read this blog post for more information about how it works.
• Automatically optimizes prompts for context caching optimization to reduce cost and latency. Typical use cases have 50-90% cache hits.

• Switched from euclidean distance to cosine similarity for artifact relevancy filtering. When upgrading, you will need to run dir-assistant clear.
• Added ARTIFACT_COSINE_CUTOFF and ARTIFACT_COSINE_CGRAG_CUTOFF to exclude artifacts with low cosine similarity.
• Updated support for the latest version of llama-cpp-python.

In this section are recipes to run dir-assistant in basic capacity to get you started quickly.

1. Local Model
2. Gemini
3. Claude
4. GPT5
5. Other Models
6. Detailed Documentation

To get started locally, you can download a default llm model. Default configuration with this model requires 3GB of memory on most hardware. You will be able to adjust the configuration to fit higher or lower memory requirements. To run via CPU:

pip install dir-assistant[recommended]
dir-assistant models download-embed
dir-assistant models download-llm
cd directory/to/chat/with
dir-assistant

To run with hardware acceleration, use the platform subcommand:

...
dir-assistant platform cuda
cd directory/to/chat/with
dir-assistant

See which platforms are supported using -h:

dir-assistant platform -h

It is not recommended to use dir-assistant directly with local LLMs on Windows. This is because llama-cpp-python requires a C compiler for installation via pip, and setting one up is not a trivial task on Windows like it is on other platforms. Instead, it is recommended to use another LLM server such as LMStudio and configure dir-assistant to use it as a custom API server. To do this, ensure you are installing dir-assistant without the recommended dependencies:

pip install dir-assistant

Then configure dir-assistant to connect to your custom LLM API server: Connecting to a Custom API Server For instructions on setting up LMStudio to host an API, follow their guide: https://lmstudio.ai/docs/app/api

pip3 has been replaced with pipx starting in Ubuntu 24.04.

pipx install dir-assistant[recommended]
...
dir-assistant platform cuda --pipx

To get started using an API model, you can use Google Gemini 2.5 Flash, which is currently free. To begin, you need to sign up for Google AI Studio and create an API key. After you create your API key, enter the following commands:

pip install dir-assistant
dir-assistant setkey GEMINI_API_KEY xxxxxYOURAPIKEYHERExxxxx
cd directory/to/chat/with
dir-assistant

Note: The Python.org installer is recommended for Windows. The Windows Store installer does not add dir-assistant to your PATH so you will need to call it with python -m dir_assistant if you decide to go that route.

pip install dir-assistant
dir-assistant setkey GEMINI_API_KEY xxxxxYOURAPIKEYHERExxxxx
cd directory/to/chat/with
dir-assistant

pip3 has been replaced with pipx starting in Ubuntu 24.04.

pipx install dir-assistant
dir-assistant setkey GEMINI_API_KEY xxxxxYOURAPIKEYHERExxxxx
cd directory/to/chat/with
dir-assistant

To get started quickly with Anthropic's Claude models:

1. Obtain an API key from Anthropic.
2. Install dir-assistant and set your API key:

   pip install dir-assistant
   dir-assistant setkey ANTHROPIC_API_KEY xxxxxYOURAPIKEYHERExxxxx

3. Configure dir-assistant to use Claude. Open the config file with dir-assistant config open and make sure these settings are present:

   [DIR_ASSISTANT]
   ACTIVE_MODEL_IS_LOCAL = false
   LITELLM_MODEL_USES_SYSTEM_MESSAGE = true
   LITELLM_CONTEXT_SIZE = 200000
   [DIR_ASSISTANT.LITELLM_COMPLETION_OPTIONS]
   model = "anthropic/claude-sonnet-4-5-20250929"

4. Navigate to your project directory and run:

   cd directory/to/chat/with
   dir-assistant

pip install dir-assistant
dir-assistant setkey ANTHROPIC_API_KEY xxxxxYOURAPIKEYHERExxxxx
# Then, configure the model as shown above using 'dir-assistant config open'
cd directory/to/chat/with
dir-assistant

pipx install dir-assistant
dir-assistant setkey ANTHROPIC_API_KEY xxxxxYOURAPIKEYHERExxxxx
# Then, configure the model as shown above using 'dir-assistant config open'
cd directory/to/chat/with
dir-assistant

To get started quickly with OpenAI's models:

1. Obtain an API key from OpenAI.
2. Install dir-assistant and set your API key:

   pip install dir-assistant
   dir-assistant setkey OPENAI_API_KEY xxxxxYOURAPIKEYHERExxxxx

3. Configure dir-assistant to use an OpenAI model. Open the config file with dir-assistant config open and make sure these settings are present:

   [DIR_ASSISTANT]
   ACTIVE_MODEL_IS_LOCAL = false
   LITELLM_MODEL_USES_SYSTEM_MESSAGE = true
   LITELLM_CONTEXT_SIZE = 128000
   [DIR_ASSISTANT.LITELLM_COMPLETION_OPTIONS]
   model = "gpt-5"

4. Navigate to your project directory and run:

   cd directory/to/chat/with
   dir-assistant

pip install dir-assistant
dir-assistant setkey OPENAI_API_KEY xxxxxYOURAPIKEYHERExxxxx
# Then, configure the model as shown above using 'dir-assistant config open'
cd directory/to/chat/with
dir-assistant

pipx install dir-assistant
dir-assistant setkey OPENAI_API_KEY xxxxxYOURAPIKEYHERExxxxx
# Then, configure the model as shown above using 'dir-assistant config open'
cd directory/to/chat/with
dir-assistant

The non-interactive mode of dir-assistant allows you to create scripts which analyze your files without user interaction. To get started using an API model, you can use Google Gemini 1.5 Flash, which is currently free. To begin, you need to sign up for Google AI Studio and create an API key. After you create your API key, enter the following commands:

pip install dir-assistant
dir-assistant setkey GEMINI_API_KEY xxxxxYOURAPIKEYHERExxxxx
cd directory/to/chat/with
dir-assistant -s "Describe the files in this directory"

pip3 has been replaced with pipx starting in Ubuntu 24.04.

pipx install dir-assistant
dir-assistant setkey GEMINI_API_KEY xxxxxYOURAPIKEYHERExxxxx
cd directory/to/chat/with
dir-assistant -s "Describe the files in this directory"

Dir-assistant supports almost every local and API model. Almost all local GGUF models (except the bleeding edge) are supported via embedded llama-cpp-python integration. Almost all API models are supported via LiteLLM integration, including generic OpenAI-compatible APIs like local servers. To learn how to use the model of your choice, view the configuration docs.

1. Install
2. Usage
3. Configuration
4. Project Information
5. Contributors