Metadata-Version: 2.4
Name: vath-observer
Version: 0.1.6
Summary: A quiet file observer that batches filesystem activity into AI-ready context.
Author: Vath Observer
License: GPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=4.0.0
Requires-Dist: questionary>=2.0.1
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyperclip>=1.8.2
Dynamic: license-file

# Vath-Looker

Vath Observer watches a project folder, records short notes, and writes compact change summaries into files beside the project.

## Commands

- `vath init` configures the observer and can install shell aliases.
- `vath start` launches the observer in a detached background process.
- `vath stop` stops the observer.
- `vath note "refactoring the database connection"` records a short note in `vath_journal.txt`.
- `vath context --last 10m` builds a Markdown context bundle and copies it to the clipboard when possible.
- `vath structure --style visual` prints the project tree.
- `vath publish` runs a git preset from `git_config.json`.
- `vath status` shows whether the observer is running and which folder it is watching.
- `vath --debug` reveals the hidden debug note.

## Project files

The observer keeps its main files beside the folder you are observing:

- `D:\Vath\.vath\vath_config.json`
- `D:\Vath\.vath\vath_journal.txt`
- `D:\Vath\.vath\vath_state.json`
- `D:\Vath\.vath\git_config.json`
- `D:\Vath\.vath\vath.pid`

The config stores the project root and setup preferences. The journal stores concise human-readable summaries plus structured details for each batch. The state file stores low-CPU tracking data for the hybrid watcher. The git config stores optional batch command presets.

## Watcher behavior

When a file changes:

1. The event is staged in memory.
2. The debounce timer resets to 3 seconds.
3. If more events arrive before the timer expires, the staging window stays open.
4. Once the tree is quiet for 3 seconds, the staged batch is flushed to `vath_journal.txt`.

That keeps rapid save bursts from flooding the log.

## Install

```bash
pip install .
```

## Quick start

```bash
vath init
vath start
vath note "refactoring database connection"
vath context --last 10m
vath structure --style directory
vath publish
```

## Notes

- Clipboard support is best-effort. If it cannot access the clipboard, the context bundle is still printed to the terminal.
- Shell aliases are opt-in and can be written for PowerShell, Bash, or Zsh.
- Git presets are opt-in and stored in `git_config.json`.

