claudetools/.claude/OFFLINE_MODE.md

ClaudeTools - Offline Mode & Sync

Version 2.0 - Offline-Capable Context Recall

---

Overview

ClaudeTools now supports fully offline operation with automatic synchronization when the API becomes available. Contexts are never lost - they're queued locally and uploaded when connectivity is restored.

---

How It Works

Online Mode (Normal Operation)

User Message
    ↓
[user-prompt-submit hook]
    ↓
Fetch context from API → Cache locally → Inject into conversation
    ↓
Claude processes with context
    ↓
Task completes
    ↓
[task-complete hook]
    ↓
Save context to API → Success

Offline Mode (API Unavailable)

User Message
    ↓
[user-prompt-submit hook]
    ↓
API unavailable → Use local cache → Inject cached context
    ↓
Claude processes with cached context
    ↓
Task completes
    ↓
[task-complete hook]
    ↓
API unavailable → Queue locally in .claude/context-queue/pending/

Sync Mode (When API Restored)

Next API interaction
    ↓
Background sync triggered
    ↓
Upload all queued contexts
    ↓
Move to .claude/context-queue/uploaded/

---

Directory Structure

├── context-cache/              # Downloaded contexts for offline reading
│   └── [project-id]/           # Per-project cache
│       ├── latest.json         # Most recent contexts from API
│       └── last_updated        # Cache timestamp
├── context-queue/              # Pending contexts to upload
│   ├── pending/                # Contexts waiting to upload
│   │   ├── [project]_[timestamp]_context.json
│   │   └── [project]_[timestamp]_state.json
│   ├── uploaded/               # Successfully uploaded (auto-cleaned)
│   └── failed/                 # Failed uploads (manual review needed)
└── hooks/
    ├── user-prompt-submit-v2   # Enhanced hook with offline support
    ├── task-complete-v2        # Enhanced hook with queue support
    └── sync-contexts           # Manual/auto sync script

---

Features

1. Context Caching

What:

• API responses are cached locally after each successful fetch
• Cache is stored per-project in .claude/context-cache/[project-id]/

When Used:

• API is unavailable
• Network is down
• Server is being maintained

Benefits:

• Continue working with most recent context
• No interruption to workflow
• Clear indication when using cached data

2. Context Queuing

What:

• Failed context saves are queued locally
• Stored as JSON files in .claude/context-queue/pending/

When Used:

• API POST fails
• Network is down
• Authentication expires

Benefits:

• No context loss
• Automatic retry
• Continues working offline

3. Automatic Sync

What:

• Background process uploads queued contexts
• Triggered on next successful API interaction
• Non-blocking (runs in background)

When Triggered:

• User message processed (user-prompt-submit)
• Task completed (task-complete)
• Manual sync command

Benefits:

• Seamless sync
• No manual intervention
• Transparent to user

---

Usage

Automatic Operation

No action needed - the system handles everything automatically:

1. Working Online:

   • Context recalled from API
   • Context saved to API
   • Everything cached locally

2. API Goes Offline:

   • Context recalled from cache (with warning)
   • Context queued locally
   • Work continues uninterrupted

3. API Restored:

   • Next interaction triggers background sync
   • Queued contexts uploaded
   • Normal operation resumes

Manual Sync

If you want to force a sync:

cd D:\ClaudeTools
bash .claude/hooks/sync-contexts

Check Queue Status

