ClaudeTools cleanup: drop dead context-recall layer, unify /save + /sync
Deletions (~1,500 lines of dead docs): - .claude/hooks/ — docs-only directory, no executables. Referenced scripts setup-context-recall.sh / test-context-recall.sh did not exist. Hooks would have POSTed to localhost:8000; the API actually ran at 172.16.3.30:8001 and is no longer in use. - .claude/AUTO_CONTEXT_SYSTEM.md — 347-line duplicate spec of CLAUDE.md's Automatic Context Loading section, referencing unimplemented hooks. - .claude/URGENT-vault-path-bug.md — 217-line urgency note for a fix that already shipped weeks ago. - .claude/context-recall-config.env.example — config template for the same dead system. Refactors (~500 lines net removed): - /save and /sync now wrap bash .claude/scripts/sync.sh as the single source of truth for git ops. /save adds a session-log-writing step in front; /sync invokes the script directly. - Dropped /sync's manual git phases that contradicted sync.sh. - Dropped the cp -r ~/ClaudeTools/.claude/commands/* ~/.claude/commands/ step (clobbered per-user customization in the multi-user model). - Dropped auto-invoke of /refresh-directives (command does not exist). - Dropped references to directives.md (file does not exist). - /save now documents the rm -f save_narrative_prompt.txt step, fixing the stale-prompt bug Howard documented in feedback_tmp_path_windows.md. Fixes: - CLAUDE.md SESSION_STATE.md reference replaced with the canonical PROJECT_STATE.md (per-project, with protocol at .claude/PROJECT_STATE_PROTOCOL.md). 16 client folders already use PROJECT_STATE.md; SESSION_STATE.md was only a stale reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,25 +1,44 @@
|
||||
Save a COMPREHENSIVE session log to appropriate session-logs/ directory. This is critical for context recovery.
|
||||
Save a comprehensive session log to the appropriate `session-logs/` directory, then sync the repo.
|
||||
|
||||
## Ollama drafting (documentation engine)
|
||||
`/save` and `/sync` share `bash .claude/scripts/sync.sh` as the canonical driver for git operations. The only difference: `/save` writes a session log first, then calls sync. `/sync` calls sync directly (no log).
|
||||
|
||||
Narrative sections are drafted by Ollama (qwen3:14b), then assembled with Claude-generated factual sections. Claude reviews the full document before writing.
|
||||
---
|
||||
|
||||
**Ollama drafts:** Session Summary, Key Decisions, Problems Encountered
|
||||
**Claude owns (verbatim, never delegated):** Credentials, infrastructure IPs/hostnames, command outputs, file paths, pending tasks
|
||||
## Phase 1 — Generate the narrative
|
||||
|
||||
### Draft call
|
||||
Ollama drafts the prose sections (qwen3:14b at `localhost:11434` or Tailscale `100.92.127.64:11434`). Claude owns the factual sections — never delegate facts to Ollama.
|
||||
|
||||
| Author | Sections |
|
||||
|---|---|
|
||||
| Ollama | Session Summary, Key Decisions, Problems Encountered |
|
||||
| Claude (verbatim) | User block, Configuration Changes, Credentials, Infrastructure, Commands & Outputs, Pending Tasks, References |
|
||||
|
||||
### Resolve Ollama endpoint
|
||||
|
||||
```bash
|
||||
# Check Ollama (reuse $OLLAMA across the save operation)
|
||||
if curl -s -m 2 http://localhost:11434/api/tags >/dev/null 2>&1; then OLLAMA="http://localhost:11434"
|
||||
elif curl -s -m 3 http://100.92.127.64:11434/api/tags >/dev/null 2>&1; then OLLAMA="http://100.92.127.64:11434"
|
||||
else OLLAMA=""; fi
|
||||
if curl -s -m 2 http://localhost:11434/api/tags >/dev/null 2>&1; then
|
||||
OLLAMA="http://localhost:11434"
|
||||
elif curl -s -m 3 http://100.92.127.64:11434/api/tags >/dev/null 2>&1; then
|
||||
OLLAMA="http://100.92.127.64:11434"
|
||||
else
|
||||
OLLAMA="" # Claude drafts narrative directly
|
||||
fi
|
||||
```
|
||||
|
||||
# Write narrative prompt to temp file
|
||||
cat > "C:/Users/guru/AppData/Local/Temp/save_narrative_prompt.txt" << 'ENDPROMPT'
|
||||
You are a technical session log writer for an MSP (managed service provider).
|
||||
Write three sections of a session log in markdown. Be concise, factual, and technical.
|
||||
No filler phrases. Use past tense.
|
||||
### Draft via Ollama
|
||||
|
||||
**Always delete the prompt file first** — prior `/save` runs leave a stale `save_narrative_prompt.txt` in `%LOCALAPPDATA%/Temp`, and the Write tool refuses to overwrite without a Read. The silent fallback is `py` reading the leftover file and Ollama producing a perfectly-coherent narrative about *the previous session's work*. Documented in `.claude/memory/feedback_tmp_path_windows.md`.
|
||||
|
||||
```bash
|
||||
PROMPT_FILE="$LOCALAPPDATA/Temp/save_narrative_prompt.txt"
|
||||
rm -f "$PROMPT_FILE" # critical — see above
|
||||
# ... then Write the prompt with this session's WORK DONE bullets ...
|
||||
```
|
||||
|
||||
Prompt template:
|
||||
|
||||
```
|
||||
You are a technical session log writer for an MSP (Arizona Computer Guru). Write three sections in markdown. Be concise, factual, technical. No filler phrases. Use past tense. No emojis.
|
||||
|
||||
WORK DONE THIS SESSION:
|
||||
<paste bullet list of what happened>
|
||||
@@ -27,157 +46,94 @@ WORK DONE THIS SESSION:
|
||||
Write these three sections only:
|
||||
|
||||
## Session Summary
|
||||
<2-4 paragraph narrative: what was accomplished, in what order, why>
|
||||
<3-5 paragraph narrative: what was accomplished, in what order, why>
|
||||
|
||||
## Key Decisions
|
||||
<bullet list of non-obvious decisions made and their rationale>
|
||||
<bullet list of non-obvious decisions and their rationale>
|
||||
|
||||
## Problems Encountered
|
||||
<bullet list of problems hit and how each was resolved; omit if none>
|
||||
ENDPROMPT
|
||||
|
||||
NARRATIVE=$(py -c "
|
||||
import urllib.request, json
|
||||
prompt = open('C:/Users/guru/AppData/Local/Temp/save_narrative_prompt.txt', encoding='utf-8').read()
|
||||
body = json.dumps({'model':'qwen3:14b','messages':[{'role':'user','content':prompt}],'stream':False,'think':False}).encode()
|
||||
res = json.loads(urllib.request.urlopen(urllib.request.Request('$OLLAMA/api/chat', body), timeout=120).read())
|
||||
print(res['message']['content'])
|
||||
")
|
||||
|
||||
# Fallback: if OLLAMA empty, Claude writes narrative directly
|
||||
```
|
||||
|
||||
Claude reviews the narrative output before assembling the final document.
|
||||
Run via Python (PyJWT-free path):
|
||||
|
||||
```bash
|
||||
py -c "
|
||||
import urllib.request, json
|
||||
prompt = open('$PROMPT_FILE', encoding='utf-8').read()
|
||||
body = json.dumps({'model':'qwen3:14b','messages':[{'role':'user','content':prompt}],'stream':False,'think':False}).encode()
|
||||
res = json.loads(urllib.request.urlopen(urllib.request.Request('$OLLAMA/api/chat', body), timeout=300).read())
|
||||
print(res['message']['content'])
|
||||
"
|
||||
```
|
||||
|
||||
Claude reviews the output before assembling. Common Ollama issues to fix on review: invented compliance/risk language, hallucinated reasoning, off-task content if the prompt file was stale.
|
||||
|
||||
---
|
||||
|
||||
## Determine Correct Location
|
||||
## Phase 2 — Write to disk
|
||||
|
||||
**IMPORTANT: Save to project-specific or general session-logs based on work context**
|
||||
### Location
|
||||
|
||||
### Project-Specific Logs
|
||||
If working on a specific project, save to project folder:
|
||||
- Dataforth DOS work → `projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md`
|
||||
- ClaudeTools API work → `projects/claudetools-api/session-logs/YYYY-MM-DD-session.md`
|
||||
- Client-specific work → `clients/[client-name]/session-logs/YYYY-MM-DD-session.md`
|
||||
| Work scope | Path |
|
||||
|---|---|
|
||||
| Single project | `projects/<project>/session-logs/YYYY-MM-DD-session.md` |
|
||||
| Client | `clients/<slug>/session-logs/YYYY-MM-DD-session.md` |
|
||||
| Multi-project / general | `session-logs/YYYY-MM-DD-session.md` |
|
||||
|
||||
### General/Mixed Work
|
||||
If working across multiple projects or general tasks:
|
||||
- Use root `session-logs/YYYY-MM-DD-session.md`
|
||||
### Filename + append behavior
|
||||
|
||||
## Filename
|
||||
Use format `YYYY-MM-DD-session.md` (today's date) in appropriate folder
|
||||
- Filename: `YYYY-MM-DD-session.md` (today's local date)
|
||||
- If file exists, **append** a `## Update: HH:MM PT — <topic>` section. Do not overwrite.
|
||||
- If two users worked on the same date, namespace: `YYYY-MM-DD-<user>-<topic>.md` (e.g. `2026-05-01-howard-syncro-billing-batch.md`)
|
||||
|
||||
## If file exists
|
||||
Append a new section with timestamp header (## Update: HH:MM), don't overwrite
|
||||
### Required sections (in order)
|
||||
|
||||
## MANDATORY Content to Include
|
||||
1. **User block** — name, machine, role, session span. Pull from `.claude/identity.json` + git config.
|
||||
2. **Session Summary** (Ollama)
|
||||
3. **Key Decisions** (Ollama)
|
||||
4. **Problems Encountered** (Ollama)
|
||||
5. **Configuration Changes** — files modified / created / deleted (with paths)
|
||||
6. **Credentials & Secrets** — UNREDACTED if newly discovered or created. Vault paths if vaulted. Never half-redact a value future-Claude might need.
|
||||
7. **Infrastructure & Servers** — IPs, hostnames, ports, tenant IDs, container names, DNS, certs
|
||||
8. **Commands & Outputs** — important one-liners, key outputs, error messages with resolution
|
||||
9. **Pending / Incomplete Tasks** — what's left, blockers, next steps
|
||||
10. **Reference Information** — URLs, endpoints, commit SHAs, ticket IDs, routine IDs, file paths
|
||||
|
||||
### 1. Session Summary
|
||||
- What was accomplished in this session
|
||||
- Key decisions made and rationale
|
||||
- Problems encountered and how they were solved
|
||||
When in doubt, include MORE detail — future sessions search these logs to recover context.
|
||||
|
||||
### 2. ALL Credentials & Secrets (UNREDACTED)
|
||||
**CRITICAL: Store credentials completely - these are needed for future sessions**
|
||||
- API keys and tokens (full values)
|
||||
- Usernames and passwords
|
||||
- Database credentials
|
||||
- JWT secrets
|
||||
- SSH keys/passphrases if relevant
|
||||
- Any authentication information used or discovered
|
||||
---
|
||||
|
||||
Format credentials as:
|
||||
```
|
||||
### Credentials
|
||||
- Service Name: username / password
|
||||
- API Token: full_token_value
|
||||
## Phase 3 — Sync
|
||||
|
||||
```bash
|
||||
bash .claude/scripts/sync.sh
|
||||
```
|
||||
|
||||
### 3. Infrastructure & Servers
|
||||
- All IPs, hostnames, ports used
|
||||
- Container names and configurations
|
||||
- DNS records added or modified
|
||||
- SSL certificates created
|
||||
- Any network/firewall changes
|
||||
`sync.sh` handles: stage tracked changes by name (never `git add -A`), auto-commit, fetch + rebase, push, then the same flow for the vault repo, then surface cross-user `## Note for <user>` blocks.
|
||||
|
||||
### 4. Commands & Outputs
|
||||
- Important commands run (especially complex ones)
|
||||
- Key outputs and results
|
||||
- Error messages and their resolutions
|
||||
|
||||
### 5. Configuration Changes
|
||||
- Files created or modified (with paths)
|
||||
- Settings changed
|
||||
- Environment variables set
|
||||
|
||||
### 6. Pending/Incomplete Tasks
|
||||
- What still needs to be done
|
||||
- Blockers or issues awaiting resolution
|
||||
- Next steps for future sessions
|
||||
|
||||
### 7. Reference Information
|
||||
- URLs, endpoints, ports
|
||||
- File paths that may be needed again
|
||||
- Any technical details that might be forgotten
|
||||
|
||||
## After Saving
|
||||
|
||||
Before committing, emit a **Change Summary** block for the user to review:
|
||||
After sync, emit a **Post-commit Summary**:
|
||||
|
||||
```
|
||||
## Change Summary (this session)
|
||||
User: <full_name> (from .claude/identity.json)
|
||||
Machine: <HOSTNAME>
|
||||
|
||||
Files changed:
|
||||
<output of: git status --short>
|
||||
|
||||
Stats:
|
||||
<output of: git diff --stat HEAD>
|
||||
## Post-commit Summary
|
||||
Commit: <sha> <subject>
|
||||
Author: <name> <<email>>
|
||||
Push: <old>..<new> main -> main (origin)
|
||||
File: <session log path> (+N lines, appended/created)
|
||||
```
|
||||
|
||||
Then:
|
||||
1. Commit with message: "Session log: [brief description of work done]"
|
||||
2. Push to gitea remote (if configured)
|
||||
3. After push, emit a **Post-commit Summary**:
|
||||
- New commit SHA + message
|
||||
- Author (from `git log -1 --format='%an <%ae>'`)
|
||||
- Files in the commit (from `git show --stat HEAD`)
|
||||
4. Confirm push was successful
|
||||
---
|
||||
|
||||
### Why the summary
|
||||
## Cross-user note handling (CRITICAL)
|
||||
|
||||
In the multi-user setup, commits can land in `main` from either team member. Always attributing author + files makes it obvious who made what change when someone else pulls the repo. Saves re-reading diffs to figure out "wait, when did that happen?"
|
||||
If `sync.sh` surfaces a `## Note for <user>` or `## Message for <user>` block from an incoming session log, display it **prominently at the top of the response, before the sync summary**:
|
||||
|
||||
## Purpose
|
||||
```
|
||||
============================================================
|
||||
MESSAGE FROM <author> (<date>)
|
||||
============================================================
|
||||
<full note content>
|
||||
============================================================
|
||||
```
|
||||
|
||||
This log MUST contain enough detail to fully restore context if this conversation is summarized or a new session starts. When in doubt, include MORE information rather than less. Future Claude instances will search these logs to find credentials and context.
|
||||
|
||||
## Project-Specific Requirements
|
||||
|
||||
### Dataforth DOS Project
|
||||
Save to: `projects/dataforth-dos/session-logs/`
|
||||
Include:
|
||||
- DOS batch file changes and versions
|
||||
- Deployment script updates
|
||||
- Infrastructure changes (AD2, D2TESTNAS)
|
||||
- Test results from TS-XX machines
|
||||
- Documentation files created
|
||||
|
||||
### ClaudeTools API Project
|
||||
Save to: `projects/claudetools-api/session-logs/`
|
||||
Include:
|
||||
- Database connection details (172.16.3.30:3306/claudetools)
|
||||
- API endpoints created or modified
|
||||
- Migration files created
|
||||
- Test results and coverage
|
||||
- Any infrastructure changes (servers, networks, clients)
|
||||
|
||||
### Client Work
|
||||
Save to: `clients/[client-name]/session-logs/`
|
||||
Include:
|
||||
- Issues resolved
|
||||
- Services provided
|
||||
- Support tickets/cases
|
||||
- Client-specific infrastructure changes
|
||||
Explicitly address each action item or question before moving on.
|
||||
|
||||
@@ -1,504 +1,47 @@
|
||||
# /sync - Bidirectional ClaudeTools Sync
|
||||
Sync the ClaudeTools and vault repos with Gitea.
|
||||
|
||||
Synchronize ClaudeTools configuration, session data, and context bidirectionally with Gitea. Ensures all machines stay perfectly in sync for seamless cross-machine workflow.
|
||||
## What this does
|
||||
|
||||
Invokes `bash .claude/scripts/sync.sh`, which:
|
||||
|
||||
1. Stages tracked local changes **by name** (never `git add -A` — avoids picking up `.env`, generated files, etc.)
|
||||
2. Auto-commits any local changes with `sync: auto-sync from <hostname> at <timestamp>`
|
||||
3. Fetches from origin, rebases local commits onto remote
|
||||
4. Pushes to origin
|
||||
5. Repeats 1-4 for the **vault** repo (path read from `.claude/identity.json` `vault_path` field)
|
||||
6. Surfaces any `## Note for <user>` / `## Message for <user>` blocks from incoming session logs
|
||||
|
||||
The script is the single source of truth for git operations. Both `/sync` and `/save` invoke it.
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT: Use Automated Sync Script
|
||||
## Cross-user note handling (CRITICAL)
|
||||
|
||||
**CRITICAL:** When user invokes `/sync`, execute the automated sync script instead of manual steps.
|
||||
If sync surfaces a note from another user, display it **prominently at the top of the response, before the sync summary**, formatted as:
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
bash .claude/scripts/sync.sh
|
||||
```
|
||||
OR
|
||||
```cmd
|
||||
.claude\scripts\sync.bat
|
||||
============================================================
|
||||
MESSAGE FROM <author> (<date>)
|
||||
============================================================
|
||||
<full note content>
|
||||
============================================================
|
||||
```
|
||||
|
||||
**Mac/Linux:**
|
||||
```bash
|
||||
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
|
||||
Address each action item or question explicitly before moving on. Do not bury cross-user notes in the sync summary or skip them because other work is in progress.
|
||||
|
||||
---
|
||||
|
||||
## What Gets Synced
|
||||
## Output format
|
||||
|
||||
**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
|
||||
Report:
|
||||
- Pulled commits — count + authors + one-line summaries
|
||||
- Pushed commits — count + your commits + outgoing SHAs
|
||||
- Vault sync status — pulled/pushed/clean
|
||||
- Cross-user notes addressed (if any)
|
||||
- Final HEAD + status
|
||||
|
||||
---
|
||||
|
||||
## Execution Steps
|
||||
## Companion: `/save`
|
||||
|
||||
### Phase 1: Prepare Local Changes
|
||||
|
||||
1. **Navigate to ClaudeTools repo:**
|
||||
```bash
|
||||
cd ~/ClaudeTools # or D:\ClaudeTools on Windows
|
||||
```
|
||||
|
||||
2. **Check repository status:**
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
Report number of changed/new files to user
|
||||
|
||||
3. **Stage all changes:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Confirm push succeeded
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Apply Configuration Locally
|
||||
|
||||
7. **Copy commands to global Claude directory:**
|
||||
```bash
|
||||
mkdir -p ~/.claude/commands
|
||||
cp -r ~/ClaudeTools/.claude/commands/* ~/.claude/commands/
|
||||
```
|
||||
These slash commands are now available globally
|
||||
|
||||
8. **Apply global settings if available:**
|
||||
```bash
|
||||
if [ -f ~/ClaudeTools/.claude/settings.json ]; then
|
||||
cp ~/ClaudeTools/.claude/settings.json ~/.claude/settings.json
|
||||
fi
|
||||
```
|
||||
|
||||
9. **Sync project settings:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```powershell
|
||||
$env:COMPUTERNAME
|
||||
```
|
||||
|
||||
**Mac/Linux:**
|
||||
```bash
|
||||
hostname
|
||||
```
|
||||
|
||||
**Timestamp format:**
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# Force status check
|
||||
cd ~/ClaudeTools
|
||||
git fetch origin
|
||||
git status
|
||||
```
|
||||
|
||||
### "Divergent branches" error
|
||||
```bash
|
||||
# Rebase local changes on top of remote
|
||||
git pull origin main --rebase
|
||||
```
|
||||
|
||||
### Lost uncommitted changes
|
||||
```bash
|
||||
# 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
|
||||
`/save` writes a comprehensive session log first, then invokes the same `sync.sh`. Use `/save` after substantive work to capture context for future sessions. Use `/sync` for routine repo sync without writing a log (start of day, switching machines, mid-session check-in).
|
||||
|
||||
Reference in New Issue
Block a user