@korso/shepherd 0.6.2 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
 
-> **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
+> **New here?** The [developer quickstart](https://github.com/Korso-AI/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y --package=@korso/shepherd shepherd-mcp` with the env vars below.
 
 ---
 
@@ -20,7 +20,7 @@ The server is published to npm and runs via `npx` — no clone or build required
 (Node 18+):
 
 ```sh
-npx -y @korso/shepherd
+npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 You won't normally run that by hand; you put it in your MCP client config (below)
@@ -45,14 +45,14 @@ Missing either causes an immediate startup failure with a clear error on stderr
 listing which vars are absent. (No other var triggers this.)
 
 **Everything else is optional** — each identity field is resolved at startup as
-**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
+**env var → git detection → fallback**, so a plain `npx -y --package=@korso/shepherd shepherd-mcp` with
 just the two required vars produces a valid, fully-identified session. Set an
 override only to replace what's detected:
 
 | Variable | If omitted | Example |
 |---|---|---|
 | `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
-| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
+| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korso-AI/shepherd` |
 | `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
 | `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
 | `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
@@ -99,9 +99,22 @@ It delivers to an agent **while it's active**; an idle agent picks messages up t
 moment it next does anything. (Waking a fully-idle agent is out of scope — for
 Claude Code that needs Channels; Codex/Pi have no equivalent.)
 
-### Claude Code — `PreToolUse` hook
-
-`PreToolUse` fires before every tool, giving the most frequent passive delivery.
+**The hook also carries the unlinked-repo nudge.** The server instructions tell
+the agent to ask about linking on its first write in a new repo, but instructions
+sitting passively in context don't trigger themselves — an agent focused on the
+task can skip straight to editing. So on every invocation the hook also checks
+this repo's link state and, when the repo is **neither linked (`.shepherd`
+marker) nor declined**, injects a reminder to run `link`/`decline` — on
+`SessionStart` (front-loads the ask), right before a file-writing tool
+(`Edit`/`Write`/`MultiEdit`/`NotebookEdit`; read-only tools never nudge), and on
+tool-less events like Codex's `UserPromptSubmit` or a Pi turn. The
+nudge is advisory and self-extinguishing: the moment the repo is linked or
+declined it goes quiet, and like everything else here it fails open.
+
+### Claude Code — `PreToolUse` + `SessionStart` hooks
+
+`PreToolUse` fires before every tool, giving the most frequent passive delivery;
+`SessionStart` surfaces the link ask at the top of a session in an unlinked repo.
 The hook needs no arguments — it resolves the same default inbox dir the server
 uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
 
@@ -110,7 +123,7 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123"
@@ -118,11 +131,18 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
     }
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "npx -y --package=@korso/shepherd shepherd-inbox-hook" }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
+          { "type": "command", "command": "npx -y --package=@korso/shepherd shepherd-inbox-hook" }
         ]
       }
     ]
@@ -143,9 +163,9 @@ or MCP calls. Hooks must be enabled with `features.hooks = true`. In
 hooks = true
 
 [[hooks.UserPromptSubmit]]
-command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
+command = ["npx", "-y", "--package=@korso/shepherd", "shepherd-inbox-hook"]
 # On Windows use command_windows instead:
-# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
+# command_windows = ["cmd", "/c", "npx -y --package=@korso/shepherd shepherd-inbox-hook"]
 ```
 
 ### Pi — extension
@@ -161,8 +181,8 @@ cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extension
 ```
 
 It runs on every user turn (`before_agent_start`), drains the same inbox, and
-injects pending announcements. (Or load it ad hoc with
-`pi -e /abs/path/to/dist/inboxExtension.js`.)
+injects pending announcements plus the unlinked-repo nudge. (Or load it ad hoc
+with `pi -e /abs/path/to/dist/inboxExtension.js`.)
 
 ### Notes
 
@@ -191,7 +211,7 @@ line-continuation does not work). Minimal: just the two required vars (identity
 is auto-detected from git):
 
 ```powershell
-claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
+claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
@@ -204,7 +224,7 @@ Alternative — a `.mcp.json` at the **root of the repo you're working in**
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
@@ -228,7 +248,7 @@ The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` ar
 silently ignored). Either run `codex mcp add`:
 
 ```sh
-codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
+codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 …or add the table directly:
@@ -236,7 +256,7 @@ codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOK
 ```toml
 [mcp_servers.shepherd]
 command = "npx"
-args = ["-y", "@korso/shepherd"]
+args = ["-y", "--package=@korso/shepherd", "shepherd-mcp"]
 env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
 ```
 
@@ -249,7 +269,7 @@ Pi uses a JSON `mcpServers` block (project config overrides global):
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
@@ -260,6 +280,32 @@ Pi uses a JSON `mcpServers` block (project config overrides global):
 }
 ```
 
+### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+Cursor reads the same JSON `mcpServers` shape — global at `~/.cursor/mcp.json`,
+or per-project at `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "PROGRAM": "cursor"
+      }
+    }
+  }
+}
+```
+
+Confirm under **Settings → MCP** that `shepherd` is listed with its tools.
+Announcement push: Cursor has no hook equivalent (see the hooks above for
+Claude Code/Codex/Pi), so announcements arrive via the universal drainer — on
+the agent's next Shepherd tool call — rather than pushed between calls.
+
 ---
 
 ## 4. Verify the server starts (quick smoke test)
