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

ClaudeTools cleanup: drop dead context-recall layer, unify /save + /sync

Browse Source 
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:
Mike Swanson
2026-05-01 18:33:46 -07:00
parent 833a662b0c
commit a18fa5f93a
10 changed files with 127 additions and 2141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
.claude/commands/save.md
View File

@@ -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.