claude-sync-docs

A Claude Code skill that reconciles a documentation tree against decisions made across recent Claude conversations but never written down.

The flow: read the tail of each recent chat thread for the current project, use each chat's name + touched files as hints to find the doc(s) it affects, diff the docs against what the conversations established, then update them. Designed to catch the drift between "what we decided in chat" and "what the docs say."

Use it from Claude Code

The skill is invoked as a slash command in any Claude Code session:

/sync-docs-from-chats <docs-dir>

For example: /sync-docs-from-chats docs/06 Roadmaps.

Options forwarded to the extractor: --limit N (sessions, default 12), --tail T (human turns per session, default 8), --window-minutes M (default 60).

See SKILL.md for the full procedure and guardrails.

Install in another project (as a git submodule)

# from your project root
git submodule add https://github.com/Ethycs/claude-sync-docs.git .claude/skills/sync-docs-from-chats
git submodule update --init --recursive
git commit -m "feat(skills): add sync-docs-from-chats as a submodule"

To update later:

git submodule update --remote .claude/skills/sync-docs-from-chats
git commit -am "chore(skills): bump sync-docs-from-chats"

How it works

1. Reads ~/.claude/projects/<encoded-project-path>/<session>.jsonl — the local transcript files Claude Code writes per session.
2. Per session, extracts the chat name (first human prompt with harness wrappers stripped), the last activity timestamp, the files touched in the tail, and the tail of human prompts.
3. Anchors to the most recent session, then includes any session whose last activity is within --window-minutes of that anchor — i.e. the current "burst of work."
4. Hands the digest to the calling Claude as JSON or human-readable text via --format json.

The extractor at scripts/extract_chats.py is read-only — it never writes. The actual doc updates happen in the calling Claude's edit loop, scoped to files under the <docs-dir> you supply.

Guardrails

• Read-only on transcripts and source. The skill only writes files under the <docs-dir> you pass.
• Propose before bulk edits. When more than ~3 docs would change, the calling Claude lists the planned edits first.
• The extractor strips harness-injected <ide_opened_file> / <system-reminder> / command wrappers so chat names reflect what the human actually typed.

Why it exists

Documentation drift compounds. Conversations land decisions — "this default flipped to 5", "this surface is now Python-owned", "this carve-out exists" — and the docs don't always catch up before the next session forgets the context. This skill makes "remind me what we decided yesterday and bring the docs into line" a one-command workflow.

License

MIT (or whatever you prefer — open an issue if it matters).