✓ Stable v1.0.0

📝 shellp

Context-aware developer note-taking CLI tool

shellp encourages better documentation by intelligently detecting significant development commands and prompting you to add contextual notes. It understands git state, file changes, and command patterns to suggest when documentation would be valuable. Notes are automatically categorized, tagged, and searchable.

View on GitHub Download RPM

🎯 RPM Available

Installation

shellp is available for Fedora/RHEL as an RPM package and can be built from source using Go.

Fedora / RHEL 9

# Add the musicsian repository (first time only) sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo # Install shellp sudo dnf install shellp

From Source

# Prerequisites: Go 1.19+ git clone https://github.com/mfwolffe/shellp.git cd shellp go build -o shellp . sudo mv shellp /usr/local/bin/

Shell Integration

After installation, enable shell integration to have shellp automatically detect commands and prompt for notes:

# Add to ~/.bashrc echo 'source ~/.shellp/hook.sh' >> ~/.bashrc source ~/.bashrc # Or run the installer script sudo /usr/share/shellp/install_hooks.sh

Quick Start

# After shell integration, commands prompt for notes $ git commit -m "Add authentication" You just ran: git commit -m "Add authentication" Branch: feature/auth What's the reasoning behind these changes? > Implemented OAuth2 flow with JWT tokens Note saved: Implemented OAuth2 flow... # View your notes $ shellp notes Your recent development notes (3): 2 minutes ago git commit -m "Add authentication" Implemented OAuth2 flow with JWT tokens git | feature, security # Search through notes $ shellp search "authentication" Found 5 notes

Dependencies

Build: Go ≥ 1.19, git
Runtime: Bash or Zsh, git

Configuration File

Configuration is stored in ~/.shellp/config.json:

{ "prefer_editor": false, "editor_timeout_seconds": 300, "enabled_triggers": ["git", "build", "package", "docker"], "disabled_commands": [], "min_priority": 3, "show_context": true, "show_file_count": true, "max_suggestions": 1, "date_format": "2006-01-02 15:04", "default_category": "general", "auto_tags": true, "quiet_mode": false, "debug_mode": false }

Configuration Options

Option	Type	Default	Description
`prefer_editor`	boolean	false	Use $EDITOR for longer notes instead of inline prompt
`editor_timeout_seconds`	integer	300	Max time (seconds) to wait for editor
`enabled_triggers`	array	["git", "build", ...]	Categories that trigger prompts
`disabled_commands`	array	[]	Specific commands to skip
`min_priority`	integer	3	Minimum priority for suggestions (1-10)
`show_context`	boolean	true	Show git branch, file counts in prompts
`show_file_count`	boolean	true	Show modified/staged file counts
`max_suggestions`	integer	1	Limit suggestions per prompt
`date_format`	string	2006-01-02 15:04	Go time format for display
`default_category`	string	general	Default category for notes
`auto_tags`	boolean	true	Auto-generate tags from content
`quiet_mode`	boolean	false	Disable all prompting
`debug_mode`	boolean	false	Enable verbose output

Managing Configuration

# View current settings shellp config show # Set a value shellp config set prefer_editor true shellp config set min_priority 5 shellp config set quiet_mode false # Edit in your editor shellp config edit

Directory Structure

~/.shellp/
├── config.json          # Configuration
├── notes/               # All saved notes (JSON files)
│   ├── <note-id>.json
│   └── ...
└── hook.sh             # Shell integration script

Environment Variables

$EDITOR - Preferred text editor for note editing
$SHELL - Determines shell integration (bash/zsh)
$HOME - Root for .shellp directory

System Overview

shellp is implemented in approximately 5,860 lines of Go code, using the Cobra CLI framework for command structure. The architecture separates concerns into storage, search, rules, and integration layers.

Codebase Statistics

Total: ~5,860 lines of Go
Framework: Cobra CLI
Storage: JSON files in ~/.shellp/notes/
Dependencies: Minimal (Cobra, PFlag, stdlib)

Module Structure

shellp/
├── main.go                    # CLI root command
├── cmd/                       # Command implementations
│   ├── hook.go               # Shell hook processor
│   ├── notes.go              # View notes
│   ├── search.go             # Search & filter
│   ├── manage.go             # Edit/delete notes
│   ├── links.go              # Cross-project linking
│   ├── config.go             # Configuration
│   ├── stats.go              # Statistics
│   ├── share.go              # Export/import
│   └── integrate.go          # External integrations
├── internal/
│   ├── notes/                # Storage & search
│   │   ├── storage.go       # JSON persistence
│   │   └── search.go        # Full-text search
│   ├── git/                  # Git integration
│   ├── context/              # Command analysis
│   ├── config/               # Configuration
│   ├── linking/              # Project linking
│   ├── sharing/              # Export/import
│   ├── integrations/         # Webhooks
│   └── rules/                # Command rules
└── Makefile

