dir-assistant

dir-assistant

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

Stars: 400

Visit
 screenshot

Dir-assistant is a tool that allows users to interact with their current directory's files using local or API Language Models (LLMs). It supports various platforms and provides API support for major LLM APIs. Users can configure and customize their local LLMs and API LLMs using the tool. Dir-assistant also supports model downloads and configurations for efficient usage. It is designed to enhance file interaction and retrieval using advanced language models.

README:

dir-assistant

PyPI GitHub license GitHub last commit PyPI - Downloads GitHub stars Ko-fi Link

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

(Demo GIF of dir-assistant being run)

Summary

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.

Features

  • 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.
  • Context caching optimization to reduce cost and latency.
  • Optionally configure a separate, faster LLM for the CGRAG guidance step to reduce cost and latency.

New Features

  • The embedding index is now separated by model in the database. This means you can switch between embedding models without needing to re-index files.
  • Indexing is now parallelized and faster.
  • Fixed a bug where the context optimizer was not utilizing the whole context

Quickstart

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. Automation Usage

Local Model

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

For Windows

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

For Ubuntu 24.04

pip3 has been replaced with pipx starting in Ubuntu 24.04.

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

Gemini

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

For Windows

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

For Ubuntu 24.04

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

Claude

To get started quickly with Anthropic's Claude models (e.g., Claude 3.7 Sonnet):

  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-3-7-sonnet-20240729"
  4. Navigate to your project directory and run:
    cd directory/to/chat/with
    dir-assistant

For Windows (Claude)

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

For Ubuntu 24.04 (Claude)

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

GPT5

To get started quickly with OpenAI's models (e.g., GPT-4o):

  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-4o"
  4. Navigate to your project directory and run:
    cd directory/to/chat/with
    dir-assistant

For Windows (OpenAI)

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

For Ubuntu 24.04 (OpenAI)

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

Automation Usage

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"

For Ubuntu 24.04

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"

More Documentation

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

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for dir-assistant

Similar Open Source Tools

For similar tasks

For similar jobs