# Cheshmak

## Why using this tool

I built cheshmak because every time I `cd` into a project I end up running the same few commands to get my bearings. This tool hooks into `cd` and prints a small, readable summary so you can see the state of a project immediately.

It is intentionally lightweight and fast. The summary is meant to be useful without slowing down your shell.

I do use Starship, but I’m not fond of stuffing the prompt with too much. I want my prompt to stay clean. I also don’t need this info on *every* command, but I do want more context than a tiny prompt segment can provide. Cheshmak hits that middle ground by showing a richer snapshot only the first time I enter a project in a shell session.

![cheshmak](https://github.com/user-attachments/assets/b6f37bc9-afde-4764-b870-9a4d0f53ed80)

## How to install it

1. Visit the GitHub **Releases** page for Cheshmak.
2. Download the latest binary that matches your platform.
3. Make the binary executable and place it somewhere on your `PATH`.

```bash
chmod +x cheshmak
mv cheshmak ~/.local/bin/cheshmak
```

Ensure that `~/.local/bin` (or whichever directory you chose) is part of your `PATH`.

## Shell integration (hook)

To run Cheshmak automatically on directory change, add the shell hook:

```bash
cheshmak hook
```

This command adds a small hook to your shell rc file so `cd` prints a summary. The hook itself is intentionally minimal; the binary decides whether to render on each `cd`.

### Uninstall the hook

```bash
cheshmak unhook
```

This removes the hook from your rc file.

### Shell compatibility

- **bash**: edits `~/.bashrc`
- **zsh**: edits `~/.zshrc`
- **fish**: edits `~/.config/fish/config.fish`
- **nushell**: edits `~/.config/nushell/config.nu`

## How to use it

Once installed and hooked into your shell, Cheshmak triggers every time you `cd` into a repository. When you enter a project directory, cheshmak can show things like:

- git branch and status
- rust dependency health (if enabled)
- project identity hints
- recent activity

This gives you a quick readout of the things you typically check when opening a project. Use the plugin list in your config file to control which data points appear and how often each plugin refreshes.

## How to config it

Cheshmak loads configuration from `~/.config/cheshmak/config.toml`.

Only the plugins listed in `enabled_plugins` will execute. If the list is empty, none of the plugins run.

```toml
enabled_plugins = ["git", "todo", "project", "hints", "activity"]

# optional tuning
show_table = false
once_per_shell_session = true
hints_max_len = 48
activity_format = "relative"
```

Use this file to enable or disable plugins and to provide tuning options for individual plugins.

Setting `show_table = true` renders the summary as columnar tables with plugin names as headers, wrapping and splitting tables when they exceed the terminal width, similar to nushell's `ls` output.

Setting `once_per_shell_session = false` forces the summary to rerun every time you change directories; keep it `true` (the default) to show each project only once per shell session.


## Plugin Guide

If you want to add or customize plugins, refer to the [Plugin Guide](docs/PLUGIN_GUIDE.md).

## Notes

- If something feels slow, remove that plugin from `enabled_plugins`.
- Some plugins cache results and can be refreshed with flags like `--refresh-rust-upgrades`.