Data Flow

Command Execution
    ↓
Shell Hook (DEBUG trap / preexec)
    ↓
shellp hook <command>
    ↓
Context Analysis
├→ Git state (branch, changes)
├→ File change detection
└→ Generate suggestions
    ↓
Rules Engine
├→ Categorize command
└→ Generate initial tags
    ↓
Priority Filter (min_priority)
    ↓
Prompt User
    ↓
Save Note
├→ Auto-categorization
├→ Auto-tagging
├→ Project linking
└→ Write to ~/.shellp/notes/

Note Format

{
  "id": "abc123def456",
  "command": "git commit -m 'feat'",
  "content": "Added user authentication",
  "category": "git",
  "tags": ["feature", "security", "commit"],
  "timestamp": "2025-08-24T21:53:59Z",
  "directory": "/home/user/my-project",
  "project_id": "ff372b667cad",
  "project_name": "my-project",
  "references": [],
  "linked_to": []
}

Core Commands

Option	Type	Default	Description
`shellp notes`	command	-	View recent notes (last 10)
`shellp search [query]`	command	-	Search through notes
`shellp search categories`	command	-	List all note categories
`shellp search tags`	command	-	List all note tags
`shellp manage list`	command	-	List notes for editing
`shellp manage edit <n>`	command	-	Edit note by number
`shellp stats`	command	-	View statistics dashboard
`shellp config show`	command	-	View configuration
`shellp config set <k> <v>`	command	-	Set configuration value
`shellp version`	command	-	Show version info

Search Flags

Option	Type	Default	Description
`--category, -c`	flag	-	Filter by category
`--tag, -t`	flag	-	Filter by tags (repeatable)
`--recent, -r`	flag	-	Time filter (7d, 2w, 24h)
`--directory, -d`	flag	-	Filter by directory path
`--limit, -l`	flag	50	Maximum results
`--sort, -s`	flag	date	Sort by date or relevance

Share Commands

Option	Type	Default	Description
`shellp share export`	command	-	Export notes to JSON bundle
`shellp share import <file>`	command	-	Import notes from bundle
`shellp share report`	command	-	Generate activity report
`shellp share list`	command	-	List bundle files

Links Commands

Option	Type	Default	Description
`shellp links show`	command	-	Show current project info
`shellp links related`	command	-	Find related notes
`shellp links projects`	command	-	List all known projects
`shellp links graph <n>`	command	-	Show relationship graph

Integration Commands

Option	Type	Default	Description
`shellp integrate setup <type>`	command	-	Setup slack/discord/webhook
`shellp integrate test`	command	-	Test connection
`shellp integrate enable`	command	-	Enable notifications
`shellp integrate disable`	command	-	Disable notifications
`shellp integrate status`	command	-	Show integration status

Command Hierarchy

shellp ├── notes # View recent notes ├── search [query] # Search notes │ ├── categories # List categories │ └── tags # List tags ├── manage │ ├── list # List for editing │ ├── edit <n> # Edit note │ └── delete <n> # Delete note ├── links │ ├── show # Current project │ ├── related # Related notes │ ├── projects # All projects │ └── graph <n> # Relationship graph ├── config │ ├── show # View settings │ ├── set <k> <v> # Change setting │ └── edit # Edit in editor ├── stats # Statistics ├── share │ ├── export # Export notes │ ├── import <file> # Import bundle │ ├── report # Generate report │ └── list # List bundles ├── integrate │ ├── setup <type> # Configure │ ├── test # Test connection │ ├── enable/disable # Toggle │ └── status # Show status └── version # Show version

📝 shellp

Installation

Fedora / RHEL 9

From Source

Shell Integration

Quick Start

Dependencies

Configuration File

Configuration Options

Managing Configuration

Directory Structure

Environment Variables

Overview

Key Features

Core Commands

View Notes

Search

Manage Notes

Context-Aware Prompting

Cross-Project Linking

Team Sharing

External Integrations

System Overview

Codebase Statistics

Module Structure

Storage Layer

Search Engine

Rules Engine

Data Flow

Note Format

Core Commands

Search Flags

Share Commands

Links Commands

Integration Commands

Command Hierarchy

Common Issues

Hook not triggering

Error accessing notes

Editor doesn't open

Git context not detected

Performance

Data Backup

Debugging