@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.
package/dist/status.js CHANGED
@@ -14,6 +14,7 @@ import { assessSyncOutage } from "./shared/governance.js";
14
14
  import { resolveRuntimeProfile } from "./runtime-profile.js";
15
15
  import { renderPhrenArt } from "./phren-art.js";
16
16
  import { RESET, BOLD, DIM, GREEN, YELLOW, RED, CYAN } from "./shell/render.js";
17
+ import { storeWeight } from "./store-weight.js";
17
18
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
18
19
  function readPackageVersion() {
19
20
  try {
@@ -100,6 +101,14 @@ export async function runStatus() {
100
101
  // Phren path and config
101
102
  console.log(` ${DIM}path${RESET} ${phrenPath}`);
102
103
  console.log(` ${DIM}mode${RESET} ${manifest?.installMode || "unknown"}`);
104
+ try {
105
+ const w = storeWeight(phrenPath, profile);
106
+ const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}k` : String(n));
107
+ console.log(` ${DIM}weight${RESET} ${k(w.findings)} words of findings · ${k(w.reference)} archived · ${k(w.tasks)} in tasks · ${k(w.skills)} in skills · CLAUDE.md ${w.globalClaude} words`);
108
+ }
109
+ catch (err) {
110
+ logger.debug("status", `weight: ${errorMessage(err)}`);
111
+ }
103
112
  if (manifest?.workspaceRoot) {
104
113
  console.log(` ${DIM}workspace${RESET} ${manifest.workspaceRoot}`);
105
114
  }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * How much text a store carries, by kind. None of the tidying phren does stays
3
+ * done unless the weight is visible, so `phren status` prints this and doctor
4
+ * warns when the parts an agent pays for every session have grown.
5
+ */
6
+ import { homePath } from "./phren-paths.js";
7
+ export interface StoreWeight {
8
+ projects: number;
9
+ /** Words in FINDINGS.md files (active findings). */
10
+ findings: number;
11
+ /** Words under reference/, the archive. */
12
+ reference: number;
13
+ tasks: number;
14
+ skills: number;
15
+ /** Words in the global CLAUDE.md every session loads. */
16
+ globalClaude: number;
17
+ }
18
+ export declare function storeWeight(phrenPath: string, profile?: string): StoreWeight;
19
+ /** Median tokens the prompt hook injected per prompt, from the live lookup log's hook events. */
20
+ export declare function medianHookInjectionTokens(phrenPath: string, lastPrompts?: number): {
21
+ prompts: number;
22
+ medianTokens: number;
23
+ };
24
+ export declare const CONTEXT_COST_LIMITS: {
25
+ globalClaudeWords: number;
26
+ medianInjectionTokens: number;
27
+ };
28
+ export { homePath };
@@ -0,0 +1,80 @@
1
+ /**
2
+ * How much text a store carries, by kind. None of the tidying phren does stays
3
+ * done unless the weight is visible, so `phren status` prints this and doctor
4
+ * warns when the parts an agent pays for every session have grown.
5
+ */
6
+ import * as fs from "fs";
7
+ import * as path from "path";
8
+ import { getProjectDirs, homePath } from "./phren-paths.js";
9
+ function words(file) {
10
+ try {
11
+ return fs.readFileSync(file, "utf8").split(/\s+/).filter(Boolean).length;
12
+ }
13
+ catch {
14
+ return 0;
15
+ }
16
+ }
17
+ function walkWords(dir, match) {
18
+ let total = 0;
19
+ const stack = [dir];
20
+ while (stack.length) {
21
+ const current = stack.pop();
22
+ let entries = [];
23
+ try {
24
+ entries = fs.readdirSync(current, { withFileTypes: true });
25
+ }
26
+ catch {
27
+ continue;
28
+ }
29
+ for (const e of entries) {
30
+ if (e.name === ".git" || e.name === "node_modules")
31
+ continue;
32
+ const full = path.join(current, e.name);
33
+ if (e.isDirectory())
34
+ stack.push(full);
35
+ else if (e.isFile() && match(e.name))
36
+ total += words(full);
37
+ }
38
+ }
39
+ return total;
40
+ }
41
+ export function storeWeight(phrenPath, profile = "") {
42
+ const projectDirs = getProjectDirs(phrenPath, profile).filter((d) => path.basename(d) !== "global");
43
+ const w = { projects: projectDirs.length, findings: 0, reference: 0, tasks: 0, skills: 0, globalClaude: words(path.join(phrenPath, "global", "CLAUDE.md")) };
44
+ for (const dir of projectDirs) {
45
+ w.findings += words(path.join(dir, "FINDINGS.md"));
46
+ w.tasks += words(path.join(dir, "tasks.md"));
47
+ w.reference += walkWords(path.join(dir, "reference"), (n) => n.endsWith(".md"));
48
+ w.skills += walkWords(path.join(dir, "skills"), (n) => n.endsWith(".md"));
49
+ }
50
+ w.skills += walkWords(path.join(phrenPath, "global", "skills"), (n) => n.endsWith(".md"));
51
+ return w;
52
+ }
53
+ /** Median tokens the prompt hook injected per prompt, from the live lookup log's hook events. */
54
+ export function medianHookInjectionTokens(phrenPath, lastPrompts = 100) {
55
+ const log = path.join(phrenPath, ".runtime", "lookup-events.jsonl");
56
+ let lines = [];
57
+ try {
58
+ lines = fs.readFileSync(log, "utf8").trim().split("\n").filter(Boolean);
59
+ }
60
+ catch {
61
+ return { prompts: 0, medianTokens: 0 };
62
+ }
63
+ const perPrompt = new Map();
64
+ for (const line of lines.slice(-2000)) {
65
+ try {
66
+ const e = JSON.parse(line);
67
+ if (e.source !== "hook" || !e.at)
68
+ continue;
69
+ const key = `${e.session ?? ""}@${e.at}`;
70
+ perPrompt.set(key, (perPrompt.get(key) ?? 0) + Math.ceil(((e.snippet ?? "").length + 40) / 4));
71
+ }
72
+ catch { /* skip a torn line */ }
73
+ }
74
+ const sizes = [...perPrompt.values()].slice(-lastPrompts).sort((a, b) => a - b);
75
+ if (!sizes.length)
76
+ return { prompts: 0, medianTokens: 0 };
77
+ return { prompts: sizes.length, medianTokens: sizes[Math.floor(sizes.length / 2)] };
78
+ }
79
+ export const CONTEXT_COST_LIMITS = { globalClaudeWords: 600, medianInjectionTokens: 1500 };
80
+ export { homePath };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.53",
3
+ "version": "0.2.1",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,99 +1,35 @@
1
- # User-level instructions
1
+ # Instructions for the agent
2
2
 
3
- <!-- Copy this file to your personal phren instance's global/CLAUDE.md and fill in your own preferences. -->
4
- <!-- This becomes ~/.claude/CLAUDE.md after syncing. Claude reads it at the start of every session. -->
3
+ <!-- phren copies this to ~/.phren/global/CLAUDE.md and links it as ~/.claude/CLAUDE.md. Every session reads it, so keep it short and addressed to the agent. Fill in "How I work"; leave the rest. -->
5
4
 
6
- ## Memory
5
+ ## Memory lives in phren
7
6
 
8
- **Use Phren for all knowledge persistence, not Claude Code's built-in auto memory.** Do not write to `~/.claude/projects/.../memory/` files. Instead:
7
+ phren already knows this user's projects. Ask it before asking them to repeat themselves, and tell it what you learn as you go, not at the end.
9
8
 
10
- - Save knowledge → `add_finding(project, finding)`
11
- - Recall knowledge → `search_knowledge(query)`
12
- - Track tasks → `add_task()` / `complete_task()` / `get_tasks()`
13
- - Track sessions → `session_start()` / `session_end()`
9
+ - Recall: `search_knowledge(query)`, then `get_memory_detail(id)` for the full entry. `get_project_summary(project)` when starting on a project.
10
+ - Save: `add_finding(project, finding, findingType?)` the moment you learn something non-obvious that would save time next session. `kind: "note"` for a lightweight daily note.
11
+ - Tasks: `get_tasks(project)`, `add_task(project, item)`, `manage_task(action: "complete", project, item)`. Tasks live in phren, not in chat.
12
+ - Sessions: `session(action: "start", project)` for substantial work, `session(action: "end", summary)` when done. Hooks do not do this for you.
13
+ - Everything else: `phren_admin(action: …)`; `phren_admin(action: "list_actions")` lists it.
14
+ - Do not write to `~/.claude/projects/*/memory/`. phren is the memory.
14
15
 
15
- ## How I Work
16
+ Worth saving: decisions and why, pitfalls with the fix, patterns that worked, measurements. Not worth saving: secrets or personal data, one-off facts, narration of what happened, anything obvious from the code. Fewer, sharper entries beat volume.
16
17
 
17
- <!-- Your non-negotiable rules. Examples: -->
18
- <!-- "Write human from the start. No em dashes. No double hyphens. No AI buzzwords." -->
19
- <!-- "Think visually. If it looks like a template, it's not done." -->
20
- <!-- "Finish the job. Changelog, README, tests. Don't wait to be asked." -->
18
+ ## How I work
21
19
 
22
- ## Skills
23
-
24
- These skills are available as a full set via phren, or individually from the Claude skills marketplace. You don't need the full phren setup to use skills marked with (standalone).
25
-
26
- ### Phren skills (manage your project store)
27
-
28
- | Skill | What it does |
29
- |-------|-------------|
30
- | `/phren-sync` | Pull phren to a new machine or push config changes back to the repo |
31
- | `/phren-init` | Scaffold a new project with summary, CLAUDE.md, tasks |
32
- | `/phren-discover` | Research what's missing in a project and surface gaps and opportunities |
33
- | `/phren-consolidate` | Find patterns across all project FINDINGS.md files |
34
- | `/phren-profiles` | Manages machine-to-profile mapping |
35
-
36
- ### Your own skills
37
-
38
- Put personal workflow skills in `~/.phren/global/skills/` and list them here. See [phren](https://github.com/alaarab/phren) for examples.
39
-
40
- <!-- Example:
41
- | `/humanize` | Strip AI language from writing and code |
42
- | `/release` | Version bump, changelog, tag, publish |
43
- -->
44
-
45
- ## Agent coordination
46
-
47
- <!-- If you use team agents, document your coordination pattern here. Example: -->
48
- <!-- "Never use fire-and-forget background agents. Always use TeamCreate/TaskCreate/SendMessage." -->
49
-
50
- - Team agents follow the same phren rules as the primary agent.
51
- - Before handing work back or stopping, tell phren about non-obvious bugs, patterns, tradeoffs, or decisions with `add_finding(...)`.
52
- - Do not wait for the user to explicitly say "save this as a finding" if the insight will matter next session.
53
-
54
- ## Project store
20
+ <!-- Your rules, in your words. Examples: -->
21
+ <!-- - Lead with the answer. Don't over-engineer. Scope to what I asked. -->
22
+ <!-- - Draft emails and comms for me, don't send. -->
23
+ <!-- - Save findings as we go, not at the end. -->
55
24
 
56
- In shared mode, skills and project config live in `~/.phren` (or wherever `PHREN_DIR` points). This is a git repo that syncs across machines using profiles.
57
-
58
- If you're using `phren init --mode project-local`, the root is `<repo>/.phren` instead. Project-local mode does not use profiles, machine mappings, or global hooks.
59
-
60
- - `~/.phren/global/`: skills and config that apply everywhere
61
- - `~/.phren/<project>/`: per-project CLAUDE.md, skills, tasks, findings
62
- - `~/.phren/profiles/`: YAML files mapping project sets to machine roles
63
- - `~/.phren/machines.yaml`: maps machine hostnames to profiles
64
-
65
- Run `/phren-sync` to pull everything down or push changes back.
66
-
67
- ## MCP tools
68
-
69
- The phren MCP server is running. Phren already knows a lot. Ask him before asking the user to repeat themselves.
70
-
71
- - **At session start:** ask phren what's active: `list_projects()`, then `get_project_summary(name)` for the relevant project
72
- - **When the user mentions a project, codebase, or task:** ask phren first: `search_knowledge(query)` before asking questions
73
- - **When the user asks about commands, architecture, conventions, or past decisions:** check with phren: `search_knowledge(query)`
74
- - **When the user mentions a task or todo:** ask phren what's tracked: `get_tasks(project)`
75
- - **When you discover a non-obvious pattern, bug, or workaround:** tell phren immediately: `add_finding(project, insight)`
76
- - **When the user says they want to do something later:** tell phren to remember it: `add_task(project, item)` instead of listing it in chat
77
- - **When a task is finished:** tell phren it's done: `complete_task(project, item)` without being asked
78
-
79
- **What NOT to tell phren:**
80
- - Credentials, API keys, tokens, passwords, or anything that looks like a secret
81
- - Personal or sensitive data: SSNs, financial info, health info, PII of any kind
82
- - One-off facts that won't apply next session ("the server was down today")
83
- - Narration of what happened ("fixed the login bug"): only save the actual insight
84
- - Things obvious from reading the code or docs
85
-
86
- If you're unsure whether something is worth telling phren, skip it. High-signal entries beat volume.
87
-
88
- The goal: phren should already have the context before the user has to explain it. Tasks stay in files, not buried in chat history.
25
+ ## Skills
89
26
 
90
- ## Machine context
27
+ `/phren-sync`, `/phren-init`, `/phren-discover`, `/phren-consolidate`, `/phren-profiles` manage the store. Your own skills live in `~/.phren/global/skills/` and are listed by `phren skills list`; invoke them by name rather than expecting them to appear as memory.
91
28
 
92
- <!-- Claude reads this at session start to know what's active on this machine. -->
93
- <!-- Auto-generated by /phren-sync. Don't edit manually. -->
29
+ ## Team agents
94
30
 
95
- Read `~/.phren-context.md` at the start of every session for machine-specific context: which profile is active, which projects are linked, and when the last sync happened.
31
+ Every agent follows these rules, and tells phren about non-obvious findings before handing work back.
96
32
 
97
- ## Without MCP server
33
+ ## Where things are
98
34
 
99
- If the MCP server isn't available, phren still helps. Claude reads `~/.phren-context.md` and per-project memory files from `~/.claude/projects/` for context, then fetches details directly from `~/.phren/project-name/` as needed. No MCP required, phren just works a bit more quietly.
35
+ `~/.phren` (or `$PHREN_PATH`) is a git repo: `global/` for everything-everywhere, `<project>/` for each project's CLAUDE.md, findings, tasks and skills, `profiles/` and `machines.yaml` for which projects belong on which machine. `phren doctor` explains anything that is off. If the MCP server is not running, phren still injects context through hooks; the CLI (`phren search`, `phren add-finding`) does the rest.
@@ -1,121 +1,29 @@
1
1
  ---
2
2
  name: phren-profiles
3
- description: Manage machine-to-profile and profile-to-project mappings in phren.
3
+ description: Manage machine-to-profile and profile-to-project mappings in phren. Multi-machine users only.
4
4
  dependencies:
5
5
  - git
6
6
  ---
7
- # phren-profiles - Manage your profiles
7
+ # /phren-profiles
8
8
 
9
- > **Multi-machine only.** This skill is for users who sync phren across multiple machines and need to control which projects appear where. If you only use one machine, you can skip this -- `phren-sync` handles everything you need.
9
+ A profile is a YAML file in `~/.phren/profiles/` with a `projects:` list. `machines.yaml` maps machine names to profiles. On each machine, phren links only the projects in that machine's profile. Single-machine users can ignore all of this.
10
10
 
11
- > Add projects to profiles, move projects between profiles, create new profiles, and check what's in each one.
11
+ ## Look
12
12
 
13
- Manage which projects appear on which machines by editing your profile definitions. Each machine maps to one profile, and each profile is a list of projects.
14
-
15
- ## Prerequisites
16
-
17
- You need a phren repo. The profiles live in `~/.phren/profiles/` and machine mappings live in `~/.phren/machines.yaml`.
18
-
19
- ```
20
- ~/.phren/
21
- profiles/
22
- work.yaml
23
- personal.yaml
24
- machines.yaml
25
- ```
26
-
27
- If you don't have a phren repo yet, start with `phren-init`.
28
-
29
- ## What's a profile?
30
-
31
- A profile is a YAML file listing projects for a machine role. Example:
32
-
33
- ```yaml
34
- name: work
35
- description: Work laptop with company projects
36
- projects:
37
- - global
38
- - my-api
39
- - frontend
40
- ```
41
-
42
- When you sync on a machine mapped to this profile, only those projects appear. Personal projects stay off work machines.
43
-
44
- ## How to use it
45
-
46
- ### "Add a project to a profile"
47
-
48
- User says: "add my-project to my work profile"
49
-
50
- 1. Find the profile file: `~/.phren/profiles/work.yaml`
51
- 2. Read it and find the `projects:` list
52
- 3. Add the project name if it's not already there
53
- 4. Commit the change
54
-
55
- ### "Create a new profile"
56
-
57
- User says: "create a new profile called staging"
58
-
59
- 1. Create a new file: `~/.phren/profiles/staging.yaml`
60
- 2. Fill it with the required structure:
61
-
62
- ```yaml
63
- name: staging
64
- description: Staging servers and experiments
65
- projects:
66
- - global
13
+ ```bash
14
+ phren config machines # machine → profile
15
+ phren config profiles # profile → projects
67
16
  ```
68
17
 
69
- 3. Ask which projects should be in this new profile (can add more later)
70
- 4. Commit the file
71
-
72
- ### "Show me what's in a profile"
73
-
74
- User says: "what's in my personal profile?"
75
-
76
- 1. Find `~/.phren/profiles/personal.yaml`
77
- 2. Read it and display the projects list
78
-
79
- ### "Move a project between profiles"
80
-
81
- User says: "move my-project from personal to work"
82
-
83
- 1. Find `~/.phren/profiles/personal.yaml` and remove the project
84
- 2. Find `~/.phren/profiles/work.yaml` and add the project
85
- 3. Commit both changes
86
-
87
- ### "Set this machine's profile"
18
+ ## Change
88
19
 
89
- User says: "this machine is my work laptop"
90
-
91
- 1. Get the current machine name: `cat ~/.phren/.machine-id` or `hostname`
92
- 2. Ask which profile to use (show available profiles from `~/.phren/profiles/`)
93
- 3. Add/update the line in `~/.phren/machines.yaml`: `work-laptop: work`
94
- 4. Commit the change
95
- 5. Run `phren-sync` to activate
96
-
97
- ### "List my profiles"
98
-
99
- If the user asks what profiles exist:
100
-
101
- 1. List all files in `~/.phren/profiles/`
102
- 2. For each one, read the name and description fields
103
- 3. Show which machine is mapped to each profile (from `machines.yaml`)
104
-
105
- ## After making changes
106
-
107
- Always commit to the phren git repo:
108
-
109
- ```bash
110
- cd ~/.phren
111
- git add profiles/ machines.yaml
112
- git commit -m "update profiles"
113
- git push # only if remote exists
114
- ```
20
+ - **Move this machine to a profile:** `phren profile switch <name>` (then `phren init -y` to relink).
21
+ - **Add a project to a profile:** edit `~/.phren/profiles/<name>.yaml`, add the project name under `projects:`, commit.
22
+ - **New profile:** copy an existing YAML, rename `name:`, set its `projects:`, commit. Then map a machine to it.
23
+ - **Register a project that is on this machine but not linked:** `phren add <path>`.
115
24
 
116
- Then suggest running `phren-sync` to activate changes on this machine.
25
+ Commit and push the store after changes (`/phren-sync` push), so the other machines pick them up.
117
26
 
118
- ## Related skills
27
+ ## Conversational shortcuts
119
28
 
120
- - `phren-sync`: sync your profiles to this machine and activate them
121
- - `phren-init`: create a new project or bootstrap phren from scratch
29
+ "add X to my work profile", "what's on this machine?", "switch to personal" all map to the commands above. Show the YAML you changed.