From 02c2c2fabb529117e2ceb7d3dada504eb353cff1 Mon Sep 17 00:00:00 2001 From: Spencer Date: Thu, 26 Mar 2026 20:49:25 -0500 Subject: [PATCH] docs: document sync hooks, gitattributes, global setup, and remotes --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index 2317188..0521cdf 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,50 @@ Then open Claude Code anywhere and say: Claude will symlink `CLAUDE.md` globally, wire up the skills, and verify the install. Takes about a minute. +## This Install — What's Different + +This repo is a personalised fork of the Cog template, synced across machines via Gitea. Several things are set up here that aren't in the upstream template: + +### Auto-Sync Hooks + +Two hooks in `.claude/settings.json` keep memory in sync automatically when working inside `~/.cog`: + +| Hook | Trigger | What it does | +|------|---------|--------------| +| `SessionStart` | Every time Claude Code opens | `git pull --rebase --autostash` — pulls latest memory from Gitea | +| `Stop` | Every time Claude finishes responding | Commits any changed memory files and pushes to Gitea | + +The Stop hook is a no-op if nothing changed. The SessionStart hook stashes any local edits, pulls, then reapplies them — so it won't stomp in-progress work. + +### Conflict-Safe Merges + +`.gitattributes` sets `merge=union` on append-only observation files: + +``` +memory/**/observations.md merge=union +memory/cog-meta/self-observations.md merge=union +``` + +If two machines both append observations on the same day, git merges them as a union (keeps both) instead of raising a conflict. + +### Global CLAUDE.md + +`~/.claude/CLAUDE.md` is a symlink to `/home/artanis/.cog/CLAUDE.md`. This makes Cog's instructions and memory active in every Claude Code session, regardless of working directory. Skills are similarly symlinked from `~/.cog/.claude/commands/` into `~/.claude/commands/`. + +The `CLAUDE.md` includes an explicit base path declaration so memory reads resolve correctly from any working directory: +> **Base path**: `/home/artanis/.cog/` — all `memory/` references resolve relative to this directory. + +### Git Remotes + +| Remote | URL | Purpose | +|--------|-----|---------| +| `origin` | `https://gitea.bunny-wyvern.ts.net/artanis/Cog-Sync.git` | Personal sync — push/pull memory across machines | +| `upstream` | `https://github.com/marciopuga/cog.git` | Original Cog template — pull framework updates when needed | + +To pull upstream improvements into your install: `git fetch upstream && git merge upstream/main`. + +--- + ## Quick Start (fresh install from template) Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview).