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/.

locus --setup

2. Update Your Shell Configuration

Next, add the hook to your shell's configuration file so it loads automatically.

# 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:

# 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.

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
3. Submit a pull request

License

This project is open source and available under the MIT License.