https://github.com/malewicz1337/locus
A smart command-line history navigator that's directory-aware. Locus logs your shell commands with their corresponding directory, letting you find and re-run them with an easy interactive interface (locus -i). Stop searching your global history and find commands where you actually ran them.
https://github.com/malewicz1337/locus
cli command-history command-line developer-tools directory-history shell shell-history terminal tui zsh
Last synced: 3 months ago
JSON representation
A smart command-line history navigator that's directory-aware. Locus logs your shell commands with their corresponding directory, letting you find and re-run them with an easy interactive interface (locus -i). Stop searching your global history and find commands where you actually ran them.
- Host: GitHub
- URL: https://github.com/malewicz1337/locus
- Owner: malewicz1337
- License: mit
- Created: 2025-09-22T19:52:24.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-22T20:14:06.000Z (9 months ago)
- Last Synced: 2026-01-15T13:37:06.208Z (5 months ago)
- Topics: cli, command-history, command-line, developer-tools, directory-history, shell, shell-history, terminal, tui, zsh
- Language: Rust
- Homepage:
- Size: 16.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Locus
**Your shell history, but organized by directory.**
Locus is a command-line tool that supercharges your shell history. It logs every command you run along with its directory, so you can instantly find and re-execute commands specific to your current project. Stop searching through an endless global history and find what you need, right where you ran it.
---
## Features
* **Directory-Aware History**: Automatically logs commands with the directory they were run in. No more guessing where you ran that `git` or `docker` command.
* **Interactive UI**: Launch a fast, interactive history explorer (`locus -i`) for the current directory. Navigate with arrow keys, see a live preview, and execute with `Enter`.
* **Accurate Logging**: Uses a robust shell hook instead of parsing `.bash_history` or `.zsh_history`, ensuring every command is captured reliably.
* **Simple Setup**: A one-time command (`locus --setup`) generates the necessary hooks for both Bash and Zsh.
* **Powerful Filtering & Stats**: List commands, limit results (`-l`), include subdirectories (`-a`), and even view usage statistics with graphs (`-c`).
---
## Getting Started
### 1. Run the Setup Command
First, run the automatic setup command. This will create the necessary configuration and hook script in `~/.locus/`.
```bash
locus --setup
```
### 2. Update Your Shell Configuration
Next, add the hook to your shell's configuration file so it loads automatically.
```bash
# For Bash:
echo 'source ~/.locus/hook.sh' >> ~/.bashrc
# For Zsh:
echo 'source ~/.locus/hook.sh' >> ~/.zshrc
```
Finally, restart your shell or source the file to apply the changes:
```bash
# For Bash
source ~/.bashrc
# For Zsh
source ~/.zshrc
```
That's it! Locus will now log your commands in the background.
## Usage
Once set up, you can call locus from any directory to see its history.
```bash
locus # List commands in current directory
locus -i # Interactive navigation mode ⭐
locus -c # Show command statistics with graphs
locus -l 10 # Limit to 10 results
locus -a # Include subdirectories
```
### Interactive Mode (locus -i)
This is the core feature of Locus. It provides a clean, minimal UI to browse and re-run commands.
- **Navigate**: Use ↑ and ↓ arrow keys to move through the history.
- **Execute**: Press Enter to run the currently selected command.
- **Exit**: Press q or Ctrl+C to quit.
Try locus --setup first, then locus -i for the interactive experience. 🎉
## Contributing
1. Fork the repository
2. Create a feature branch
4. Submit a pull request
## License
This project is open source and available under the [MIT License](LICENSE).