🐕 Shelldog - Your Faithful Command Companion

https://pypi.org/project/shelldog/

Your loyal companion for tracking shell commands - because every good developer needs a faithful friend who remembers everything!

    /\_/\  
   ( o.o ) 
    > ^ <   "Woof! I'm watching... silently." --0.1.0--

Shelldog is a silent, intelligent command tracker for your terminal. Think of it as your development diary that writes itself - tracking every command you run, so you never have to remember "what did I do yesterday?" ever again!

🎯 Why Shelldog?

Ever found yourself thinking:

• "What was that curl command I ran last week?"
• "How did I set up this environment again?"
• "I need to write documentation... if only I could remember what I did!"
• "What commands did I run before that bug appeared?"

Shelldog sits quietly in the background and remembers EVERYTHING for you! 🧠

✨ Features

• 🤫 Silent Tracking - Works invisibly without cluttering your terminal
• 🔒 Privacy First - Automatically masks passwords, tokens, and API keys
• 🎯 Smart Detection - Knows when you're in a virtual environment
• 📁 Project-Level Logs - Each venv gets its own history file at the project root
• 🎭 Personality - Because who says CLI tools have to be boring?
• 🚀 Zero Performance Impact - Logs asynchronously in the background
• 🌈 Both Bash & Zsh - Works with your favorite shell

📦 Installation

Quick Install

pip install shelldog

From Source

git clone https://github.com/Ansumanbhujabal/shelldog.git
cd shelldog
pip install -e .

🚀 Quick Start

1. Start Tracking

# Wake up the dog!
shelldog follow

# Activate tracking in your current shell
eval "$(shelldog follow -q)"

That's it! Shelldog is now silently logging all your commands. 🎉

2. View Your History

# See everything
shelldog log

# Just today's commands
shelldog log --today

# Last 20 commands
shelldog log -n 20

3. Check Status

shelldog status

🎮 Commands

Core Commands

Command	Description
shelldog follow	Start tracking commands (activates the good boy!)
shelldog stop	Stop tracking (sends doggo to sleep)
shelldog log	View command history
shelldog status	Check if Shelldog is watching
shelldog clear	Clear command history
shelldog stats	See cool statistics about your commands

Fun Commands (Because Why Not?)

Command	Description
shelldog bark	Make Shelldog bark! 🐕
shelldog treat	Give Shelldog a treat! 🦴
shelldog goodboy	Tell Shelldog he's a good boy! 🏆

🔧 How It Works

The Magic Behind the Scenes

1. Shell Hook: Shelldog installs a tiny hook in your shell (via DEBUG trap in Bash or preexec in Zsh)
2. Silent Logger: Every command gets logged asynchronously - zero impact on your workflow
3. Smart Masking: Sensitive data (passwords, tokens, API keys) are automatically masked
4. Venv Detection: Automatically detects if you're in a virtual environment

Virtual Environment Awareness

When you're in a virtual environment:

• Shelldog creates shelldog_history.txt at your project root (next to your venv folder)
• Each project gets its own command history
• No more mixing up commands from different projects!

my-project/
├── venv/
│   └── .shelldog/          # Hidden config folder
├── shelldog_history.txt     # Your project's command history! 📝
├── src/
└── README.md

Privacy & Security

Shelldog automatically masks sensitive information:

# What you type:
export API_KEY=super_secret_key_123

# What gets logged:
export API_KEY=****

Protected patterns:

• export VARNAME=value → export VARNAME=****
• --password, --token, --api-key, --secret
• Authorization headers in curl commands
• And more!

💡 Usage Examples

Example 1: Track Your Development Session

# Start your day
cd my-project
source venv/bin/activate
eval "$(shelldog follow -q)"

# Do your work
git pull origin main
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

# Later, review what you did
shelldog log --today

Example 2: Debug Like a Pro

# Something broke! What did you do?
shelldog log -n 50

# Find that specific command
shelldog log | grep docker

# See statistics
shelldog stats

Example 3: Document Your Setup

# After setting up a new environment
shelldog log > SETUP.md

# Now you have automatic documentation! 📚

🎨 Example Output

Starting Shelldog

$ shelldog follow

🐕 Woof! I'm watching you.

    Never forget what you did.
    Always know where you've been.
    I've got your back.

