https://github.com/crypdick/obsidian-llm
https://github.com/crypdick/obsidian-llm
Last synced: 11 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/crypdick/obsidian-llm
- Owner: crypdick
- License: mit
- Created: 2024-03-29T17:16:08.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-01T08:35:15.000Z (11 months ago)
- Last Synced: 2025-08-01T10:42:40.125Z (11 months ago)
- Language: Python
- Size: 1.85 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Obsidian Llm
[][pypi_]
[][status]
[][python version]
[][license]
[][read the docs]
[][tests]
[][codecov]
[][pre-commit]
[][black]
[pypi_]: https://pypi.org/project/obsidian-llm/
[status]: https://pypi.org/project/obsidian-llm/
[python version]: https://pypi.org/project/obsidian-llm
[read the docs]: https://obsidian-llm.readthedocs.io/
[tests]: https://github.com/crypdick/obsidian-llm/actions?workflow=Tests
[codecov]: https://app.codecov.io/gh/crypdick/obsidian-llm
[pre-commit]: https://github.com/pre-commit/pre-commit
[black]: https://github.com/psf/black
# Obsidian.md Vault Improvement Assistant
This project aims to automate maintenance of an Obsidian.md vault created from Bryan Jenk's template.
## Features
- **Filling Missing Aliases**: suggests missing aliases within the YAML frontmatter
- **Suggesting Missing Links**: recommends which parts of a note should be turned into wikilinks
- **Merging SyncThing Conflicts**: resolves conflicts in the `.md` files generated by Syncthing
- **Bumping Note Status**: scans all notes currently tagged as stubs (`đ/đĨī¸`) and decide whether to bump its status. In particular, we count the number of links in the body of the note and suggest a status based on that. Note status are as follows:
- `đ/đĨī¸`: _Stub_. 0 links.
- `đ/đ§ī¸`: _Processing_. 1-4 links.
- `đ/đŠī¸`: _Evergreen_. 5+ links.
- **Bumping Journal Status**: scans all journal notes tagged as incomplete (`đ/đĨī¸`) and decides whether to bump its status. In particular, we use ChatGPT to decide whether there are any action items in the journal. If there are, it will prompt the user to capture them into a task manager (manual step). When the user indicates they have finished capturing the tasks, the job continues. If ChatGPT finds no action items, the journal status is bumped without user interaction.
- `đ/đ¨`: _Captured_. The note contained action items, and the user has finished capturing them into a task manager.
- `đ/đŠī¸`: _Processed_. The note contained no action items, and does not need to be processed further.
All edits are presented to the user in a `meld` diff editor, allowing for interactive approval or modification of suggestions.
## Getting Started
### Requirements
- Python 3.11
- Installation of required packages from `poetry.lock` file
### Quickstart
1. Clone the repository to your local machine.
2. Install dependencies using `poetry install`.
3. (Optional) Create a `.env` file in the root directory using `sample.env` as a template.
4. Run `poetry run obsidian-llm --task ` to start the application. Task types include:
- `aliases`: suggest missing aliases within the YAML frontmatter
- `bump-note-status`: suggest bumping of a note's status based on number of wikilinks
- `bump-journal-status`: suggest bumping of a journal's status based on whether it contains action items
- `spell-check-titles`: spell check all note titles
- `linkify`: suggests missing wikilinks in the body of each note
- `merge-syncthing-conflicts`: resolves conflicts in the `.md` files generated by Syncthing
- `fix-file-names`: removes special characters from filenames that cause sync issues to other operating systems
## Usage
When running the steps, it is recommended to close Obsidian to prevent conflicts with the vault. This can happen
if the vault is open and Obsidian is updating the `modified` timestamp of the files.
The exception is when running the `spell-check-titles` task, as this does not modify the files. Files should be renamed manually in Obsidian so that it propagates the updates to wikilinks.
## Recommended workflow
1. Merge Syncthing file conflicts: `poetry run obsidian-llm --task merge-syncthing-conflicts`
2. Bump journal status: `poetry run obsidian-llm --task bump-journal-status`
3. Correct title spelling errors, or else future LLM calls may hallucinate the correct spellings: `poetry run obsidian-llm --task spell-check-titles`
4. Adding aliases helps with later linking steps: `poetry run obsidian-llm --task aliases`
5. Linkify now that aliases are added and titles are corrected: `poetry run obsidian-llm --task linkify`
6. Bump note status now that links are added: `poetry run obsidian-llm --task bump-note-status`
Please see the [Command-line Reference] for details.
## Contributing
Contributions are very welcome.
To learn more, see the [Contributor Guide].
## License
Distributed under the terms of the [MIT license][license],
_Obsidian Llm_ is free and open source software.
## Issues
If you encounter any problems,
please [file an issue] along with a detailed description.
## TODO
- help link to relevant pages using RAG
- add @beartype to all functions and add type hints
- consolidate all prompts into prompts/ folder
- suggest notes which should be merged based on title
- suggest notes which should be split based on length
## Credits
This project was generated from [@cjolowicz]'s [Hypermodern Python Cookiecutter] template.
[@cjolowicz]: https://github.com/cjolowicz
[pypi]: https://pypi.org/
[hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
[file an issue]: https://github.com/crypdick/obsidian-llm/issues
[pip]: https://pip.pypa.io/
[license]: https://github.com/crypdick/obsidian-llm/blob/main/LICENSE
[contributor guide]: https://github.com/crypdick/obsidian-llm/blob/main/CONTRIBUTING.md
[command-line reference]: https://obsidian-llm.readthedocs.io/en/latest/usage.html