claudetools/.claude/commands/sync.md

/sync - Bidirectional ClaudeTools Sync

Synchronize ClaudeTools configuration, session data, and context bidirectionally with Gitea. Ensures all machines stay perfectly in sync for seamless cross-machine workflow.

---

IMPORTANT: Use Automated Sync Script

CRITICAL: When user invokes /sync, execute the automated sync script instead of manual steps.

Windows:

bash .claude/scripts/sync.sh

OR

.claude\scripts\sync.bat

Mac/Linux:

bash .claude/scripts/sync.sh

Why use the script:

• Ensures PULL happens BEFORE PUSH (prevents missing remote changes)
• Consistent behavior across all machines
• Proper error handling and conflict detection
• Automated timestamping and machine identification
• No steps can be accidentally skipped

The script automatically:

1. Checks for local changes
2. Commits local changes (if any)
3. Fetches and pulls remote changes FIRST
4. Pushes local changes
5. Reports sync status

---

What Gets Synced

FROM Local TO Gitea (PUSH):

• Session logs: session-logs/*.md
• Project session logs: projects/*/session-logs/*.md
• Credentials: credentials.md (private repo - safe to sync)
• Project state: SESSION_STATE.md
• Commands: .claude/commands/*.md
• Directives: directives.md
• File placement guide: .claude/FILE_PLACEMENT_GUIDE.md
• Behavioral guidelines:
  • .claude/CODING_GUIDELINES.md (NO EMOJIS, ASCII markers, standards)
  • .claude/AGENT_COORDINATION_RULES.md (delegation guidelines)
  • .claude/agents/*.md (agent-specific documentation)
  • .claude/CLAUDE.md (project context and instructions)
  • Any other .claude/*.md operational files
• Any other tracked changes

FROM Gitea TO Local (PULL):

• All of the above from other machines
• Latest commands and configurations
• Updated session logs from other sessions
• Project-specific work and documentation

---

Execution Steps

Phase 1: Prepare Local Changes

1. Navigate to ClaudeTools repo:

   cd ~/ClaudeTools  # or D:\ClaudeTools on Windows
   

2. Check repository status:

   git status
   

   Report number of changed/new files to user

3. Stage all changes:

   git add -A
   

   This includes:

   • New/modified session logs
   • Updated credentials.md
   • SESSION_STATE.md changes
   • Command updates
   • Directive changes
   • Behavioral guidelines (CODING_GUIDELINES.md, AGENT_COORDINATION_RULES.md, etc.)
   • Agent documentation
   • Project documentation

4. Auto-commit local changes with timestamp:

   git commit -m "sync: Auto-sync from [machine-name] at [timestamp]
   
   Synced files:
   - Session logs updated
   - Latest context and credentials
   - Command/directive updates
   
   Machine: [hostname]
   Timestamp: [YYYY-MM-DD HH:MM:SS]
   
   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
   

   Note: Only commit if there are changes. If working tree is clean, skip to Phase 2.

---

Phase 2: Sync with Gitea

5. Pull latest changes from Gitea:

   git pull origin main --rebase
   

   Handle conflicts if any:

   • Session logs: Keep both versions (rename conflicting file with timestamp)
   • credentials.md: Manual merge required - report to user
   • Other files: Use standard git conflict resolution

   Report what was pulled from remote

6. Push local changes to Gitea:

   git push origin main
   

   Confirm push succeeded

---

Phase 3: Apply Configuration Locally

7. Copy commands to global Claude directory:

   mkdir -p ~/.claude/commands
   cp -r ~/ClaudeTools/.claude/commands/* ~/.claude/commands/
   

   These slash commands are now available globally

8. Apply global settings if available:

   if [ -f ~/ClaudeTools/.claude/settings.json ]; then
     cp ~/ClaudeTools/.claude/settings.json ~/.claude/settings.json
   fi
   

9. Sync project settings:

   if [ -f ~/ClaudeTools/.claude/settings.local.json ]; then
     # Read and note any project-specific settings
   fi
   

---

Phase 4: Context Recovery

10. Find and read most recent session logs:

    Check all locations:

    • ~/ClaudeTools/session-logs/*.md (general)
    • ~/ClaudeTools/projects/*/session-logs/*.md (project-specific)

    Report the 3 most recent logs found:

    • File name and location
    • Last modified date
    • Brief summary of what was worked on (from first 5 lines)

11. Read behavioral guidelines and directives:

    cat ~/ClaudeTools/directives.md
    cat ~/ClaudeTools/.claude/CODING_GUIDELINES.md
    cat ~/ClaudeTools/.claude/AGENT_COORDINATION_RULES.md
    

    Internalize operational directives and behavioral rules to ensure:

    • Proper coordination mode (delegate vs execute)
    • NO EMOJIS rule enforcement
    • Agent delegation patterns
    • Coding standards compliance

---

Phase 5: Report Sync Status

12. Summarize what was synced:

    ## Sync Complete
    
    [OK] Local changes pushed to Gitea:
    - X session logs updated
    - credentials.md synced
    - SESSION_STATE.md updated
    - Y command files
    
    [OK] Remote changes pulled from Gitea:
    - Z files updated from other machines
    - Latest session: [most recent log]
    
    [OK] Configuration applied:
    - Commands available: /checkpoint, /context, /save, /sync, etc.
    - Directives internalized (coordination mode, delegation rules)
    - Behavioral guidelines internalized (NO EMOJIS, ASCII markers, coding standards)
    - Agent coordination rules applied
    - Global settings applied
    
    Recent work (last 3 sessions):
    1. [date] - [project] - [brief summary]
    2. [date] - [project] - [brief summary]
    3. [date] - [project] - [brief summary]
    
    **Status:** All machines in sync. Ready to continue work.
    

13. Refresh directives (auto-invoke):

    Automatically invoke /refresh-directives to internalize all synced behavioral guidelines:

    • Re-read directives.md
    • Re-read CODING_GUIDELINES.md
    • Re-read AGENT_COORDINATION_RULES.md
    • Perform self-assessment for violations
    • Commit to following all behavioral rules

    Why this is critical:

    • Ensures latest behavioral rules are active
    • Prevents shortcut-taking after sync
    • Maintains coordination discipline
    • Enforces NO EMOJIS and ASCII marker rules
    • Ensures proper agent delegation

---

Conflict Resolution

Session Log Conflicts

If both machines created session logs with same date:

1. Keep both versions
2. Rename to: YYYY-MM-DD-session-[machine].md
3. Report conflict to user

credentials.md Conflicts

If credentials.md has conflicts:

1. Do NOT auto-merge
2. Report conflict to user
3. Show conflicting sections
4. Ask user which version to keep or how to merge

Other File Conflicts

Standard git conflict markers:

1. Report files with conflicts
2. Show conflict sections
3. Ask user to resolve manually or provide guidance

---

Machine Detection

Automatically detect machine name for commit messages:

Windows:

$env:COMPUTERNAME

Mac/Linux:

hostname

Timestamp format:

date "+%Y-%m-%d %H:%M:%S"

---

Benefits

Seamless Multi-Machine Workflow

• Start work on one machine, continue on another
• All session context automatically synchronized
• Credentials available everywhere (private repo)
• Commands and directives stay consistent
• Behavioral rules enforced identically (NO EMOJIS, delegation patterns, coding standards)

Complete Context Preservation

• Never lose session data
• Full history across all machines
• Searchable via git log
• Rollback capability if needed

Zero Manual Sync

• One command syncs everything
• Auto-commit prevents forgotten changes
• Push/pull happens automatically
• Conflicts handled gracefully

---

Usage Examples

Standard Sync (Most Common)

User: /sync

Claude:
[Commits local changes]
[Pulls from Gitea]
[Pushes to Gitea]
[Applies configuration]
[Reports status]
[Auto-invokes /refresh-directives]

Sync complete. 3 session logs pushed, 2 updates pulled.
Directives refreshed. Ready to continue work.

Sync Before Important Work

User: "I'm switching to my other machine. /sync"

Claude:
[Syncs everything]
Report: Latest work on Dataforth DOS dashboard pushed to Gitea.
All session logs and credentials synced.
You can now pull on the other machine to continue.

Daily Morning Sync

User: /sync

Claude:
[Pulls overnight changes from other machines]
[Auto-invokes /refresh-directives]
Report: Found 2 new sessions from yesterday evening.
Latest: GuruRMM dashboard redesign completed.
Context recovered. Directives refreshed. Ready for today's work.

---

Error Handling

Network Issues

If git pull/push fails:

1. Report connection error
2. Show what was committed locally
3. Suggest retry or manual sync
4. Changes are safe (committed locally)

Authentication Issues

If Gitea authentication fails:

1. Report auth error
2. Check SSH keys or credentials
3. Provide troubleshooting steps
4. Manual push may be needed

Merge Conflicts

If automatic merge fails:

1. Report which files have conflicts
2. Show conflict markers
3. Ask for user guidance
4. Offer to abort merge if needed

---

Security Notes

credentials.md Syncing:

• Private repository on Gitea (https://git.azcomputerguru.com)
• Only accessible to authorized user
• Encrypted in transit (HTTPS/SSH)
• Safe to sync sensitive credentials
• Enables cross-machine access

What's NOT synced:

• .env files (gitignored)
• API virtual environment (api/venv/)
• Database files (local development)
• Temporary files (*.tmp, *.log)
• node_modules/ directories

---

Integration with Other Commands

After /checkpoint

User can run /sync after /checkpoint to push the checkpoint to Gitea:

User: /checkpoint
Claude: [Creates git commit]

User: /sync
Claude: [Pushes checkpoint to Gitea]

Before /save

User can sync first to see latest context:

User: /sync
Claude: [Shows latest session logs]

User: /save
Claude: [Creates session log with full context]

With /context

Syncing ensures /context has complete history:

User: /sync
Claude: [Syncs all session logs]

User: /context Dataforth
Claude: [Searches complete session log history including other machines]

Auto-invokes /refresh-directives

IMPORTANT: /sync automatically invokes /refresh-directives at the end:

User: /sync
Claude:
[Phase 1: Commits local changes]
[Phase 2: Pulls/pushes to Gitea]
[Phase 3: Applies configuration]
[Phase 4: Recovers context]
[Phase 5: Reports status]
[Auto-invokes /refresh-directives]
[Confirms directives internalized]

Sync complete. Directives refreshed. Ready to coordinate.

Why automatic:

• Ensures latest behavioral rules are active after pulling changes
• Prevents using outdated directives from previous sync
• Maintains coordination discipline across all machines
• Enforces NO EMOJIS rule after any directive updates
• Critical after conversation compaction or multi-machine sync

---

Frequency Recommendations

Daily: Start of work day

• Pull overnight changes
• See what was done on other machines
• Recover latest context

After Major Work: End of coding session

• Push session logs
• Share context across machines
• Backup to Gitea

Before Switching Machines:

• Push all local changes
• Ensure other machine can pull
• Seamless transition

Weekly: General maintenance

• Keep repos in sync
• Review session log history
• Clean up if needed

---

Troubleshooting

"Already up to date" but files seem out of sync

# Force status check
cd ~/ClaudeTools
git fetch origin
git status

"Divergent branches" error

# Rebase local changes on top of remote
git pull origin main --rebase

Lost uncommitted changes

# Check stash
git stash list

# Recover if needed
git stash pop

---

Created: 2026-01-21 Purpose: Bidirectional sync for seamless multi-machine ClaudeTools workflow Repository: https://git.azcomputerguru.com/azcomputerguru/claudetools.git Status: Active - comprehensive sync with context preservation