fegger
b0229b6332
Scans codebases for TODO/FIXME/HACK/XXX comments and generates Markdown notes in an Obsidian vault. Includes Zed editor integration that runs on file save, plus a shell wrapper for CLI usage. Supports customizable vault paths, project names, and output directories.
120 lines
2.7 KiB
Markdown
120 lines
2.7 KiB
Markdown
# todoObsidian
|
||
|
||
Scan a codebase for `TODO`, `FIXME`, `HACK`, and `XXX` comments and create a Markdown note per project inside your Obsidian vault.
|
||
|
||
## Installation
|
||
|
||
No external dependencies (uses the Python 3 standard library).
|
||
|
||
Make the wrapper executable:
|
||
|
||
```bash
|
||
chmod +x todo-to-obsidian.sh
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Basic
|
||
|
||
```bash
|
||
python3 main.py /path/to/your/project
|
||
```
|
||
|
||
### Specify vault path
|
||
|
||
```bash
|
||
python3 main.py /path/to/your/project --vault ~/Obsidian/MyVault
|
||
```
|
||
|
||
### Custom project name
|
||
|
||
```bash
|
||
python3 main.py /path/to/your/project --name "My Awesome App"
|
||
```
|
||
|
||
### Custom output folder inside vault
|
||
|
||
```bash
|
||
python3 main.py /path/to/your/project --output-dir "Project TODOs"
|
||
```
|
||
|
||
### Using the shell wrapper
|
||
|
||
```bash
|
||
./todo-to-obsidian.sh /path/to/your/project
|
||
```
|
||
|
||
### Zed integration (run on file-save)
|
||
|
||
A Zed task is included in `.zed/tasks.json` that automatically scans the workspace and syncs TODOs to Obsidian every time you save a file.
|
||
|
||
1. Open the `obsidianUtils` folder as a workspace in Zed.
|
||
2. Save any file — the task runs in the background.
|
||
3. Check your Obsidian vault under `Todos/TODOs obsidianUtils.md`.
|
||
|
||
If the task does not run automatically on save, you can also trigger it manually via **cmd-shift-p → tasks: run task → "Scan TODOs to Obsidian"** (or bind it to a key in your `keymap.json`).
|
||
|
||
#### Customizing the Zed task
|
||
|
||
You can edit `.zed/tasks.json` to:
|
||
- Change `--output-dir`
|
||
- Set a custom `--name`
|
||
- Add `--vault` if `OBSIDIAN_VAULT` is not set
|
||
|
||
Example with explicit vault:
|
||
```json
|
||
{
|
||
"label": "Scan TODOs to Obsidian",
|
||
"command": "python3",
|
||
"args": [
|
||
"todoObsidian/main.py",
|
||
"{ZED_WORKTREE_ROOT}",
|
||
"--vault",
|
||
"/Users/you/Obsidian/MyVault"
|
||
],
|
||
"tags": ["file-save"],
|
||
"cwd": "{ZED_WORKTREE_ROOT}",
|
||
"reveal": "no",
|
||
"hide": "on_success",
|
||
"allow_concurrent_runs": false
|
||
}
|
||
```
|
||
|
||
## Environment Variables
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `OBSIDIAN_VAULT` | Path to your Obsidian vault (used if `--vault` is omitted) |
|
||
|
||
## Supported File Types
|
||
|
||
- Python, JavaScript, TypeScript, Java, C, C++, Rust, Go, Ruby, Shell, Swift, Kotlin, Scala, R, Lua, PHP, C#, F#, Markdown, YAML, JSON, TOML, INI, and Makefiles/Dockerfiles.
|
||
|
||
## Output Format
|
||
|
||
A note is created under `Todos/` in your vault:
|
||
|
||
```markdown
|
||
# TODOs – ProjectName
|
||
|
||
_Scanning on 2026-05-26 14:30_
|
||
|
||
## Summary
|
||
- **TODO**: 3
|
||
- **FIXME**: 1
|
||
|
||
## By File
|
||
|
||
### `src/main.py`
|
||
- [ ] **TODO** (line 42) – refactor this function
|
||
- [ ] **FIXME** (line 55) – handle edge case
|
||
|
||
### `README.md`
|
||
- [ ] **TODO** (line 10) – add installation instructions
|
||
```
|
||
|
||
## What Gets Skipped
|
||
|
||
- Hidden directories (`.git`, `.vscode`, etc.)
|
||
- Common build / dependency folders (`node_modules`, `venv`, `target`, `build`, etc.)
|