@@ -270,10 +316,10 @@ PowerShell (set env vars, then run):
 ```powershell
 $env:HUB_URL = "https://shepherd.example.com"
 $env:TEAM_TOKEN = "tok_abc123"
-npx -y @korso/shepherd
+npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
-bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
+bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y --package=@korso/shepherd shepherd-mcp`
 
 No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
 
@@ -298,7 +344,7 @@ Only needed if you're changing the MCP server itself. Clone the monorepo and
 point your client at a local build instead of npx:
 
 ```sh
-git clone https://github.com/Korsoai/shepherd.git
+git clone https://github.com/Korso-AI/shepherd.git
 cd shepherd
 npm install
 npm run build         # tsc -b — compiles the workspace for dev + tests

package/dist/inboxExtension.js

@@ -1,16 +1,59 @@
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
-function defaultInboxDir() {
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
   let base = "";
   try {
     base = homedir();
@@ -18,29 +61,78 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "declined");
 }
-function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+
+// src/linkNudge.ts
+var WRITE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+var LINK_NUDGE_TEXT = '[Shepherd] This repo is not linked to a Shepherd workspace and has not been declined. Before writing files here, call the shepherd `link` tool with no argument: it auto-links if the user belongs to exactly one workspace, or lists workspaces \u2014 then ask the user "Coordinate this repo with Shepherd? Which workspace?" and call `link <workspace>` with their answer, or `decline` if they say no. Ask at most once per repo.';
+function buildLinkNudge(cwd, toolName, deps = {}) {
+  try {
+    if (toolName !== void 0 && !WRITE_TOOLS.has(toolName)) return "";
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) return "";
+    if (readMarker(cwd) !== null) return "";
+    if (isDeclined(repoRoot, deps.declinedDir)) return "";
+    return LINK_NUDGE_TEXT;
+  } catch {
+    return "";
+  }
+}
+
+// src/inbox.ts
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -80,7 +172,7 @@ function shepherdInbox(pi) {
       const dir = process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
       const cwd = ctx?.cwd ?? process.cwd();
       const announcements = drainInbox(inboxFilePath(dir, cwd));
-      const content = formatInboxAnnouncements(announcements);
+      const content = [buildLinkNudge(cwd), formatInboxAnnouncements(announcements)].filter(Boolean).join("\n\n");
       if (!content) return void 0;
       return { message: { customType: "shepherd-inbox", content, display: true } };
     } catch {

package/dist/inboxHook.js

@@ -1,18 +1,61 @@
 #!/usr/bin/env node
 
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
-function defaultInboxDir() {
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
   let base = "";
   try {
     base = homedir();
@@ -20,29 +63,78 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "declined");
 }
-function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+
+// src/linkNudge.ts
+var WRITE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+var LINK_NUDGE_TEXT = '[Shepherd] This repo is not linked to a Shepherd workspace and has not been declined. Before writing files here, call the shepherd `link` tool with no argument: it auto-links if the user belongs to exactly one workspace, or lists workspaces \u2014 then ask the user "Coordinate this repo with Shepherd? Which workspace?" and call `link <workspace>` with their answer, or `decline` if they say no. Ask at most once per repo.';
+function buildLinkNudge(cwd, toolName, deps = {}) {
+  try {
+    if (toolName !== void 0 && !WRITE_TOOLS.has(toolName)) return "";
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) return "";
+    if (readMarker(cwd) !== null) return "";
+    if (isDeclined(repoRoot, deps.declinedDir)) return "";
+    return LINK_NUDGE_TEXT;
+  } catch {
+    return "";
+  }
+}
+
+// src/inbox.ts
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -74,8 +166,7 @@ function formatInboxAnnouncements(announcements) {
   }
   return lines.join("\n");
 }
-function buildHookOutput(rawStdin, inboxDir, drain = drainInbox) {
-  if (!inboxDir) return "";
+function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLinkNudge) {
   let input;
   try {
     input = JSON.parse(rawStdin);
@@ -83,13 +174,21 @@ function buildHookOutput(rawStdin, inboxDir, drain = drainInbox) {
     return "";
   }
   if (!input || typeof input.cwd !== "string" || input.cwd.length === 0) return "";
-  const announcements = drain(inboxFilePath(inboxDir, input.cwd));
-  const text = formatInboxAnnouncements(announcements);
-  if (!text) return "";
+  const parts = [];
+  const nudgeText = nudge(
+    input.cwd,
+    typeof input.tool_name === "string" ? input.tool_name : void 0
+  );
+  if (nudgeText) parts.push(nudgeText);
+  if (inboxDir) {
+    const text = formatInboxAnnouncements(drain(inboxFilePath(inboxDir, input.cwd)));
+    if (text) parts.push(text);
+  }
+  if (parts.length === 0) return "";
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: input.hook_event_name || "PreToolUse",
-      additionalContext: text
+      additionalContext: parts.join("\n\n")
     }
   });
 }

package/dist/index.js

@@ -783,7 +783,10 @@ function detectHuman(cwd = process.cwd()) {
     return null;
   }
   const name = runGit(cwd, ["config", "user.name"]);
-  if (name) return name;
+  if (name) {
+    const local = name.includes("@") ? name.split("@")[0] : name;
+    if (local) return local;
+  }
   const email = runGit(cwd, ["config", "user.email"]);
   if (email) {
     const local = email.split("@")[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",