starling-ai 0.0.2 → 0.0.4

package/README.md

@@ -10,7 +10,7 @@ Agent session manager for Claude Code and OpenAI Codex. Starling discovers local
 
 - Discover Claude Code and Codex sessions from local session files.
 - Browse sessions by catalog, project, or recent activity.
-- Create hierarchical catalogs such as `work/research/paper`.
+- Create catalogs such as `paper-review`, with optional hierarchical paths when needed.
 - Add session metadata, titles, tags, notes, and catalog assignments.
 - Resume Claude Code and Codex sessions from one command.
 - Track token usage when it is available in the session file.
@@ -31,6 +31,19 @@ The npm package is named `starling-ai`, but the installed command is:
 starling --help
 ```
 
+The npm install step also installs the bundled Starling skill to:
+
+```text
+~/.codex/skills/starling/SKILL.md
+~/.claude/skills/starling/SKILL.md
+```
+
+If npm lifecycle scripts were disabled with `--ignore-scripts`, install the skill manually from the package directory:
+
+```bash
+npm explore -g starling-ai -- npm run install:skill
+```
+
 Starling requires Node.js 20 or newer.
 
 ## Quick Start
@@ -56,27 +69,27 @@ starling resume <session-id>
 Create a catalog and add a session:
 
 ```bash
-starling catalog create research/paper
-starling catalog add research/paper <session-id> --title "Figure review"
+starling catalog create paper-review
+starling catalog add paper-review <session-id> --title "Figure review"
 ```
 
 Launch Codex and assign the new session to a catalog:
 
 ```bash
-starling run --catalog research/paper codex
+starling run --catalog paper-review codex
 ```
 
 Launch Claude Code with a Starling config profile:
 
 ```bash
-starling run --config ds --catalog research/paper claude
+starling run --config ds --catalog paper-review claude
 ```
 
 Starling options must be placed before the agent name. Everything after `claude` or `codex` is passed directly to that agent:
 
 ```bash
-starling run --catalog research/paper codex exec "summarize this repo"
-starling run --catalog research/paper claude --dangerously-skip-permissions
+starling run --catalog paper-review codex exec "summarize this repo"
+starling run --catalog paper-review claude --dangerously-skip-permissions
 ```
 
 ## Commands
@@ -88,7 +101,7 @@ starling session ls
 starling session ls --all
 starling session ls --agent claude
 starling session ls --cataloged
-starling session ls --catalog research/paper
+starling session ls --catalog paper-review
 starling session show <session-id>
 starling session resume <session-id>
 starling session meta <session-id> --title "New title" --tags review,important
@@ -100,8 +113,8 @@ starling session delete <session-id> --yes
 Catalog assignment can also be managed from the session namespace:
 
 ```bash
-starling session catalog add <session-id> research/paper --title "Important run"
-starling session catalog remove <session-id> research/paper
+starling session catalog add <session-id> paper-review --title "Important run"
+starling session catalog remove <session-id> paper-review
 starling session catalog clear <session-id>
 ```
 
@@ -113,6 +126,7 @@ starling catalog create parent/child/grandchild
 starling catalog create child --parent parent
 starling catalog ls
 starling catalog tree
+starling catalog tree --sessions
 starling catalog show <catalog>
 starling catalog add <catalog> <session-id>
 starling catalog detach <catalog> <session-id>
@@ -189,8 +203,8 @@ starling model add demo --agent codex \
 Use a profile when launching an agent:
 
 ```bash
