azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add Mac sync guide and grepai sync strategy

Browse Source 
Added comprehensive documentation for syncing development environment
between Windows and Mac machines.

Files:
- MAC_SYNC_PROMPT.md: Complete Mac setup instructions including Ollama
  models, grepai indexing, MCP configuration, and verification steps
- GREPAI_SYNC_STRATEGY.md: Best practices for keeping grepai indexes
  synchronized using independent indexes with automated rebuilds

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-01-22 19:06:45 -07:00
parent 07816eae46
commit 33bd99eb4e
2 changed files with 582 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
GREPAI_SYNC_STRATEGY.md Normal file
View File

@@ -0,0 +1,335 @@
# Grepai Sync Strategy
**Purpose:** Keep grepai indexes synchronized between Windows and Mac development machines
---
## Understanding Grepai Index
**What is the index?**
- Semantic embeddings of your codebase (13,020 chunks from 961 files)
- Size: 73.7 MB
- Generated using: nomic-embed-text model via Ollama
- Stored locally: `.grepai/` directory (usually)
**Index components:**
- Embeddings database (vector representations of code)
- Symbol tracking database (functions, classes, etc.)
- File metadata (paths, timestamps, hashes)
---
## Sync Strategy Options
### Option 1: Independent Indexes (RECOMMENDED)
**How it works:**
- Each machine maintains its own grepai index
- Index is gitignored (not committed to repository)
- Each machine rebuilds index from local codebase
**Advantages:**
- [OK] Always consistent with local codebase
- [OK] No merge conflicts
- [OK] Handles machine-specific paths correctly
- [OK] Simple and reliable
**Disadvantages:**
- [WARNING] Must rebuild index on each machine (one-time setup)
- [WARNING] Initial indexing takes time (~2-5 minutes for 961 files)
**Setup:**
```bash
# Add to .gitignore
echo ".grepai/" >> .gitignore
# On each machine:
grepai init
grepai index
# Keep codebase in sync via git
git pull origin main
grepai index # Rebuild after pulling changes
```
**When to rebuild:**
- After pulling major code changes (>50 files)
- After switching branches
- If search results seem outdated
- Weekly maintenance (optional)
---
### Option 2: Shared Index via Git
**How it works:**
- Commit `.grepai/` directory to repository
- Pull index along with code changes
**Advantages:**
- [OK] Instant sync (no rebuild needed)
- [OK] Same index on all machines
**Disadvantages:**
- [ERROR] Can cause merge conflicts
- [ERROR] May have absolute path issues (D:\ vs ~/)
- [ERROR] Index may get out of sync with actual code
- [ERROR] Increases repository size (+73.7 MB)
**NOT RECOMMENDED** due to path conflicts and sync issues.
---
### Option 3: Automated Rebuild on Pull (BEST PRACTICE)
**How it works:**
- Keep indexes independent (Option 1)
- Automatically rebuild index after git pull
- Use git hooks to trigger rebuild
**Setup:**
Create `.git/hooks/post-merge` (git pull trigger):
```bash
#!/bin/bash
echo "[grepai] Rebuilding index after merge..."
grepai index --quiet
echo "[OK] Index updated"
```
Make executable:
```bash
chmod +x .git/hooks/post-merge
```
**Advantages:**
- [OK] Always up to date
- [OK] Automated (no manual intervention)
- [OK] No merge conflicts
- [OK] Each machine has correct index
**Disadvantages:**
- [WARNING] Adds 1-2 minutes to git pull time
- [WARNING] Requires git hook setup on each machine
---
## Recommended Workflow
### Initial Setup (One-Time Per Machine)
**On Windows:**
```bash
# Ensure .grepai is gitignored
echo ".grepai/" >> .gitignore
git add .gitignore
git commit -m "chore: gitignore grepai index"
# Build index
grepai index
```
**On Mac:**
```bash
# Pull latest code
git pull origin main
# Install Ollama models
ollama pull nomic-embed-text
# Build index
grepai index
```
### Daily Workflow
**Start of day (on either machine):**
```bash
# Update codebase
git pull origin main
# Rebuild index (if significant changes)
grepai index
```
**During development:**
- No action needed
- Grepai auto-updates as you edit files (depending on configuration)
**End of day:**
```bash
# Commit your changes
git add .
git commit -m "your message"
git push origin main
```
**On other machine:**
```bash
# Pull changes
git pull origin main
# Rebuild index
grepai index
```
---
## Quick Rebuild Commands
**Full rebuild:**
```bash
grepai index
```
**Incremental update (faster, if supported):**
```bash
grepai index --incremental
```
**Check if rebuild needed:**
```bash
# Compare last index time with last git pull
grepai status
git log -1 --format="%ai"
```
---
## Automation Script
**Create `sync-and-index.sh`:**
```bash
#!/bin/bash
# Sync codebase and rebuild grepai index
echo "=== Syncing ClaudeTools ==="
# Pull latest changes
echo "[1/3] Pulling from git..."
git pull origin main
if [ $? -ne 0 ]; then
echo "[ERROR] Git pull failed"
exit 1
fi
# Check if significant changes
CHANGED_FILES=$(git diff HEAD@{1} --name-only | wc -l)
echo "[2/3] Changed files: $CHANGED_FILES"
# Rebuild index if changes detected
if [ "$CHANGED_FILES" -gt 0 ]; then
echo "[3/3] Rebuilding grepai index..."
grepai index
echo "[OK] Sync complete with index rebuild"
else
echo "[3/3] No changes, skipping index rebuild"
echo "[OK] Sync complete"
fi
```
**Usage:**
```bash
chmod +x sync-and-index.sh
./sync-and-index.sh
```
---
## Monitoring Index Health
**Check index status:**
```bash
grepai status
```
**Expected output (healthy):**
```
Total files: 961
Total chunks: 13,020
Index size: 73.7 MB
Last updated: [recent timestamp]
Provider: ollama
Model: nomic-embed-text
Symbols: Ready
```
**Signs of unhealthy index:**
- File count doesn't match codebase
- Last updated > 7 days old
- Symbol tracking not ready
- Search results seem wrong
**Fix:**
```bash
grepai rebuild # or
grepai index --force
```
---
## Best Practices
1. **Always gitignore `.grepai/`** - Prevents merge conflicts
2. **Rebuild after major pulls** - Keeps index accurate
3. **Use same embedding model** - Ensures consistency (nomic-embed-text)
4. **Verify index health weekly** - Run `grepai status`
5. **Document rebuild frequency** - Set team expectations
---
## Troubleshooting
### Index out of sync
```bash
# Force complete rebuild
rm -rf .grepai
grepai init
grepai index
```
### Different results on different machines
- Check embedding model: `grepai status | grep model`
- Should both use: `nomic-embed-text`
- Rebuild with same model if different
### Index too large
```bash
# Check what's being indexed
grepai stats
# Add exclusions to .grepai.yml (if exists)
# exclude:
# - node_modules/
# - venv/
# - .git/
```
---
## Summary
**RECOMMENDED APPROACH: Option 3 (Automated Rebuild)**
**Setup:**
1. Gitignore `.grepai/` directory
2. Install git hook for post-merge rebuild
3. Each machine maintains independent index
4. Index rebuilds automatically after git pull
**Maintenance:**
- Initial index build: 2-5 minutes (one-time per machine)
- Incremental rebuilds: 30-60 seconds (after pulls)
- Full rebuilds: As needed (weekly or when issues arise)
**Key principle:** Treat grepai index like compiled artifacts - gitignore them and rebuild from source (the codebase) as needed.
---
## Last Updated
2026-01-22 - Initial creation

