szoloth/ambient-context

Ambient Context System

A clawdis-inspired system for machine awareness and automatic context injection between Claude Code sessions.

Purpose

This skill manages the ambient context system that:

1. Queues events from various sources (filesystem, git, CI, calendar, manual)
2. Automatically injects context at session start
3. Provides visibility into what happened while you were away

When This Skill Is Invoked

• User asks about events or what happened
• User wants to add context for future sessions
• User needs to check/manage the filesystem watcher
• User wants to integrate external event sources
• Troubleshooting ambient system issues

Commands

Add Events

# Manual event
~/.claude/bin/claude-event "message" --source NAME --priority LEVEL

# External event (simplified)
~/.claude/bin/claude-external-event SOURCE "message"

# Examples
~/.claude/bin/claude-event "Completed auth refactor" --source dev --priority normal
~/.claude/bin/claude-external-event ci "Build passed for dwa-prototypes"
~/.claude/bin/claude-external-event calendar "Meeting with Sarah in 15 minutes"

Check Pending Events

# List pending events (without draining)
ls -la ~/.claude/events/*.event 2>/dev/null | wc -l

# Preview event content
for f in ~/.claude/events/*.event; do
  [ -f "$f" ] && jq -r '"\(.priority | ascii_upcase): [\(.source)] \(.message)"' "$f"
done 2>/dev/null

Watcher Management

# Status
launchctl list | grep claude.ambient

# Logs
tail -20 /tmp/claude-watcher.log

# Restart
launchctl unload ~/Library/LaunchAgents/com.claude.ambient-watcher.plist
launchctl load ~/Library/LaunchAgents/com.claude.ambient-watcher.plist

# Stop
launchctl unload ~/Library/LaunchAgents/com.claude.ambient-watcher.plist

Git Hook Installation

# Install in current repo
ln -sf ~/.claude/bin/claude-git-hook .git/hooks/post-commit

# Install in specific repo
ln -sf ~/.claude/bin/claude-git-hook /path/to/repo/.git/hooks/post-commit

Event Priorities

urgent - Meetings, critical failures, blockers → Shows with "!" prefix, always displayed normal - Commits, deploys, significant changes → Shows with "-" prefix, always displayed low - Minor code edits, routine changes → Shows with "-" prefix, filtered if >5 events

File Locations

~/.claude/
├── events/              # Event queue (ephemeral, auto-cleaned)
│   └── *.event          # JSON event files
├── bin/
│   ├── claude-event     # Core event CLI
│   ├── claude-external-event
│   └── claude-git-hook
├── watchers/
│   └── project-watcher.sh
├── hooks/
│   ├── session-start-hook.sh  # Drains events
│   └── drain-events.sh
└── ambient/
    └── README.md        # Full documentation

~/Library/LaunchAgents/
└── com.claude.ambient-watcher.plist

Watched Directories

The filesystem watcher monitors these directories (edit ~/.claude/watchers/project-watcher.sh to change):

• ~/dwa-prototypes
• ~/prototype-01
• ~/training-app
• ~/clawdis

Add a New Watch Directory

# Edit the watcher script
vim ~/.claude/watchers/project-watcher.sh

# Add to WATCH_DIRS array:
# WATCH_DIRS=(
#     "$HOME/dwa-prototypes"
#     "$HOME/your-new-project"  # Add here
# )

# Restart watcher
launchctl unload ~/Library/LaunchAgents/com.claude.ambient-watcher.plist
launchctl load ~/Library/LaunchAgents/com.claude.ambient-watcher.plist

Integration Examples

From launchd Jobs

Add to existing scripts like ~/clawd/scripts/morning.sh:

# At end of script
~/.claude/bin/claude-external-event morning "Morning briefing completed"

From CI/CD Webhooks

# In webhook handler
~/.claude/bin/claude-external-event ci "Deploy v1.2.3 to production succeeded"

From Apple Shortcuts

Create a Shortcut with "Run Shell Script":

~/.claude/bin/claude-external-event calendar "Meeting starting: [Meeting Name]"

From Cron/launchd

# Email check (every 30 min)
~/.claude/bin/claude-external-event email "$(mail -H | wc -l) new emails"

Troubleshooting

Events Not Appearing at Session Start

1. Check events exist:

   ls ~/.claude/events/*.event 2>/dev/null
   

2. Test drain manually:

   ~/.claude/hooks/drain-events.sh
   

3. Verify hook is in session-start:

   grep drain-events ~/.claude/hooks/session-start-hook.sh
   

Watcher Not Running

1. Check launchd status:

   launchctl list | grep claude.ambient
   # Should show PID and exit code 0
   

2. Check for errors:

   cat /tmp/claude-watcher-error.log
   

3. Verify fswatch installed:

   which fswatch
   

4. Check watch directories exist:

   for d in ~/dwa-prototypes ~/prototype-01 ~/training-app ~/clawdis; do
     [ -d "$d" ] && echo "✓ $d" || echo "✗ $d (missing)"
   done
   

Events Expiring Too Fast

Default TTL is 4 hours. To change, edit ~/.claude/bin/claude-event:

TTL_HOURS=4  # Change to desired hours

Architecture (clawdis-inspired)

EVENT SOURCES              QUEUE                    DRAIN
─────────────────────────────────────────────────────────────
fswatch ─┐
git     ─┼──▶ claude-event ──▶ ~/.claude/events/ ──▶ session-start
CI/CD   ─┤                     (ephemeral)            │
calendar─┤                     TTL: 4 hours           ▼
manual  ─┘                     Max: 20             Claude sees
                                                   context

Key principles from clawdis system-events:

• Ephemeral: Events don't persist forever (4-hour TTL)
• Debounced: Duplicate consecutive events collapsed
• Priority-based: Important events surface first
• Auto-drain: Events consumed at session start