-starling run --config demo --catalog research/paper codex
-starling run --config ds --catalog research/paper claude
+starling run --config demo --catalog paper-review codex
+starling run --config ds --catalog paper-review claude
 ```
 
 If `--config` is not provided, Starling uses the agent's normal default configuration.
@@ -243,7 +257,7 @@ The repository includes a VS Code extension in `vscode-extension/`.
 
 The Starling sidebar contains three views:
 
-- Catalog: hierarchical catalog tree with sessions.
+- Catalog: hierarchical catalog tree, with sessions shown on request.
 - Projects: project directory tree with session counts.
 - Sessions: recent sessions with incremental loading.
 

package/dist/index.js

@@ -683,15 +683,21 @@ function removeSpace(id) {
   const idx = store.spaces.findIndex((s) => s.id === id || s.name === id);
   if (idx === -1) return false;
   const space = store.spaces[idx];
-  for (const b of store.bookmarks) {
-    b.space_ids = b.space_ids.filter((sid) => sid !== space.id);
-  }
-  for (const s of store.spaces) {
-    if (s.parent_id === space.id) {
-      s.parent_id = space.parent_id;
+  const idsToRemove = /* @__PURE__ */ new Set([space.id]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const candidate of store.spaces) {
+      if (candidate.parent_id && idsToRemove.has(candidate.parent_id) && !idsToRemove.has(candidate.id)) {
+        idsToRemove.add(candidate.id);
+        changed = true;
+      }
     }
   }
-  store.spaces.splice(idx, 1);
+  for (const b of store.bookmarks) {
+    b.space_ids = b.space_ids.filter((sid) => !idsToRemove.has(sid));
+  }
+  store.spaces = store.spaces.filter((s) => !idsToRemove.has(s.id));
   saveStore(store);
   return true;
 }
@@ -1546,9 +1552,9 @@ ${chalk4.yellow(`Pins in ${row.name} (${row.id})`)}`);
       }
     }
   });