247
MAC_SYNC_PROMPT.md Normal file
View File

@@ -0,0 +1,247 @@
# Mac Machine Sync Instructions
**Date Created:** 2026-01-22
**Purpose:** Bring Mac Claude instance into sync with Windows development machine
## Overview
This prompt configures the Mac to match the Windows ClaudeTools development environment. Use this when starting work on the Mac to ensure consistency.
---
## 1. System Status Check
First, verify these services are running on the Mac:
```bash
# Check Ollama status
curl http://localhost:11434/api/tags
# Check grepai index
# (Command will be provided after index setup)
```
---
## 2. Required Ollama Models
Ensure these models are installed on the Mac:
```bash
ollama pull llama3.1:8b # 4.6 GB - General purpose
ollama pull qwen2.5-coder:7b # 4.4 GB - Code-specific
ollama pull qwen3-vl:4b # 3.1 GB - Vision model
ollama pull nomic-embed-text # 0.3 GB - Embeddings (REQUIRED for grepai)
ollama pull qwen3-embedding:4b # 2.3 GB - Alternative embeddings
```
**Critical:** `nomic-embed-text` is required for grepai semantic search.
---
## 3. Grepai Index Setup
**Current Windows Index Status:**
- Total files: 961
- Total chunks: 13,020
- Index size: 73.7 MB
- Last updated: 2026-01-22 17:40:20
- Embedding model: nomic-embed-text
- Symbols: Ready
**Mac Setup Steps:**
```bash
# Navigate to ClaudeTools directory
cd ~/path/to/ClaudeTools
# Initialize grepai (if not already done)
grepai init
# Configure to use Ollama with nomic-embed-text
# (Check grepai config file for provider settings)
# Build index
grepai index
# Verify index status
grepai status
```
---
## 4. MCP Server Configuration
**Configured MCP Servers (from .mcp.json):**
- GitHub MCP - Repository and PR management
- Filesystem MCP - Enhanced file operations
- Sequential Thinking MCP - Structured problem-solving
- Ollama Assistant MCP - Local LLM integration
- Grepai MCP - Semantic code search
**Verify MCP Configuration:**
1. Check `.mcp.json` exists and is properly configured
2. Restart Claude Code completely after any MCP changes
3. Test each MCP server:
- "List Python files in the api directory" (Filesystem)
- "Use sequential thinking to analyze X" (Sequential Thinking)
- "Ask Ollama about Y" (Ollama Assistant)
- "Search for authentication code" (Grepai)
---
## 5. Database Connection
**IMPORTANT:** Database is on Windows RMM server (172.16.3.30)
**Connection Details:**
```
Host: 172.16.3.30:3306
Database: claudetools
User: claudetools
Password: CT_e8fcd5a3952030a79ed6debae6c954ed
```
**Environment Variable:**
```bash
export DATABASE_URL="mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4"
```
**Network Requirements:**
- Ensure Mac can reach 172.16.3.30:3306
- Test connection: `telnet 172.16.3.30 3306` or `nc -zv 172.16.3.30 3306`
---
## 6. Project Structure Verification
Verify these directories exist:
```bash
ls -la D:\ClaudeTools/ # Adjust path for Mac
# Expected structure:
# - api/ # FastAPI application
# - migrations/ # Alembic migrations
# - .claude/ # Claude Code config
# - mcp-servers/ # MCP implementations
# - projects/ # Project workspaces
# - clients/ # Client-specific work
# - session-logs/ # Session documentation
```
---
## 7. Git Sync
**Ensure repository is up to date:**
```bash
git fetch origin
git status
# If behind: git pull origin main
```
**Current Branch:** main
**Remote:** Check with `git remote -v`
---
## 8. Virtual Environment
**Python virtual environment location (Windows):** `api\venv\`
**Mac Setup:**
```bash
cd api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
---
## 9. Quick Verification Commands
Run these to verify Mac is in sync:
```bash
# 1. Check Ollama models
ollama list
# 2. Check grepai status
grepai status
# 3. Test database connection (if Python installed)
python -c "import pymysql; conn = pymysql.connect(host='172.16.3.30', port=3306, user='claudetools', password='CT_e8fcd5a3952030a79ed6debae6c954ed', database='claudetools'); print('[OK] Database connected'); conn.close()"
# 4. Check git status
git status
# 5. Verify MCP servers (in Claude Code)
# Ask: "Check Ollama status" and "Check grepai index status"
```
---
## 10. Key Files to Review
**Before starting work, read these files:**
- `CLAUDE.md` - Project context and guidelines
- `directives.md` - Your identity and coordination rules
- `.claude/FILE_PLACEMENT_GUIDE.md` - File organization rules
- `SESSION_STATE.md` - Complete project history
- `credentials.md` - Infrastructure credentials (UNREDACTED)
---
## 11. Common Mac-Specific Adjustments
**Path Differences:**
- Windows: `D:\ClaudeTools\`
- Mac: Adjust to your local path (e.g., `~/Projects/ClaudeTools/`)
**Line Endings:**
- Ensure git is configured: `git config core.autocrlf input`
**Case Sensitivity:**
- Mac filesystem may be case-sensitive (APFS default is case-insensitive but case-preserving)
---
## 12. Sync Verification Checklist
- [ ] Ollama running with all 5 models
- [ ] Grepai index built (961 files, 13,020 chunks)
- [ ] MCP servers configured and tested
- [ ] Database connection verified (172.16.3.30:3306)
- [ ] Git repository up to date
- [ ] Virtual environment created and packages installed
- [ ] Key documentation files reviewed
---
## Quick Start Command
**Single command to verify everything:**
```bash
echo "=== Ollama Status ===" && ollama list && \
echo "=== Grepai Status ===" && grepai status && \
echo "=== Git Status ===" && git status && \
echo "=== Database Test ===" && python -c "import pymysql; conn = pymysql.connect(host='172.16.3.30', port=3306, user='claudetools', password='CT_e8fcd5a3952030a79ed6debae6c954ed', database='claudetools'); print('[OK] Connected'); conn.close()" && \
echo "=== Sync Check Complete ==="
```
---
## Notes
- **Windows Machine:** Primary development environment
- **Mac Machine:** Secondary/mobile development environment
- **Database:** Centralized on Windows RMM server (requires network access)
- **Grepai:** Each machine maintains its own index (see sync strategy below)
---
## Last Updated
2026-01-22 - Initial creation based on Windows machine state