# PSWatch 

pswatch is a minimalist process monitoring and task scheduler that allows you to
watch system processes and run custom commands when specific conditions or
patterns are matched. It also implements the `notify` signal with systemd.

**Features**
- match running processes by pattern in: name, exe path or the entire command line.
- Define multiple conditions and actions. 
- Execute actions when conditions are met on the matched processes.

## Installation

To install pswatch, clone the repository from GitHub and build it using
Cargo:

```sh
git clone https://github.com/your-username/pswatch.git
cd pswatch
cargo build --release
```

The binary will be located in `target/release/pswatch`.

## Usage

Pswatch requires a `TOML` based configuration file. By default it uses the
config file under $XDG_CONFIG_DIR/pswatch/config.toml or the one provided as
parameter.

```sh
./pswatch -c /path/to/config.toml
```

The program will watch system processes and execute commands based on the
patterns defined in the configuration file.

## Configuration File

pswatch's behavior is configured using a TOML-formatted configuration file.
The file should contain a list of `watches`, each containing a `pattern` (the
process name to match), a `regex` flag (set to `true` if the pattern is a
regular expression), and a list of `commands`.

Each command contains a condition (either `seen` or `not_seen` with a duration)
and an array of shell commands (`exec`) to execute when the condition is met. An
optional `run_once` flag can be set to run the command only once per process
detection.

Here's an example configuration file:

```toml
[[watches]]
pattern = "foo"
regex = false

[[watches.commands]]
condition = {seen = "5s"}
exec = ["sh", "-c", "notify-end action!"]
# run_once = false # uncomment to run the command only once per process
detection
```

## Examples with Multiple Watches

You can use multiple watches within a single configuration file to monitor
different processes and execute commands based on their patterns. Here's an
example configuration that uses two watches:

```toml
[[watches]]
pattern = "bar"
regex = false

[[watches.commands]]
condition = {not_seen = "5s"}
exec = ["sh", "-c", "echo not seen!"]

[[watches]]
pattern = "baz"
regex = true

[[watches.commands]]
condition = {seen = "10s"}
exec = ["sh", "-c", "say 'baz detected!'"]
run_once = true # run the command only once per process detection
```

In this example, pswatch will watch for two processes: "bar" and "baz". When
"bar" is not seen for 5 seconds, it will execute `echo not seen!`. When "baz" (a
regular expression) is detected, it will execute `say 'baz detected!'` after a
delay of 10 seconds. The command for "baz" will be run only once per process
detection.

## Example Scenarios

1. **Execute a command when a specific process is seen for a certain duration**
   - Define a watch with the desired process name and use `{seen = "duration"}` to specify that the command should be executed when the process has been running for a specified duration (e.g., "5s").

2. **Execute a command when a specific process is not seen for a certain duration**
   - Define a watch with the desired process name and use `{not_seen = "duration"}` to specify that the command should be executed when the process has been absent for a specified duration (e.g., "5s").

3. **Execute multiple commands based on different conditions**
   - Define multiple watch configurations in the same TOML file and specify separate `condition` and `exec` settings for each. pswatch will monitor all configured watches and execute their respective commands when appropriate.

## Troubleshooting

If you encounter any issues while using pswatch, please refer to the
[TROUBLESHOOTING.md](TROUBLESHOOTING.md) file in this repository for
troubleshooting tips and solutions.

## Contributing

Contributions are welcome! If you'd like to contribute to pswatch, please
follow these steps:

1. Fork the repository on GitHub.
2. Clone your fork to your local machine: `git clone
   https://github.com/your-username/pswatch.git`.
   3. Create a new branch for your changes: `git checkout -b my-feature`.
   4. Make your changes and commit them with descriptive messages: `git commit
      -am 'Add some feature'`.
      5. Push your branch to your GitHub fork: `git push origin my-feature`.
      6. Submit a pull request from your GitHub fork to the main repository.

## License

pswatch is licensed under the AGPLv3 License. See [LICENSE](LICENSE) for more
details.