agentic-codebase-memory-manager/README.md

Snip - Local-First Code Snippet Manager

A powerful CLI tool for managing code snippets with local-first architecture. Store snippets in SQLite with FTS5 full-text search, optional AES encryption, and peer-to-peer sync capabilities.

Features

• CRUD Operations: Create, read, update, delete code snippets with ease
• Full-Text Search: FTS5-powered search across title, description, code, and tags with ranking
• Tag Organization: Flexible tag-based organization with autocomplete
• Collections: Group snippets into named collections for better organization
• Syntax Highlighting: Beautiful terminal syntax highlighting using Pygments
• Import/Export: JSON import/export for backup, sharing, and portability
• Encryption: Optional AES encryption for sensitive snippets using PBKDF2 key derivation
• P2P Sync: Discover and sync snippets with peers on your local network via mDNS

Installation

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/snippet-manager.git
cd snippet-manager
pip install -e .

Dependencies

click>=8.3.0
cryptography>=46.0.0
pygments>=2.19.0
rich>=13.0.0
zeroconf>=0.148.0

Quick Start

# Initialize the database
snip init

# Add a snippet
snip add --title "Hello World" --code 'print("Hello, World!")' --language python

# List all snippets
snip list

# Get a snippet with syntax highlighting
snip get 1

# Search snippets
snip search hello

# Add tags to organize
snip tag add 1 python basics

# Create a collection
snip collection create "Python Snippets"

# Export snippets for backup
snip export all --file backup.json

# Import snippets from backup
snip import --file backup.json --strategy skip

Commands Reference

Snippet Commands

Command	Description
snip init	Initialize the snippet database
snip add	Add a new snippet
snip get <id>	Get a snippet by ID with syntax highlighting
snip list	List all snippets with pagination
snip edit <id>	Edit a snippet in your default editor
snip delete <id>	Delete a snippet (with confirmation)
snip search <query>	Full-text search with FTS5

Tag Commands

Command	Description
snip tag add <snippet_id> <tag>	Add a tag to a snippet
snip tag remove <snippet_id> <tag>	Remove a tag from a snippet
snip tag list	List all tags in use

Collection Commands

Command	Description
snip collection create <name>	Create a new collection
snip collection list	List all collections
snip collection delete <id>	Delete a collection
snip collection add <collection_id> <snippet_id>	Add snippet to collection
snip collection remove <collection_id> <snippet_id>	Remove snippet from collection

Import/Export Commands

Command	Description
snip export all --file <path>	Export all snippets to JSON
snip export collection <name> --file <path>	Export a specific collection
snip export snippet <id> --file <path>	Export a single snippet
snip import --file <path> --strategy <strategy>	Import snippets (strategies: skip, replace, duplicate)

P2P Sync Commands

Command	Description
snip discover list	Discover peers on the local network
snip sync --peer-id <id>	Sync snippets with a discovered peer
snip peers	List known sync peers

Configuration

Environment Variables

Variable	Default	Description
SNIP_DB_PATH	~/.snip/snippets.db	Path to SQLite database
SNIP_KEY_FILE	~/.snip/.key	Path to encryption key file
SNIP_SYNC_PORT	8765	Port for P2P sync
SNIP_PEER_CACHE	~/.snip/peers.json	Path to peer cache

Configuration File

Optional configuration can be placed at ~/.snip/config.toml:

[database]
path = "~/.snip/snippets.db"

[sync]
port = 8765
auto_discover = true

[display]
style = "monokai"
line_numbers = true

Encryption

Snippets can be encrypted using AES encryption with PBKDF2 key derivation (480k iterations, SHA256).

# Add an encrypted snippet
snip add --title "API Secret" --code "API_KEY=abc123" --language python --encrypt

# View encrypted snippet (will prompt for password)
snip get 1

# Encrypted snippets are stored with is_encrypted flag
# Decryption happens on-demand with password verification

How Encryption Works

1. User provides a password when creating an encrypted snippet
2. PBKDF2 derives a 32-byte key using SHA256 (480,000 iterations)
3. Fernet (AES-128-CBC with HMAC) encrypts the snippet content
4. Encrypted data stored in database with is_encrypted=True
5. On retrieval, password decrypts the content in memory

P2P Sync

Snip can discover and sync snippets with other peers on your local network using mDNS/Bonjour service discovery.

Discovery

# Discover available peers on the network
snip discover list

# Output example:
# Peer: macbook-pro.local (192.168.1.100:8765)
# Last seen: 2 minutes ago

Sync Protocol

1. Peer discovery via _snippets._tcp.local. mDNS service
2. HTTP/JSON communication over TCP
3. Sync exchanges snippets updated since last sync
4. Conflict resolution: newest-wins strategy (with option to keep both)

# Sync with a specific peer
snip sync --peer-id <peer_id>

# View known peers
snip peers

Import/Export Format

Exported JSON follows this structure:

{
  "version": "1.0",
  "exported_at": "2024-01-15T10:30:00Z",
  "snippets": [
    {
      "title": "Hello World",
      "description": "A simple Hello World example",
      "code": "print('Hello, World!')",
      "language": "python",
      "tags": ["basics", "example"],
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Import Strategies

• skip: Skip snippets that already exist (by title match)
• replace: Replace existing snippets with same title
• duplicate: Import all as new snippets (generate new IDs)

Shell Completion

Snip supports shell completion for bash and zsh.

Bash

# Add to ~/.bashrc
eval "$(_SNIP_COMPLETE=bash snip)"

Zsh

# Add to ~/.zshrc
eval "$(_SNIP_COMPLETE=zsh snip)"

Troubleshooting

Database Locked

If you see "Database locked" errors:

• Ensure no other snip processes are running
• Check file permissions on ~/.snip/

FTS Query Syntax Error

FTS5 uses special syntax for boolean queries:

• Use quotes for phrases: "hello world"
• Use AND/OR for boolean: hello AND world
• Escape special characters with \

Decryption Failed

• Verify you're using the correct password
• Passwords cannot be recovered if forgotten
• Encrypted snippets without the password cannot be decrypted

Peer Unreachable

• Ensure both peers are on the same network
• Check firewall settings for port 8765
• Verify mDNS/Bonjour is enabled on your system

Development

# Clone repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/snippet-manager.git
cd snippet-manager

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with verbose output
pytest tests/ -v --capture=no

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or submit a pull request.