# Count pending contexts
ls .claude/context-queue/pending/*.json | wc -l

# Count uploaded contexts
ls .claude/context-queue/uploaded/*.json | wc -l

# Check failed uploads
ls .claude/context-queue/failed/*.json 2>/dev/null

View Cached Context

# View cached contexts for current project
PROJECT_ID=$(git config --local claude.projectid)
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool

# Check cache age
cat .claude/context-cache/$PROJECT_ID/last_updated

---

Migration from V1 to V2

Step 1: Backup Current Hooks

cd .claude/hooks
cp user-prompt-submit user-prompt-submit.backup
cp task-complete task-complete.backup

Step 2: Replace with V2 Hooks

# Replace hooks with offline-capable versions
mv user-prompt-submit-v2 user-prompt-submit
mv task-complete-v2 task-complete

# Make executable
chmod +x user-prompt-submit task-complete sync-contexts

Step 3: Create Queue Directories

mkdir -p .claude/context-cache
mkdir -p .claude/context-queue/{pending,uploaded,failed}

Step 4: Update .gitignore

Add to .gitignore:

# Context recall local storage
.claude/context-cache/
.claude/context-queue/

Step 5: Test

# Test offline mode by stopping API
ssh guru@172.16.3.30
sudo systemctl stop claudetools-api

# Back on Windows - use Claude Code
# Should see "offline mode" message
# Contexts should queue in .claude/context-queue/pending/

# Restart API
sudo systemctl start claudetools-api

# Next Claude Code interaction should trigger sync

---

Indicators & Messages

Online Mode

<!-- Context Recall: Retrieved 3 relevant context(s) from API -->
## 📚 Previous Context

The following context has been automatically recalled:
...

Offline Mode (Using Cache)

<!-- Context Recall: Retrieved 3 relevant context(s) from LOCAL CACHE (offline mode) -->
## 📚 Previous Context

⚠️ **Offline Mode** - Using cached context (API unavailable)

The following context has been automatically recalled:
...
*Context from local cache - new context will sync when API is available.*

Context Saved (Online)

✓ Context saved to database

Context Queued (Offline)

⚠ Context queued locally (API unavailable) - will sync when online

---

Troubleshooting

Issue: Contexts Not Syncing

Check:

# Verify JWT token is set
source .claude/context-recall-config.env
echo $JWT_TOKEN

# Manually run sync
bash .claude/hooks/sync-contexts

Issue: Cache Too Old

Solution:

# Clear cache to force fresh fetch
PROJECT_ID=$(git config --local claude.projectid)
rm -rf .claude/context-cache/$PROJECT_ID

Issue: Failed Uploads

Check:

# Review failed contexts
ls -la .claude/context-queue/failed/

# View specific failed context
cat .claude/context-queue/failed/[filename].json | python -m json.tool

# Retry manually
bash .claude/hooks/sync-contexts

Issue: Queue Growing Too Large

Solution:

# Check queue size
du -sh .claude/context-queue/

# Clean up old uploaded contexts (keeps last 100)
find .claude/context-queue/uploaded/ -type f -name "*.json" -mtime +7 -delete

# Emergency: Clear all queues (data loss!)
rm -rf .claude/context-queue/{pending,uploaded,failed}/*

---

Performance Considerations

Cache Storage

• Per-project cache: ~10-50 KB per project
• Storage impact: Negligible (< 1 MB total)
• Auto-cleanup: No (caches remain until replaced)

Queue Storage

• Per-context: ~1-2 KB per context
• Growth rate: 1-5 contexts per work session
• Auto-cleanup: Yes (keeps last 100 uploaded)

Sync Performance

• Upload speed: ~0.5 seconds per context
• Background: Non-blocking
• Network impact: Minimal (POST requests only)

---

Security Considerations

Local Storage

• Cache contents: Context summaries (not sensitive)
• Queue contents: Context payloads with metadata
• Access control: File system permissions only

Recommendations

1. Add to .gitignore:

   .claude/context-cache/
   .claude/context-queue/
   

2. Backup exclusions:

   • Exclude .claude/context-cache/ (can be re-downloaded)
   • Include .claude/context-queue/pending/ (unique data)

3. Sensitive projects:

   • Review queued contexts before sync
   • Clear cache when switching machines

---

Advanced Usage

Disable Offline Mode

Keep hooks but disable caching/queuing:

# In .claude/context-recall-config.env
CONTEXT_RECALL_ENABLED=false

Force Online-Only Mode

Prevent local fallback:

# Remove cache and queue directories
rm -rf .claude/context-cache
rm -rf .claude/context-queue

Pre-populate Cache

For offline work, cache contexts before disconnecting:

# Trigger context recall
# (Just start a Claude Code session - context is auto-cached)

Batch Sync Script

Create a cron job or scheduled task:

# Sync every hour
0 * * * * cd /path/to/ClaudeTools && bash .claude/hooks/sync-contexts >> /var/log/context-sync.log 2>&1

---

Comparison: V1 vs V2

Feature	V1 (Original)	V2 (Offline-Capable)
API Recall	✅ Yes	✅ Yes
API Save	✅ Yes	✅ Yes
Offline Recall	❌ Silent fail	✅ Uses local cache
Offline Save	❌ Data loss	✅ Queues locally
Auto-sync	❌ No	✅ Background sync
Manual sync	❌ No	✅ sync-contexts script
Status indicators	❌ Silent	✅ Clear messages
Data resilience	❌ Low	✅ High

---

FAQ

Q: What happens if I'm offline for days? A: All contexts queue locally and sync when online. No data loss.

Q: How old can cached context get? A: Cache is updated on every successful API call. Age is shown in offline mode message.

Q: Can I work on multiple machines offline? A: Yes, but contexts won't sync between machines until both are online.

Q: What if sync fails repeatedly? A: Contexts move to failed/ directory for manual review. Check API connectivity.

Q: Does this slow down Claude Code? A: No - sync runs in background. Cache/queue operations are fast (~milliseconds).

Q: Can I disable caching but keep queuing? A: Not currently - it's all-or-nothing via CONTEXT_RECALL_ENABLED.

---

Support

For issues or questions:

1. Check queue status: ls -la .claude/context-queue/pending/
2. Run manual sync: bash .claude/hooks/sync-contexts
3. Review logs: Check stderr output from hooks
4. Verify API: curl http://172.16.3.30:8001/health

---

Last Updated: 2026-01-17 Version: 2.0 (Offline-Capable)