@vishalpunjabi/claude-profile 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishal Punjabi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# claude-profile
+
+Sync your `~/.claude/` config across machines via a git-backed multi-profile system.
+
+**Status: v0.1.0 — early release. macOS + Linux only. Not yet on npm.**
+
+**Docs:** https://vshalpnjabi.github.io/claude-profile/ (deployed from `main` on every doc change)
+
+---
+
+## Install
+
+Until the package is published to npm, install directly from GitHub:
+
+```bash
+# Latest from default branch (main)
+npm install -g github:vshalpnjabi/claude-profile
+
+# Pinned to a release tag
+npm install -g github:vshalpnjabi/claude-profile#v0.1.0
+```
+
+Or clone and link locally:
+
+```bash
+git clone https://github.com/vshalpnjabi/claude-profile.git
+cd claude-profile
+npm install && npm run build && npm link
+```
+
+---
+
+## Quickstart
+
+### Machine A (first machine)
+
+```bash
+# Create an empty private GitHub repo first (e.g., github.com/you/my-claude)
+claude-profile init --git git@github.com:you/my-claude.git --profile default --activate
+claude-profile install-skill   # wires SessionStart/Stop hooks for auto-sync
+```
+
+### Machine B (second machine)
+
+```bash
+claude-profile init --git git@github.com:you/my-claude.git --profile default --activate
+claude-profile install-skill
+# ~/.claude/ now mirrors Machine A
+```
+
+### See what's in a profile
+
+```bash
+claude-profile describe           # full sectioned report
+claude-profile describe --brief   # counts only
+claude-profile describe --json    # machine-readable
+```
+
+---
+
+## What gets synced
+
+**Synced by default (everything under `~/.claude/`):** `settings.json`,
+`settings.local.json`, `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `hooks/`,
+`output-styles/`, `plugins/` (including installed plugin code), statusline script,
+and 5 tracked keys from `~/.claude.json` (`mcpServers`, `autoUpdates`,
+`autoUpdatesProtectedForNative`, `showExpandedTodos`, `showSpinnerTree`).
+
+**Never synced (per-machine state):**
+- Credentials and secrets — hard-blocked by built-in denylist:
+  `.credentials.json`, `*.key`, `*.pem`, `.env*`, `*secret*`, `*token*`
+- Caches: `cache/`, `paste-cache/`, `downloads/`, `stats-cache.json`,
+  `mcp-needs-auth-cache.json`, `plugins/cache/`, `plugins/plugin-catalog-cache.json`,
+  `plugins/data/`
+- Per-machine runtime: `daemon*`, `tasks/`, `telemetry/`, `jobs/`, `security/`,
+  `security_warnings_state_*.json`, `*.bak.*`, `.last-cleanup`
+- Project + session history: `projects/`, `sessions/`, `history.jsonl`,
+  `file-history/`, `shell-snapshots/`, `session-env/`
+- `~/.claude/.claude-profile/backups/` (claude-profile owns this)
+- Most top-level `~/.claude.json` keys (`oauthAccount`, `projects`, `theme`,
+  `userID`, `firstStartTime`, etc.) — run `claude-profile describe` to see the
+  full list on your machine
+
+You can override either list with a repo-root `claude-profile.yaml`:
+
+```yaml
+include:
+  - "**"
+exclude:
+  - "projects/**"
+  - "sessions/**"
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `claude-profile init --git <url>` | Clone repo and register a profile on this machine |
+| `claude-profile sync` | Pull, merge, commit, push. Usually invoked by the hook |
+| `claude-profile status` | Show what sync would do; no writes |
+| `claude-profile diff <path>` | Unified diff between home and repo for one path |
+| `claude-profile describe [name]` | Inventory a profile: settings, hooks, MCP, commands, skills, agents, plugins, backups, and excluded `~/.claude.json` keys |
+| `claude-profile use <name>` | Switch active profile (always backs up first) |
+| `claude-profile list` | List registered + repo-only profiles |
+| `claude-profile adopt <name>` | Snapshot current `~/.claude/` into a new profile |
+| `claude-profile merge <source> --into <dest>` | Merge profiles (`prefer-dest` \| `prefer-source` \| `newer` \| `mark-conflicts`) |
+| `claude-profile backups` | List backup snapshots |
+| `claude-profile restore <profile> [ts]` | Restore a backup snapshot |
+| `claude-profile prune [--keep N]` | Delete old backups |
+| `claude-profile config <op> [key] [value]` | Per-machine config (get/set/unset) |
+| `claude-profile install-skill` | Install `/profile` skill + SessionStart/Stop hooks |
+
+---
+
+## Auto-sync
+
+`install-skill` wires two Claude Code hooks: a **SessionStart** hook that pulls the
+latest profile (3-second timeout, non-blocking) and a **Stop** hook that pushes any
+local changes in the background. Once installed you rarely need to run `sync` manually
+— changes flow between machines automatically each time Claude Code starts and stops.
+
+---
+
+## Conflicts
+
+When both machines edit the same file, the newer timestamp wins and the losing version
+is preserved at `profiles/<active>/.conflicts/<path>.<host>.<ts>` in the repo. No data
+is ever silently discarded.
+
+---
+
+## Per-machine config
+
+Machine-specific settings (which git remote to use, sync timeout, debounce window)
+live in `~/.claude-profile/config.json` and are never committed to the repo. Manage
+with `claude-profile config get/set/unset`.
+
+---
+
+## Docs
+
+- [Full documentation site](https://vshalpnjabi.github.io/claude-profile/) (quickstart, command reference, sync algorithm, configuration, FAQ)
+- [Design spec](docs/superpowers/specs/2026-05-24-claude-profile-design.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).