-  space.command("tree").description("Display catalogs as a hierarchical tree").action(() => {
+  space.command("tree").description("Display catalogs as a hierarchical tree").option("--sessions", "show sessions assigned to each catalog").action((opts) => {
     const spaces = listSpaces();
-    const bookmarks = listBookmarks();
+    const bookmarks = opts.sessions ? listBookmarks() : [];
     console.log(formatSpaceTree(spaces, bookmarks));
   });
   space.command("add <catalog> <session-id>").description("Add a session to a catalog").option("-t, --title <title>", "pin title when creating a new pin").option("--tags <tags>", "comma-separated tags when creating a new pin").action(async (catalog, sessionId, opts) => {
@@ -2982,6 +2988,7 @@ function registerRunCommand(program2) {
     const beforeRun = hookRun ? /* @__PURE__ */ new Map() : await snapshotSessions(provider);
     const beforeRunProjectFiles = provider === "claude" && !hookRun ? snapshotProjectSessions(normalizedCwd) : /* @__PURE__ */ new Map();
     const cleanupRunState = async () => {
+      syncClaudeProfileSettingsFromRunSettings(resolvedConfig, hookRun?.settingsPath ?? null);
       cleanupClaudeRunHookSettings(hookRun);
       await cleanupCodexRunConfig(codexConfig);
       restoreCodexDefaultConfig(codexDefaultSnapshot);
@@ -3207,6 +3214,38 @@ function cleanupClaudeRunHookSettings(hookRun) {
     }
   }
 }
+var CLAUDE_SETTINGS_SYNC_KEYS = [
+  "permissions",
+  "projects",
+  "trust",
+  "trustedProjects",
+  "enableAllProjectMcpServers",
+  "enabledMcpjsonServers",
+  "disabledMcpjsonServers"
+];
+function syncClaudeProfileSettingsFromRunSettings(sourceConfigPath, runSettingsPath) {
+  if (!sourceConfigPath || !runSettingsPath || !existsSync6(runSettingsPath)) return false;
+  const sourceExt = extname2(sourceConfigPath).toLowerCase();
+  if (sourceExt !== ".json" && sourceExt !== ".jsonc") return false;
+  try {
+    const sourceSettings = readSettingsJsonObject(sourceConfigPath, sourceExt === ".jsonc");
+    const runSettings = readSettingsJsonObject(runSettingsPath, false);
+    if (!sourceSettings || !runSettings) return false;
+    let changed = false;
+    for (const key of CLAUDE_SETTINGS_SYNC_KEYS) {
+      if (!Object.prototype.hasOwnProperty.call(runSettings, key)) continue;
+      if (jsonStable(sourceSettings[key]) === jsonStable(runSettings[key])) continue;
+      sourceSettings[key] = cloneJsonValue(runSettings[key]);
+      changed = true;
+    }
+    if (!changed) return false;
+    atomicWriteJSON(sourceConfigPath, sourceSettings);
+    return true;
+  } catch (error) {
+    console.error(chalk6.yellow(`Could not sync Claude settings to ${sourceConfigPath}: ${String(error)}`));
+    return false;
+  }
+}
 async function createCodexRunConfig(configPath) {
   if (!configPath) {
     return null;
@@ -3658,14 +3697,24 @@ function readSessionIdFromHookEntry(value) {
 function readClaudeSettingsObject(configPath) {
   if (!configPath) return {};
   try {
-    const raw = readFileSync5(configPath, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (isRecord4(parsed)) return parsed;
+    const parsed = readSettingsJsonObject(configPath, extname2(configPath).toLowerCase() === ".jsonc");
+    if (parsed) return parsed;
   } catch {
     console.log(chalk6.yellow("Could not add Claude SessionStart hook because settings is not parseable JSON."));
   }
   return null;
 }
+function readSettingsJsonObject(filePath, allowComments) {
+  const raw = readFileSync5(filePath, "utf-8");
+  const parsed = JSON.parse(allowComments ? stripJsonComments(raw) : raw);
+  return isRecord4(parsed) ? parsed : null;
+}
+function jsonStable(value) {
+  return JSON.stringify(value);
+}
+function cloneJsonValue(value) {
+  return value === void 0 ? void 0 : JSON.parse(JSON.stringify(value));
+}
 function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -4694,7 +4743,7 @@ function escapeRegex(value) {
 // src/index.ts
 var program = new Command7();
 program.enablePositionalOptions();
-program.name("starling").description("Agent session manager \u2014 discover, pin, and organize AI coding sessions").version("0.1.0");
+program.name("starling").description("Agent session manager \u2014 discover, pin, and organize AI coding sessions").version("0.0.4");
 registerSessionCommand(program);
 registerPinCommand(program);
 registerSpaceCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starling-ai",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Agent session manager — discover, bookmark, and organize AI coding sessions",
   "type": "module",
   "repository": {
@@ -12,6 +12,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "scripts/install-agent-skills.js",
     "package.json",
     "README.md",
     "LICENSE"
@@ -19,6 +21,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node scripts/install-agent-skills.js",
+    "install:skill": "node scripts/install-agent-skills.js",
     "prepack": "npm run build",
     "test": "vitest run",
     "lint": "tsc --noEmit"

package/scripts/install-agent-skills.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const source = join(packageRoot, "skills", "starling", "SKILL.md");
+const targets = [
+  join(homedir(), ".codex", "skills", "starling", "SKILL.md"),
+  join(homedir(), ".claude", "skills", "starling", "SKILL.md"),
+];
+
+try {
+  if (!existsSync(source)) {
+    console.warn(`[starling] Codex skill not found in package: ${source}`);
+    process.exit(0);
+  }
+
+  for (const target of targets) {
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    console.log(`[starling] Installed skill: ${target}`);
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.warn(`[starling] Could not install skills: ${message}`);
+}

package/skills/starling/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: starling-agent-session
+description: Use when working with Starling, the local agent session manager for Claude Code and Codex: organizing sessions into catalogs, managing projects/session, launching agents with catalog assignment, configuring Claude/Codex profiles.
+---
+
+# Starling
+
+Starling is a local session manager for Claude Code and Codex. It discovers session files, groups sessions by project, organizes them into catalogs, stores metadata under `~/.starling`, and provides a VS Code sidebar.
+
+
+## Catalogs
+
+Use one plain catalog name in examples unless explaining hierarchy:
+
+```bash
+starling catalog create paper-review
+starling catalog add paper-review <session-id> --title "Figure review"
+starling catalog tree
+starling catalog show paper-review
+```
+
+Hierarchy is path-based:
+
+```bash
+starling catalog create research/paper
+starling catalog create child --parent research
+```
+
+`research/paper` means catalog `paper` under parent catalog `research`; it is not a single catalog name.
+
+Useful catalog operations:
+
+```bash
+starling catalog ls
+starling catalog show <catalog>
+starling catalog detach <catalog> <session-id>
+starling catalog clear <catalog>
+starling catalog rename <catalog> <new-name>
+starling catalog delete <catalog>
+```
+
+Deleting a catalog recursively deletes child catalogs from Starling metadata. It does not delete real session files.
+
+## Sessions
+
+Common session commands:
+
+```bash
+starling session ls
+starling session ls --all
+starling session ls --cataloged
+starling session ls --catalog paper-review
+starling session show <session-id>
+starling resume <session-id>
+```
+
+Manage catalog assignment from the session namespace:
+
+```bash
+starling session catalog add <session-id> paper-review --title "Important run"
+starling session catalog remove <session-id> paper-review
+starling session catalog clear <session-id>
+```
+
+Use 13-character session ID display when changing UI or tables, unless full IDs are required.
+
+## Projects And Index
+
+Project views are built from the local session index by default:
+
+```bash
+starling project ls
+starling project ls --all
+starling project show /path/to/project
+starling session index status
+starling session index rebuild
+starling session index clear
+```
+
+If project output is stale, rebuild the index. If performance is being investigated, compare indexed and scan modes:
+
+```bash
+starling project ls --refresh-index
+starling project ls --no-index
+```
+
+## Running Agents
+
+Starling arguments go before the agent name. Agent arguments go after the agent name and should be passed through unchanged:
+
+```bash
+starling run --catalog paper-review codex
+starling run --catalog paper-review codex exec "summarize this repo"
+starling run --config ds --catalog paper-review claude
+starling run --catalog paper-review claude --dangerously-skip-permissions
+```
+
+If `--config` is omitted, Starling should use the agent's normal default configuration and must not overwrite default Codex or Claude config files.
+
+## Model Profiles
+
+Profiles live under:
+
+```text
+~/.starling/settings/claude/<name>.json
+~/.starling/settings/codex/<name>.json
+```
+
+List profiles:
+
+```bash
+starling model ls
+starling model ls --agent claude
+starling model ls --agent codex
+```
+
+Create profiles:
+
+```bash
+starling model add ds --agent claude --model deepseek-v4-pro --base-url https://api.example.com --api-key "$API_KEY"
+starling model add demo --agent codex --model gpt-5.2 --base-url https://api.example.com/v1 --api-key "$OPENAI_API_KEY" --reasoning high --wire-api responses
+```
+
+Codex profiles use JSON with `auth` and `config`. Starling converts them into temporary Codex config for a run.
+
+## VS Code Extension
+
+Extension source is in:
+
+```text
+vscode-extension/
+```
+
+Compile before claiming extension changes work:
+
+```bash
+cd /data20T/dev/Starling/vscode-extension
+npm run compile
+```
+
+The sidebar has three views in this order:
+
+```text
+Catalog
+Projects
+Sessions
+```
+
+The extension calls the `starling` CLI. If VS Code cannot find it, use the install prompt or set `starling.cliPath` to an absolute path.
+
+## Development And Release
+
+For local development:
+
+```bash
+cd /data20T/dev/Starling
+npm install
+npm run build
+npm run lint
+npm test
+npm link
+```
+
+For testing the published package:
+
+```bash
+npm uninstall -g starling-ai
+npm install -g starling-ai
+starling --version
+```
+
+Publishing uses tags:
+
+```bash
+git tag vX.Y.Z
+git tag vsx-vX.Y.Z
+git push origin vX.Y.Z vsx-vX.Y.Z
+```
+
+`vX.Y.Z` triggers npm publish. `vsx-vX.Y.Z` triggers VS Code Marketplace publish. A GitHub Release can include both assets:
+
+```bash
+npm pack --pack-destination .
+cd vscode-extension && npx @vscode/vsce package
+gh release create vX.Y.Z ../starling-ai-X.Y.Z.tgz starling-ai-X.Y.Z.vsix --title "vX.Y.Z" --generate-notes
+```
+
+If `gh release create` fails with a 403 while `GITHUB_TOKEN` is set, try:
+
+```bash
+env -u GITHUB_TOKEN gh release create ...
+```
+
+## Guardrails
+
+- Do not remove or rewrite user data in `~/.starling`, `~/.claude`, or `~/.codex` unless explicitly requested.
+- Do not let `starling run --config <name> codex` mutate the user's default `~/.codex/config.toml`.
+- Keep examples with a single catalog name unless the task is specifically about hierarchy.
+- When changing CLI behavior, update README, tests, and `dist/index.js`.
+- When changing extension behavior, update `vscode-extension/package.json` contributions if needed and run `npm run compile`.