svenflow/contacts

Contacts Management Skill

This skill manages contacts using the native macOS Contacts.app. Tiers are implemented using Contact Groups.

CLI Location

~/.claude/skills/contacts/scripts/contacts

Architecture

Tier System via Contact Groups (priority order):

• Claude Admin - Full access users who can control the main Claude session
• Claude Partner - Special tier for partner with elevated privileges
• Claude Family - Family members with read access, mutations need admin approval
• Claude Favorites - Priority users with a dedicated locked-down Claude
• No group = Unknown/ignored (messages from contacts not in any group are ignored)

Data Storage:

• All contact data lives in macOS Contacts.app
• Tiers are determined by group membership
• Phone numbers are the primary identifier for incoming messages

Quick Reference

| Subcommand | Accepts | Description | |------------|---------|-------------| | list | --tier <tier> (optional) | List all contacts, optionally filtered by tier | | lookup | Phone number or email | Look up contact by phone/email | | add | First, Last, Phone, --tier | Add a new contact | | tier | "First Last", tier (optional) | Get or set contact tier | | notes | "First Last", notes (optional) | Get or set contact notes |

Search by name: The CLI doesn't have a name search subcommand. Use:

~/.claude/skills/contacts/scripts/contacts list | grep -i "name"

Commands

List All Contacts

# All contacts with tiers
~/.claude/skills/contacts/scripts/contacts list

# Filter by tier
~/.claude/skills/contacts/scripts/contacts list --tier family
~/.claude/skills/contacts/scripts/contacts list --tier admin

Lookup Contact by Phone Number or Email

~/.claude/skills/contacts/scripts/contacts lookup +16175551234
~/.claude/skills/contacts/scripts/contacts lookup [email protected]

Returns: Name | Phone | Tier

Note: lookup only accepts phone numbers or emails, NOT names. To find by name, use list | grep -i "name".

Add New Contact

# With tier
~/.claude/skills/contacts/scripts/contacts add "First" "Last" "+16175551234" --tier family

# Without tier (will be ignored by system)
~/.claude/skills/contacts/scripts/contacts add "First" "Last" "+16175551234"

Valid tiers: admin, partner, family, favorite

Get/Set Contact Tier

# Get current tier
~/.claude/skills/contacts/scripts/contacts tier "First Last"

# Set new tier
~/.claude/skills/contacts/scripts/contacts tier "First Last" family

# Remove from all tiers (contact will be ignored)
~/.claude/skills/contacts/scripts/contacts tier "First Last" none

Get/Set Contact Notes

# Get notes
~/.claude/skills/contacts/scripts/contacts notes "First Last"

# Set notes
~/.claude/skills/contacts/scripts/contacts notes "First Last" "Prefers morning texts. Works at Google."

Notes are useful for remembering preferences, context, etc.

Important Notes

• Phone numbers should include country code (e.g., +1 for US)
• The Messages.app chat.db uses phone numbers as identifiers
• When a message comes in, lookup the phone number to determine tier and routing

Technical Details

Hybrid read/write path:

• Reads: SQLite queries against AddressBook-v22.abcddb (fast, no Contacts.app dependency)
• Writes: AppleScript via Contacts.app (required by macOS for mutations)

Multi-source database architecture: macOS stores contacts across multiple SQLite databases when iCloud is enabled:

• ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb (root, may be stale)
• ~/Library/Application Support/AddressBook/Sources/<UUID>/AddressBook-v22.abcddb (per-source)

The same contact can exist in multiple source DBs with different data. AppleScript writes go to the active iCloud source (most recently modified). SQLite reads query all sources, sorted by modification time (newest first), so "first match wins" returns the most recent version.

If notes appear to not persist, it may be an iCloud sync issue - check all source DBs manually.