CodeQuery API is a lightweight and efficient Python/Flask tool designed to enable AI assistants—such as custom GPTs—to navigate and interact with local code. With this API, LLM agents* can effortlessly query project structures and retrieve up-to-date file contents, helping developers efficiently explore and manage large codebases. By adhering to customizable ignore patterns via .agentignore, the API ensures that only relevant files are probed, making it an invaluable tool for AI-driven code analysis and development.
* An LLM agent is the decision-making component of an AI assistant. Read more about about agents in this article. (You don't necessarily need to know about them to use CodeQuery, but a bit of knowledge is beneficial.)
🤖 Curious Fact: During its development, the CodeQuery API was an integral part of its own creation process, being used to analyze, write, and debug its own files while the project evolved. This unique feedback loop made it a participant in its own development stages!
- Designed for AI Assistants: This API was specifically designed to integrate with AI assistants such as custom GPTs, providing them with efficient access to project file structures and contents.
- Retrieve Project Structure: Get a detailed view of the project’s directories and files, excluding those specified in the
.agentignorefile. - Retrieve File Contents: Access the contents of specific files in the project, with error handling for non-existent paths.
- Custom Ignore Patterns: Utilize
.agentignorefor specifying which files or directories to exclude from the structure retrieval.
- Endpoint:
/files/structure - Method:
GET - Description: Retrieves the project directory structure, respecting the ignore patterns in
.agentignore. - Response Example:
{ ".": { "directories": ["src", "tests"], "files": [".agentignore", "openapi.json"] }, "src": { "directories": [], "files": ["app.py"] }, "tests": { "directories": [], "files": ["test_app.py"] } }
-
Endpoint:
/files/content -
Method:
POST -
Description: Retrieves the content of specified files.
-
Request Body:
{ "file_paths": ["app.py", "tests/test_app.py"] } -
Response Example:
{ "app.py": { "content": "# Content of app.py file..." }, "tests/test_app.py": { "content": "# Content of test_app.py file..." } } -
Error Example (File Not Found):
{ "error": "All requested files are missing" }
The .agentignore file works similarly to .gitignore, allowing you to specify files and directories that should be excluded from file structure queries (/files/structure endpoint).
Example:
# General
.git/
.gitignore
.vscode/
assets/
public/
# Python
src/__pycache__/
tests/__pycache__/
__pycache__/
venv/
.benchmarks/
.pytest_cache/
.env
requirements.txt
# JavaScript
node_modules/
package-lock.json
package.json
You can and should customize the CodeQuery API using environment variables defined in a .env file.
PROJECT_PATH: Set this variable to the relative path of the project you are working on.AGENTIGNORE_FILE: Change this if you want another file (such as.gitignore) to determine which files are to be ignored for the/files/structureendpoint. Note that those files can still be accessed by the/files/content/endpoint.
Example .env file:
PROJECT_PATH=../your-project/
AGENTIGNORE_FILE=.agentignore
- Python 3.8+ (3.12 recommended)
- Flask
-
Clone the repository:
git clone https://github.com/your-username/CodeQuery-API.git cd CodeQuery-API -
Install dependencies:
pip install -r requirements.txt
-
Activate local environment && Run the Flask application:
conda activate venv/ && python app.py -
The API will be available at
http://localhost:5001.
This API was designed to be used by custom AI assistants. If you are a ChatGPT Premium user, you can create a custom GPT using the ChatGPT Builder.
-
Go to the GPT Builder in your ChatGPT Premium account.
-
Access the Create tab.
-
Send the following prompt to the GPT Builder to create your custom GPT:
Name: CodeQueryGPT Description: Helps developers analyze code, debug issues, and develop features, by leveraging an API to retrieve project structure and files. Instructions: You are CodeQueryGPT, an AI specialized in actively assisting with software development tasks by querying project files, analyzing code structure, answering questions, and providing direct coding support. You use an external API to fetch the latest file structures and retrieve file contents as needed. Your primary goal is to engage in code analysis, feature development, debugging, and understanding code dependencies, while actively contributing to the coding process. Whether through refactoring, writing new code, or suggesting improvements, you play an active role in the developer's workflow. Your core functionality includes querying the structure of the project to reason about which files are relevant to a user query, retrieving the contents of specific files when requested, and then using the file content to answer queries or write new code directly. Your responses must be clear, concise, and action-oriented, focusing on assisting users with writing or adjusting code, debugging errors, and improving overall code quality. You should prioritize using the information retrieved from the API, interact with the '/files/structure' and '/files/content' endpoints to gather the necessary context, and explain which files are being used. Where relevant, you will identify key dependencies in the codebase, such as files calling others or key functions, and actively engage in writing new code to extend or improve features. Conversation Starters: - Analyse the current project structure and main files. - Help me investigate and debug an issue in the code. - I need assistance in developing a new feature. - Analyze the main files and help me refactor them for better performance.You can of course tweak some of the settings above.
-
Once the GPT is created, go to the Configure tab.
-
Enable the "Code Interpreter & Data Analysis" option.
-
Create a new Action by providing the following OpenAPI schema:
{ "openapi": "3.1.0", "info": { "title": "CodeQuery API", "description": "A Flask API to retrieve the file structure and contents of a project directory", "version": "1.0.0" }, "servers": [ { "url": "<YOUR-GENERATED-NGROK-URL>" } ], "paths": { "/files/structure": { "get": { "summary": "Retrieve the file structure", "description": "Returns the file structure of the project directory in a nested format, showing directories and files.", "operationId": "getFileStructure", "responses": { "200": { "description": "Successful response with the file structure", "content": { "application/json": { "schema": { "type": "object", "properties": { "directories": { "type": "array", "items": { "type": "string" }, "description": "List of directory names" }, "files": { "type": "array", "items": { "type": "string" }, "description": "List of file names" } } } } } } } } }, "/files/content": { "post": { "summary": "Retrieve file contents", "description": "Accepts a list of file paths and returns their contents or an error message if the file does not exist.", "operationId": "retrieveFiles", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "file_paths": { "type": "array", "items": { "type": "string" }, "description": "A list of file paths to retrieve" } }, "required": ["file_paths"] } } } }, "responses": { "200": { "description": "Successful response with file contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_path": { "type": "object", "additionalProperties": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the file" }, "error": { "type": "string", "description": "Error message in case of failure" } } } } } } } } }, "400": { "description": "Error when no file paths are provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Error when all requested files are missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } } } } } } } } } } -
Make sure to update the
"servers.url"field with your ngrok HTTPS URL, which you generate by runningngrok http 5001while the API is running locally.
For information on how data is handled by this API, please refer to the Privacy Policy. The policy explains what data is processed, how it's used, and the lack of data retention within the API.
This project is licensed under the MIT License. See the LICENSE file for details.