{"id":22436486,"url":"https://github.com/sysread/fnord","last_synced_at":"2025-08-01T15:31:23.963Z","repository":{"id":265751958,"uuid":"864172209","full_name":"sysread/fnord","owner":"sysread","description":"Fnord is an AI code archaeologist.","archived":false,"fork":false,"pushed_at":"2025-07-28T20:25:22.000Z","size":21555,"stargazers_count":27,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-28T21:36:30.309Z","etag":null,"topics":["ai","code","database","elixir","embedding","gpt","index","llm","openai","search","vector","vectordb"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sysread.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-27T16:17:34.000Z","updated_at":"2025-07-28T20:25:27.000Z","dependencies_parsed_at":"2024-11-30T19:54:01.036Z","dependency_job_id":"c51242ab-e83f-4e2d-9d30-e1a94861257f","html_url":"https://github.com/sysread/fnord","commit_stats":null,"previous_names":["sysread/fnord"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sysread/fnord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2Ffnord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2Ffnord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2Ffnord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2Ffnord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sysread","download_url":"https://codeload.github.com/sysread/fnord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2Ffnord/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267592972,"owners_count":24112695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","code","database","elixir","embedding","gpt","index","llm","openai","search","vector","vectordb"],"created_at":"2024-12-06T00:07:33.746Z","updated_at":"2025-08-01T15:31:23.951Z","avatar_url":"https://github.com/sysread.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fnord\n\n[![Tests | Dialyzer](https://github.com/sysread/fnord/actions/workflows/run-tests.yml/badge.svg)](https://github.com/sysread/fnord/actions/workflows/run-tests.yml)\n\n- [Description](#description)\n- [Features](#features)\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Tool usage](#tool-usage)\n- [User integrations](#user-integrations)\n- [Writing code (EXPERIMENTAL)](#writing-code)\n- [Copyright and License](#copyright-and-license)\n\n\n## Description\n\n`fnord` is a command line tool that uses multiple LLM-powered agents and tools to provide a conversational interface to your codebase, notes, and other (non-binary) files.\n\nIt can be used to generate on-demand tutorials, playbooks, and documentation for your project, as well as to search for examples, explanations, and solutions to problems in your codebase.\n\n## Why `fnord`?\n\nAI-powered tools are limited by to the data built into their training data. **RAG (Retrieval-Augmented Generation)** using tool calls can supplement the training data with information, such as your code base, to provide more accurate and relevant answers to your questions.\n\nBut even with RAG, the AI still runs up against the **context window**. This is the conversational \"memory\" of the AI, often making use of an \"attention mechanism\" to keep it focused on the current instructions, but causing it to lose track of details earlier in the conversation.\n\nIf you've ever pasted multiple files into ChatGPT or worked with it iteratively on a piece of code, you've probably seen this in action. It may forget constraints you defined earlier in the conversation or hallucinate entities and functions that don't exist in any of the files you've shown it.\n\n`fnord` attempts to mitigate this with cleverly designed tool calls that allow the LLM to ask _other_ agents to perform tasks on its behalf. For example, it can generate a prompt to ask another agent to read through a file and retrieve specific details it needs, like a single function definition, the declaration of an interface, or whether a specific function behaves in a certain way. This keeps the entire file out of the \"coordinating\" agent's context window while still allowing it to use the information in the file to generate a response. This allows `fnord` to conduct more complex research across many files and directories without losing track of the details it needs to provide accurate answers.\n\n\n## Features\n\n- Semantic search\n- On-demand explanations, documentation, and tutorials\n- Git archaeology\n- Learns about your project(s) over time\n- Improves its research capabilities with each interaction\n- User integrations\n\n\n## Installation\n\nFnord is written in [Elixir](https://elixir-lang.org/) and is distributed as an `escript`.\n\n- **Install [elixir](https://elixir-lang.org/)**\n```bash\n# MacOS\nbrew install elixir\n\n# Debian-based\nsudo apt-get install elixir\n```\n\n- **Add the `escript` path to your shell's PATH**\n```bash\necho 'export PATH=\"$HOME/.mix/escripts:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n- **Install `fnord`**\n```bash\nmix escript.install github sysread/fnord\n```\n\n- **Set `OPENAI_API_KEY` in your shell environment**\n\nSet this in your shell environment to the OpenAI project key you wish to use for this tool.\nYou can create a new project and get a key [here](https://platform.openai.com/api-keys).\n\n\n- **Optional: Install `ripgrep`**\n\n`fnord` includes tooling for the LLM to use the `ripgrep` tool in addition to semantic search.\nThis enables the LLM to answer questions about your code base, even if the project has not been indexed yet (with the caveat that the results will be less context-aware).\n\n\n- **Optional: Install a markdown viewer**\n\nMarkdown seems to be the language of choice for LLMs, so installing something like `gum` or `glow` to pipe output to will make the output more readable.\nYou can make your preferred formatter persistent by setting the `FNORD_FORMATTER` environment variable in your shell.\n\n```bash\nexport FNORD_FORMATTER=\"gum format\"\n```\n\n\n## Getting Started\n\nFor the purposes of this guide, we will assume that `fnord` is installed and we are using it to interact with your project, `blarg`, which is located at `$HOME/dev/blarg`.\n\n\n### Index your project\n\nThe first step is to index your project to make it searchable with `fnord`'s semantic search capabilities.\nThe first time you index your project may take a while, especially if there are a lot of files.\n`fnord` respects `.gitignore`, but you may also wish to exclude certain paths or globs from indexing (e.g., `-x 'node_modules'`).\n\n```bash\nfnord index --project blarg --dir $HOME/dev/blarg --exclude 'node_modules'\n```\n\nIf you cancel partway-through (for example, with `Ctrl-C`), you can resume indexing by running the same command again.\n\nYou must re-index your project to reflect changes in the code base, new files, deleted files, or to change the directory or exclusions.\nThis is done by running the same command again.\n\n`fnord` stores its index in `$HOME/.fnord/$project`.\n\nAlthough indexing provides full semantic search capabilities and richer results, `fnord` also supports ad-hoc querying on unindexed projects via directory metadata and `ripgrep` fallback, allowing quicker experimentation without full indexing.\n\n\n### Prime the knowledge base\n\n`fnord` can generate an initial set of learnings about your project to prime its knowledge base.\n\n```bash\nfnord prime --project blarg\n```\n\n\n### Configuration\n\nYou can view and edit the configuration for your project with the `fnord config` command.\n\n```bash\nfnord config list --project blarg\nfnord config set --project blarg --root $HOME/dev/blarg --exclude 'node_modules' --exclude 'vendor'\n```\n\n\n### Search your code base\n\n`fnord`'s semantic search is powered by embeddings generated by OpenAI's `text-embedding-3-large` model. The indexing process does a lot more than simply generate embeddings for the contents of your files. It also generates summary documentation for each file as well as an index of all functions, entities, and symbols in each file to enhance semantic matches for common questions and symbols.\n\n```bash\nfnord search --project blarg --query \"callers of some_function\"\nfnord search --project blarg --query \"some_function definition\"\nfnord search --project blarg --query \"unit tests for some_function\"\n```\n\nThe summaries generated by the indexing process can also be included in the search results with the `--detail` flag.\n\n```bash\nfnord search --project blarg --query \"some_function declaration\" --detail | glow\n```\n\nIf you would like to see more information about a single file, you can use the `summary` command.\n\n```bash\nfnord summary --project blarg --file \"path/to/some_module.ext\" | glow\n```\n\n\n### Search behavior and fallbacks\n\n`fnord` uses semantic search by default when a project has been indexed. If semantic search is unavailable (because the project is unindexed or the index is missing):\n\n- Semantic search will be disabled with a warning.\n- If `ripgrep` is installed and in your PATH, `fnord` will automatically fall back to ripgrep for basic text-based file search.\n- If ripgrep is not available, you will see a warning indicating limited search capability.\n- This fallback behavior lets you query projects immediately without waiting for a full index, providing fast albeit less context-aware results.\n\n\n### Generate answers on-demand\n\n`fnord` uses a combination of LLM-powered agents and tool calls to research your question within your project, including access to semantic search and git tools (read only!).\n\nAs it conducts its investigation, you will see some of the research steps reported back to you in real-time. These are printed to `STDERR` so they will not interfere with redirected output. If you wish to see more of this, set `LOGGER_LEVEL=debug` in your shell.\n\n```bash\nfnord ask --project blarg --question \"Where is the unit test for some_function?\"\nfnord ask --project blarg --question \"Find all callers of some_function\"\nfnord ask --project blarg --question \"Is there a function or method that does X?\"\nfnord ask --project blarg --question \"How do I add a new X implementation?\"\n```\n\n#### Asking questions without prior indexing\n\nYou can now use `fnord ask` on projects that have **not yet been indexed** or where the project index is unavailable.\n\n- If the project is already created in `fnord` but not indexed, semantic search will be disabled, and `ripgrep` fallback will be used if available.\n- If the project does **not exist in fnord yet**, you can provide the project's root directory with the `--directory` (or `-d`) option when running `fnord ask`.\n- This will automatically create the project metadata on demand and allow you to query the project files without requiring a full index upfront.\n\nExample usage:\n\n```bash\n# Ask a question about a project without an index by specifying the source directory\nfnord ask --project blarg --directory $HOME/dev/blarg --question \"Where is the unit test for some_function?\"\n\n# Continue to specify the directory if the project has not been indexed or created yet\nfnord ask --project new_project --directory /path/to/new_project --question \"Explain the main workflow\"\n```\n\nNote: If semantic search is unavailable and `ripgrep` is not installed, you will receive a warning and limited search capability. To get full semantic search power, please index your project using the `fnord index` command.\n\n#### Improve research quality\n\nBy default, `ask` performs a single round of research (multiple tool calls per round notwithstanding).\nYou can increase the number of rounds with the `--rounds` option.\nIncreasing the number of rounds will increase the time it takes to generate a response, but can drastically improve the quality and thoroughness of the response, especially in large code bases or code bases containing multiple apps.\n\n```bash\nfnord ask --project blarg --question \"Please confirm that all information in the README is up-to-date and correct. Identify user-facing functionality that is not well-documented.\" --rounds 3\n```\n\n#### Continuing a conversation\n\nConversations (the transcript of messages between the LLM and the application) are saved for future reference and continuation. After each response, you will see a message like:\n```\nConversation saved with ID: c81928aa-6ab2-4346-9b2a-0edce6a639f0\n```\n\nIf desired, you can use that ID to continue the conversation with `--conversation`.\n\n```bash\nfnord ask --project blarg --conversation c81928aa-6ab2-4346-9b2a-0edce6a639f0 --question \"Is some_function still used?\"\n```\n\n...or can continue the _most recently saved conversation_ with `--follow`.\n\n```bash\nfnord ask --project blarg --follow --question \"Is some_function still used?\"\n```\n\n\nList conversations with the `conversations` command.\n\n```bash\nfnord conversations --project blarg\n```\n\nPrune conversations older than a certain number of days with the `--prune` option.\n\n```bash\n# Prune conversations older than 30 days\nfnord conversations --project blarg --prune 30\n```\n\n#### Replaying a conversation\n\nYou can also `replay` a conversation, replicating the output of the original question, research steps, and response.\n\n```bash\nfnord replay --project blarg --conversation c81928aa-6ab2-4346-9b2a-0edce6a639f0 | glow\n```\n\nAs it learns more about your project, `fnord` will be able to answer more complex questions with less research.\n\n\n### Learning over time\n\n`fnord` learns about your project over time by saving facts and inferences it makes about the project while researching your questions. These facts and inferences are saved and made\nsearchable in the project's data in the `$HOME/.fnord` directory.\n\nYou can view the facts learned thus far, organized by topic, with the `notes` command.\n\n```bash\nfnord notes --project blarg | glow\n```\n\nOver time, these can become quite extensive, redundant, and stale over time as your code base evolves.\n\n`fnord` knows how to \"prime the pump\" for its learning process with an initial set of learnings.\n\n```bash\nfnord ask --project blarg --question \"Prime your research notes and report your findings\"\n```\n\n\n### Upgrades\n\n`fnord` is under active development and new features are added regularly. To upgrade to the latest version, simply run:\n\n```bash\nfnord upgrade\n```\n\nNote that this is just a shortcut for:\n\n```bash\nmix escript.install github sysread/fnord\n```\n\n\n### Other commands\n- List projects: `fnord projects`\n- List files in a project: `fnord files --project foo`\n- Delete a project: `fnord torch --project foo`\n\n\n## Tool usage\n\nAll of the tool calls available to `fnord` are available for external use via the `tool` subcommand.\n\n```bash\n# List available tools\nfnord help tool\n\n# Get help for a specific tool\nfnord tool --tool file_search_tool --help\n\n# Call the tool\nfnord tool --tool file_search_tool --project blarg --query \"some_function definition\"\nfnord tool --tool file_info_tool --project blarg --file \"path/to/some_module.ext\" --question \"What public functions are defined in this file?\"\n```\n\n\n## User integrations\n\nUsers can create their own integrations, called frobs, that `fnord` can use as a tool call while researching.\nJust like built-in tools, these are usable through the `fnord tool` subcommand.\n\n```bash\n# Create a new integration\nfnord frobs create --name my_frob\n\n# Validate the frob\nfnord frobs check --name my_frob\n\n# List frobs\nfnord frobs list\n\n# List frobs that are registered for a project\nfnord frobs list --project blarg\n```\n\nFrobs are stored in `$HOME/fnord/tools` and are comprised of the following files:\n- `my_frob/registry.json` - a JSON file that identifies the projects for which the frob is available\n- `my_frob/spec.json` - a JSON file describing the frob's calling semantics in [OpenAI's function spec format](https://platform.openai.com/docs/guides/function-calling?api-mode=responses#defining-functions)\n- `my_frob/main` - a script or binary that performs the requested task\n\nMake your tool available to your projects: edit the `registry.json` file created when you ran `fnord frobs create` to include the project name(s) for which you want the frob to be available.\n\n```json\n{\n  // When true, the frob is available to all projects and the \"projects\" field is ignored.\n  \"global\": true,\n\n  // An array of project names for which fnord should make the frob available. Superseded by the \"global\" field when set to true.\n  \"projects\": [\"blarg\", \"some_other_project\"]\n}\n```\n\nImplementing the frob: the `main` file is a script or binary that implements the frob. `fnord` passes information to the frob via shell environment variables:\n\n- `FNORD_PROJECT`: The name of the currently selected project\n- `FNORD_CONFIG`: The project configuration from `$HOME/.fnord/settings.json` as a single JSON object\n- `FNORD_ARGS_JSON`: JSON object of LLM-provided arguments\n\nTesting your frob: if you prefix your `fnord ask` query with `testing:`, you can ask the LLM to test your frob to confirm it is working as expected.\n\n```bash\nfnord ask -p blarg -q \"testing: please confirm that the 'my_frob' tool is available to you\"\nfnord ask -p blarg -q \"testing: please make a call to 'my_frob' with the arguments 'foo' and 'bar' and report the results\"\n```\n\n\n## Writing code\nFnord can (optionally) automate code changes in your project using the `ask` command with the `--edit` flag.\n\n**HIGHLY EXPERIMENTAL!**\n- Use `--edit` with extreme caution.\n- AI-driven code modification is unsafe, may corrupt or break files, and must always be manually reviewed.\n\n### How it works\nThe LLM has access to several tools that allow it to modify code within the project directory and perform basic file management tasks.\nIt *cannot* perform write operations with `git` or act on files outside of the project's root and `/tmp`.\n\n```bash\nfnord ask --project myproj --edit --question \"Add a docstring to foo/thing.ex\"\n```\n\nCode modification by an LLM is *unreliable* and is not safe for unsupervised use.\nThe AI may behave unpredictably.\n\n## Copyright and License\n\nThis software is copyright (c) 2025 by Jeff Ober.\n\nThis is free software; you can redistribute it and/or modify it under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Ffnord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsysread%2Ffnord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Ffnord/lists"}