@tricknowtech/context 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @tricknowtech/context
+
+Carry a project's LLM context — memory, skills, instructions, and where you left off — between machines.
+
+Local-first: the store is a plain directory you commit to your repo, so context travels with the code. No account, no server, works offline. A hosted Tricknowtech remote is optional and comes later.
+
+```bash
+npx @tricknowtech/context init
+```
+
+## The problem
+
+Open the same project on a second machine and the assistant knows nothing. Your instruction files travel with the repo, but the parts that actually accumulate — the per-project memory, your custom skills, and the thread of what you were doing — live in `~/.claude` and never leave the machine that built them.
+
+## What it does
+
+`ctx init` creates `.contextsync/` and installs a `/context` slash command. From then on:
+
+```bash
+ctx push      # collect context into the store
+ctx pull      # restore it on another machine
+ctx status    # what changed since the last push
+```
+
+Commit `.contextsync/` and your teammates — and your other laptop — get the same context on clone.
+
+### It skips what git already carries
+
+Your `CLAUDE.md` is already in the repo, so copying it into the store would just create a second copy that drifts. The collector checks `git ls-files` and leaves tracked files alone. What it *does* capture is the part that never travels:
+
+| Store path | Comes from |
+|---|---|
+| `memory/` | `~/.claude/projects/<project-key>/memory/` |
+| `skills/` | `~/.claude/skills/` |
+| `agents/` | `~/.claude/agents/` |
+| `user/` | `~/.claude/CLAUDE.md`, `settings.json` |
+| `project/` | untracked instruction files in the repo |
+| `artifacts/` | derived indexes, opt-in (`--artifacts`) |
+| `handoff.json` | written by `/context push` |
+
+### Paths are rewritten on restore
+
+Claude Code names its per-project directories after the absolute project path — `/root/my-app` becomes `-root-my-app`. Clone the repo somewhere else and that key is wrong. The manifest stores paths as templates (`{userClaude}/projects/{cwdKey}/memory/…`) and `ctx pull` recomputes them for wherever the repo actually lives.
+
+### The handoff
+
+`/context push` asks the model to write `.contextsync/handoff.json` first — goal, decisions made, open threads, files touched, next step. Only the model has the conversation; only the CLI has the disk, so the slash command is the one place both are available.
+
+On the other machine, `/context pull` restores everything and reads the handoff back, so the new session starts oriented instead of blank.
+
+## Safety
+
+The store gets committed, and a committed credential is permanent — so `ctx push` scans everything first and **refuses** if it finds anything that looks like a secret:
+
+```
+Refusing to push — 2 possible secrets found:
+
+  user/settings.json:14  [assigned-secret]  wJal********MPLEK
+  memory/deploy.md:8     [aws-access-key-id]  AKIA********MPLE
+
+These would be committed to the repository and be very hard to remove.
+```
+
+`.env` files, `~/.claude/.credentials.json`, `.claude.json`, and private keys are never collected at all, at any tier.
+
+Session transcripts are excluded from local mode entirely. They run to hundreds of megabytes, are append-only, and carry the largest leak surface (full tool output). They will be supported through the hosted remote, where content-addressed chunking makes them practical.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `--artifacts` | include derived indexes (`graphify-out/`, etc.) |
+| `--dry-run` | show what would sync, write nothing |
+| `--force` | `init`: overwrite config · `pull`: overwrite differing files |
+| `--allow-secrets` | push despite scan hits — think first |
+
+`ctx pull` never overwrites a local file whose contents differ; it lists them and leaves them alone until you pass `--force`.
+
+## Configuration
+
+`.contextsync/config.json`:
+
+```json
+{
+  "projectId": "…",
+  "name": "my-app",
+  "rootHint": "/root/my-app",
+  "tiers": ["core", "handoff"],
+  "artifactPaths": ["graphify-out"],
+  "exclude": ["**/*.log"],
+  "remotes": {}
+}
+```
+
+## Programmatic use
+
+```ts
+import { collect, findProjectRoot, loadConfig, LocalStore } from '@tricknowtech/context'
+
+const root = findProjectRoot()!
+const cfg = loadConfig(root)!
+const { files, skippedTracked } = collect(root, cfg, ['core'])
+new LocalStore(root).write(files, root)
+```
+
+## License
+
+ISC © Tricknowtech