@phren/cli 0.1.53 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,261 +0,0 @@
1
- ---
2
- name: sync
3
- description: Sync your Claude skills and project config across machines using profiles.
4
- dependencies:
5
- - git
6
- ---
7
- # phren-sync - Profile-aware sync
8
-
9
- > Sync your Claude skills and project config across machines using profiles that control what goes where.
10
-
11
- Phren carries your skills and project config between machines. Profile-aware: he only syncs what belongs on this machine.
12
-
13
- ## Prerequisites
14
-
15
- This skill requires a phren repository. If you don't have one yet, see "New machine setup" at the bottom.
16
-
17
- **Expected structure:**
18
- ```
19
- ~/.phren/ # or wherever your phren repo lives
20
- global/ # skills and config for all projects
21
- skills/ # global skill files (.md)
22
- CLAUDE.md # global Claude instructions
23
- <project>/ # per-project config
24
- CLAUDE.md
25
- skills/
26
- summary.md
27
- profiles/ # machine profile definitions
28
- work.yaml
29
- personal.yaml
30
- machines.yaml # maps machine names to profiles
31
- ```
32
-
33
- If any of these are missing, the skill will tell you what to create and how.
34
-
35
- ## How it works
36
-
37
- Phren uses profiles to decide what goes where. A profile is a list of projects. A machine is mapped to a profile. When you sync, phren only brings over the projects in your machine's profile.
38
-
39
- ## Sync down (pull to this machine)
40
-
41
- When the user says "get my skills", "sync my config", "pull from phren", or just "phren-sync":
42
-
43
- ### 1. Find the phren directory
44
-
45
- ```bash
46
- PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
47
- ls "$PHREN_DIR" 2>/dev/null
48
- ```
49
-
50
- If the directory doesn't exist, tell the user:
51
- > "No phren repo found at ~/.phren. Clone yours with `git clone <your-repo-url> ~/.phren`, or set `PHREN_DIR` to point to a different location."
52
-
53
- ### 2. Figure out which machine this is
54
-
55
- ```bash
56
- cat ~/.phren/.machine-id 2>/dev/null || hostname
57
- ```
58
-
59
- If `~/.phren/.machine-id` doesn't exist, ask the user to pick a name:
60
- > "I need a machine name to look up your profile. What should I call this machine? (e.g. 'work-laptop', 'home-desktop')"
61
-
62
- Then save it:
63
- ```bash
64
- mkdir -p ~/.phren && echo "work-laptop" > ~/.phren/.machine-id
65
- ```
66
-
67
- ### 3. Look up the profile
68
-
69
- ```bash
70
- cat "$PHREN_DIR/machines.yaml"
71
- ```
72
-
73
- If the machine name isn't in `machines.yaml`, tell the user:
74
- > "Machine 'work-laptop' isn't in machines.yaml yet. Which profile should it use?"
75
- > Then show available profiles: `ls "$PHREN_DIR/profiles/"*.yaml`
76
-
77
- ```bash
78
- cat "$PHREN_DIR/profiles/<profile-name>.yaml"
79
- ```
80
-
81
- The profile YAML has:
82
- ```yaml
83
- name: work
84
- description: Work laptop setup
85
- projects:
86
- - myapp
87
- - api-server
88
- ```
89
-
90
- If no profiles exist yet, offer to create one with `phren-init`.
91
-
92
- ### 4. Pull latest
93
-
94
- ```bash
95
- cd "$PHREN_DIR" && git pull
96
- ```
97
-
98
- If this fails (not a git repo, no remote), tell the user. Don't silently skip.
99
-
100
- ### 5. Refresh the machine with the supported flow
101
-
102
- Run init against the pulled phren repo so hooks, MCP registration, and machine/profile wiring are refreshed:
103
-
104
- ```bash
105
- PHREN_PATH="$PHREN_DIR" phren init -y
106
- ```
107
-
108
- If the user is in an untracked repo afterward, tell them to open a session there and let the agent ask, or run `phren add` from that directory.
109
-
110
- Only mention `phren link` if the user is explicitly repairing an older pre-init install.
111
-
112
- ### 6. Build the context file
113
-
114
- Write `~/.phren-context.md` with a summary of what's active on this machine:
115
-
116
- ```markdown
117
- # Phren context: <machine-name> (<profile-name>)
118
-
119
- Machine: <machine-name>
120
- Profile: <profile-name>
121
- Last synced: <date>
122
-
123
- ## Active projects
124
- - myapp: Description from summary.md
125
- - api-server: Description from summary.md
126
-
127
- ## Global skills
128
- phren-sync, phren-init, phren-consolidate, phren-discover
129
- ```
130
-
131
- Pull project descriptions from each project's `summary.md` if it exists.
132
-
133
- ### 7. Rebuild MEMORY.md
134
-
135
- Regenerate `~/.claude/projects/*/memory/MEMORY.md` with cross-project awareness from the active profile. Pull key facts from each project's `summary.md`.
136
-
137
- ### 8. Check project health
138
-
139
- After syncing, check each active project in the phren directory for missing files. Print a one-line status per project. Informational only, does not block the sync.
140
-
141
- **Required files** (warn if missing):
142
- - `summary.md`: project description used by context file and memory
143
- - `CLAUDE.md`: project-level Claude instructions
144
-
145
- **Recommended files** (note if missing, don't warn):
146
- - `tasks.md`: persistent task queue
147
- - `FINDINGS.md`: captured session findings
148
-
149
- For each project in the profile, check `$PHREN_DIR/<project>/` for these files and print:
150
-
151
- ```
152
- Project health:
153
- + my-app: all files present
154
- ~ backend: missing recommended: FINDINGS.md
155
- ! new-project: missing required: summary.md, CLAUDE.md
156
- ```
157
-
158
- Legend: `+` all good, `~` missing recommended files, `!` missing required files.
159
-
160
- Skip the "global" entry since it has a different structure. Only check actual project directories.
161
-
162
- ### 9. Report
163
-
164
- ```
165
- phren-sync down: <machine-name> (<profile-name>)
166
-
167
- Synced:
168
- - myapp (CLAUDE.md + 3 skills)
169
- - api-server (CLAUDE.md + 1 skill)
170
- - global (CLAUDE.md + 11 skills)
171
-
172
- Skipped (not in profile):
173
- - old-project
174
-
175
- Project health:
176
- + myapp: all files present
177
- ~ api-server: missing recommended: FINDINGS.md
178
-
179
- Context: ~/.phren-context.md updated
180
- ```
181
-
182
- ## Sync up (push changes back)
183
-
184
- When the user says "sync this back", "push to phren", "save this to my phren":
185
-
186
- ### 1. Find what changed
187
-
188
- ```bash
189
- diff "$PHREN_DIR/<project>/CLAUDE.md" ./<project-path>/CLAUDE.md
190
- diff -r "$PHREN_DIR/<project>/skills/" ./<project-path>/.claude/skills/
191
-
192
- Remember: `.claude/skills/` is a generated mirror. The source-of-truth lives in phren `skills/`, and the project mirror also includes inherited global skills after resolution.
193
- ```
194
-
195
- If files are symlinked (same inode), they're already in sync. Just commit from the phren directory.
196
-
197
- If files are regular copies that differ, copy them back:
198
- ```bash
199
- cp <changed-file> "$PHREN_DIR/<project>/<corresponding-path>"
200
- ```
201
-
202
- ### 2. Commit and push
203
-
204
- ```bash
205
- cd "$PHREN_DIR"
206
- git add -A
207
- git commit -m "<project> updates from <machine-name>"
208
- git push
209
- ```
210
-
211
- ## Conversational shortcuts
212
-
213
- These should work naturally in conversation:
214
-
215
- | User says | What to do |
216
- |-----------|-----------|
217
- | "add myapp to my work profile" | Edit the profile YAML, add to projects list, commit |
218
- | "show me my personal profile" | Read and display the profile YAML |
219
- | "what's on this machine?" | Read and display `~/.phren-context.md` |
220
- | "remove old-project from work" | Edit the profile YAML, commit |
221
- | "switch to personal profile" | Update the machine mapping in `machines.yaml`, re-run sync down |
222
- | "create a new profile called travel" | Create a new profile YAML with empty projects list, ask what to include |
223
-
224
- ## New machine setup
225
-
226
- First time on a new machine:
227
-
228
- ```bash
229
- # 1. Clone your phren repo
230
- git clone <your-repo-url> ~/.phren
231
-
232
- # 2. Name this machine
233
- mkdir -p ~/.phren && echo "my-machine-name" > ~/.phren/.machine-id
234
-
235
- # 3. Map it to a profile in machines.yaml
236
- # Add a line: my-machine-name: work
237
-
238
- # 4. Run phren-sync
239
- ```
240
-
241
- If you don't have a phren repo yet, start with `phren-init` to create one from scratch.
242
-
243
- ## Conflict resolution
244
-
245
- When two machines edit the same phren file before syncing, `git pull` will hit a merge conflict. Here's how to handle each file type:
246
-
247
- **tasks.md**: Take both changes. Task items from both machines are valid. Concat them, deduplicate if needed, commit.
248
-
249
- **FINDINGS.md**: Take both changes. Keep entries in chronological order. If both machines added entries on the same date, interleave or group them under the same date heading.
250
-
251
- **CLAUDE.md**: Manual merge. Ask the user which version they want, or show both and let them pick. These files contain preferences and instructions where intent matters, so don't auto-resolve.
252
-
253
- **skills/ files**: If the same skill was edited on both machines, show the user a diff and let them choose. If different skills were edited, git handles this automatically (no conflict).
254
-
255
- **General approach**: Run `git pull --rebase` during sync. If conflicts appear, tell the user which files conflict and apply the rules above. Don't silently drop changes from either side.
256
-
257
- ## Related skills
258
-
259
- - `phren-init`: create a new project or set up phren from scratch
260
- - `add_finding()`: capture findings via MCP (synced across machines by `push_changes()`)
261
- - `phren-consolidate`: synthesize findings across projects