✓ Shelldog is now following your commands!

📝 Commands will be logged to:
   /path/to/project/shelldog_history.txt
   🎯 Project root level logging!

🎉 Stay pawsitive! 🐾
============================================================

✓ Initialization complete!
============================================================

🐕 Activate the hook by running:
   eval "$(shelldog follow -q)"

Viewing History

$ shelldog log -n 5

🐕 Shelldog History:

================================================================================
[2025-10-08 14:23:45] pip install requests
[2025-10-08 14:24:12] python app.py
[2025-10-08 14:25:33] git add .
[2025-10-08 14:25:40] git commit -m "Add new feature"
[2025-10-08 14:25:55] git push origin main
================================================================================

📊 Total entries: 5
🐕 *proud tail wag* I remembered everything!

Status Check

$ shelldog status

🐕 Shelldog Status:

==================================================
Tracking enabled:    ✓ Yes
Shell hook active:   ✓ Yes
Virtual env:         ✓ Yes (venv-specific logging)
Venv path:           /opt/CodeRepo/SideProjects/shelldog/venv
Log file:            /opt/CodeRepo/SideProjects/shelldog/shelldog_history.txt
Log file exists:     ✓ Yes
Logged commands:     247
==================================================

✓ Shelldog is actively tracking your commands! 🐕
   Every great developer was once a beginner! 🌟

⚙️ Configuration

Log File Locations

• In a venv: <project_root>/shelldog_history.txt
• Global: ~/.shelldog/shelldog_history.txt

State Files

Shelldog keeps its configuration in:

• In a venv: <venv>/.shelldog/
• Global: ~/.shelldog/

🤝 Shell Integration

Manual Activation

If you want to manually control when Shelldog watches:

# Start tracking
source ~/.shelldog/shelldog_hook.sh

# Stop tracking
source ~/.shelldog/shelldog_unhook.sh

Add to Shell Profile (Optional)

Want Shelldog to start automatically? Add to your ~/.bashrc or ~/.zshrc:

# Auto-start Shelldog in virtual environments
if [[ -n "$VIRTUAL_ENV" ]]; then
    eval "$(shelldog follow -q)" 2>/dev/null
fi

🐛 Troubleshooting

"Shelldog is enabled but not logging!"

Make sure the hook is active:

shelldog status

# If hook is not active, run:
eval "$(shelldog follow -q)"

"Commands are logged twice!"

This can happen if you source the hook multiple times. Run:

shelldog stop
eval "$(shelldog follow -q)"

"Shelldog logs its own commands!"

It shouldn't! Shelldog filters itself out. If you see this, please file a bug report! 🐛

📝 What Gets Logged?

✅ Logged

• All shell commands
• Script executions
• Git commands
• Package installations
• Database migrations
• Server starts/stops
• Basically everything you type!

❌ Not Logged

• shelldog commands themselves
• Internal shell functions
• Empty commands
• Shell initialization stuff

🎓 Pro Tips

1. Review Daily: shelldog log --today at the end of the day
2. Document Projects: shelldog log > COMMANDS.md for documentation
3. Debug Sessions: shelldog log -n 50 to see recent commands
4. Find Patterns: shelldog stats to see your most-used commands
5. Clean Slate: shelldog clear when starting fresh

🤔 FAQ

Q: Does Shelldog slow down my terminal?
A: Nope! Logging happens asynchronously in the background. Zero performance impact.

Q: Is my sensitive data safe?
A: Yes! Shelldog automatically masks passwords, tokens, and API keys.

Q: Can I use this in production?
A: Shelldog is designed for development environments. Use caution in production!

Q: Does it work with tmux/screen?
A: Yes! Each session tracks independently.

Q: What shells are supported?
A: Bash and Zsh are fully supported.

🎨 Why the Dog Theme?

Because:

1. Dogs are loyal (like your command history should be)
2. Dogs remember everything (especially treats)
3. Dogs are always happy to help
4. CLI tools deserve more personality! 🎉

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests
• 🎨 Improve documentation

🙏 Acknowledgments

Built with ❤️ by developers who got tired of asking "wait, what command did I just run?"

---

Made with 🐕 and ☕ by Ansuman Bhujabala

If Shelldog helps you, give him a treat! ⭐ this repo

🐕 *tail wagging intensifies*