@letta-ai/git-status 0.1.0

package/MOD.md

@@ -0,0 +1,57 @@
+---
+name: "@letta-ai/git-status"
+description: "Git branch, dirty/clean, file counts, and ahead/behind for the Letta Code statusline."
+---
+
+# Git status statusline mod semantics
+
+## When to use
+
+Use this mod when the user wants Letta Code's idle statusline to show git state:
+current branch, clean/dirty, changed-file counts, and ahead/behind vs upstream.
+Letta Code's default statusline shows no git information, so this is additive, not
+a replacement for existing git UI.
+
+## Behavior
+
+- Polls `git` outside the render path on a fixed interval (default 4 seconds).
+- Runs a single read-only command per poll: `git status --porcelain=v2 --branch
+  --untracked-files=all`, plus a `rev-parse --is-inside-work-tree` guard.
+- Reads the live working directory from the statusline render context (`ModContext.cwd`),
+  captured at render time, so polling follows the session's current directory rather than
+  the launch directory. The host `letta` object does not expose a workspace. Falls back to
+  `process.cwd()` until the first render.
+- Branch: from `# branch.head`; shows a short SHA (from `# branch.oid`) when detached.
+  Long names are truncated to 22 chars with a trailing `…` to avoid overflowing the row.
+- Ahead/behind: from `# branch.ab +A -B`; rendered as `↑A ↓B`, only when an upstream
+  exists and there is a non-zero delta.
+- File counts from porcelain v2 entries: `?` untracked → added; staged `A` → added;
+  `D` in the XY field → deleted; everything else changed → modified. Rendered as
+  `+added ~modified -deleted`.
+- Clean tree renders a check (`✓`).
+- Segment color: green when clean, yellow when dirty.
+- Clears the segment entirely when not inside a git work tree.
+- Renders agent name and model on the right so the row stays useful with no repo.
+
+## Platform assumptions
+
+Cross-platform. Requires `git` (with porcelain v2 support, git >= 2.11) on `PATH`.
+Uses `windowsHide` so no console window flashes on Windows.
+
+## Safety invariants
+
+- Renderer stays synchronous; all shelling happens in the poll interval.
+- Only read-only git commands are run; the mod never mutates the repository.
+- Git invocations use a short timeout and swallow errors, degrading to a cleared segment.
+- Timers and status values are cleaned up when the mod is disposed.
+- Optional UI APIs are capability-guarded (`ui.customStatuslineRenderer`, `ui.statusValues`).
+
+## Adaptation notes for agents
+
+- Keep polling lightweight; raise `REFRESH_MS` if a large repo makes `git status` slow.
+- To add line-level churn, layer in `git diff --numstat` / `--cached --numstat` and a
+  sparkline; this mod intentionally stays at the file + branch level.
+- The custom statusline owns the full idle row — if composing with other statusline data,
+  merge it into this renderer rather than registering a second renderer.
+- Porcelain v2 is required for the branch/ahead-behind headers; do not downgrade to v1
+  without re-deriving branch and upstream separately.

package/README.md

@@ -0,0 +1,72 @@
+# Git Status
+
+#git-status
+
+A Letta Code statusline mod that shows your current git state in the idle status row: branch, clean/dirty, changed-file counts, and how far you are ahead/behind upstream.
+
+Letta Code's default statusline has no git awareness — this fills that gap.
+
+## Install
+
+#install
+
+```
+letta install npm:@letta-ai/git-status
+```
+
+Then reload local mods:
+
+```
+/reload
+```
+
+## What it shows
+
+#what-it-shows
+
+A git segment on the left of the idle statusline, for example:
+
+```
+ main ↑2 +1 ~3 -1     Letta · claude-sonnet
+```
+
+- ` main` — current branch (short SHA when in detached HEAD; long names are truncated with `…`)
+- `↑2 ↓1` — commits ahead / behind the upstream branch (only shown when there's an upstream and a delta)
+- `+N` — untracked / newly added files
+- `~N` — modified files (staged or unstaged)
+- `-N` — deleted files
+
+When the working tree is clean it shows a check:
+
+```
+ main ✓
+```
+
+The segment is **green when clean** and **yellow when dirty**, so you can read tree state at a glance. The right side always shows the agent name and model.
+
+## Behavior
+
+#behavior
+
+- Polls `git status --porcelain=v2 --branch` every 4 seconds, outside the render path.
+- Reads from the agent's current workspace directory.
+- Clears the segment when not inside a git work tree.
+- A single git call provides branch, upstream, ahead/behind, and per-file status.
+
+## Safety
+
+#safety
+
+Mods are trusted local code. Review the source before installing third-party mods.
+
+This mod only runs read-only `git` commands; it never writes to your repository.
+
+If a mod breaks startup or command handling, recover with:
+
+```
+letta --no-mods
+# or
+LETTA_DISABLE_MODS=1 letta
+```
+
+See [MOD.md](./MOD.md) for the agent-facing behavioral contract.

package/mods/index.tsx

@@ -0,0 +1,238 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const REFRESH_MS = 4_000;
+const EXEC_TIMEOUT_MS = 1_500;
+// Long branch names can overflow narrow statuslines, so cap the displayed
+// length and add an ellipsis. The full name is never hidden in detached mode
+// (we already show a short SHA there).
+const MAX_BRANCH_CHARS = 22;
+
+function truncateBranch(name: string): string {
+  if (name.length <= MAX_BRANCH_CHARS) return name;
+  return `${name.slice(0, MAX_BRANCH_CHARS - 1)}…`;
+}
+
+interface GitState {
+  /** Current branch name (or short SHA when detached). */
+  branch: string;
+  /** True when in detached HEAD. */
+  detached: boolean;
+  /** Number of untracked / newly added files. */
+  added: number;
+  /** Number of modified (staged or unstaged) files. */
+  modified: number;
+  /** Number of deleted files. */
+  deleted: number;
+  /** Commits ahead of upstream. */
+  ahead: number;
+  /** Commits behind upstream. */
+  behind: number;
+  /** Whether an upstream is configured. */
+  hasUpstream: boolean;
+}
+
+const EMPTY_STATE: GitState = {
+  branch: "",
+  detached: false,
+  added: 0,
+  modified: 0,
+  deleted: 0,
+  ahead: 0,
+  behind: 0,
+  hasUpstream: false,
+};
+
+async function git(args: string[], cwd: string): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, {
+    cwd,
+    timeout: EXEC_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  return stdout;
+}
+
+async function readGitState(cwd: string): Promise<GitState | null> {
+  // Bail quietly if we are not inside a work tree.
+  try {
+    const inside = (
+      await git(["rev-parse", "--is-inside-work-tree"], cwd)
+    ).trim();
+    if (inside !== "true") return null;
+  } catch {
+    return null;
+  }
+
+  const state: GitState = { ...EMPTY_STATE };
+
+  // Use porcelain v2 with branch headers: a single call gives us branch,
+  // upstream, ahead/behind, and per-file status.
+  let porcelain = "";
+  try {
+    porcelain = await git(
+      ["status", "--porcelain=v2", "--branch", "--untracked-files=all"],
+      cwd,
+    );
+  } catch {
+    return state;
+  }
+
+  for (const line of porcelain.split("\n")) {
+    if (!line) continue;
+
+    if (line.startsWith("# branch.head ")) {
+      const head = line.slice("# branch.head ".length).trim();
+      if (head === "(detached)") {
+        state.detached = true;
+      } else {
+        state.branch = head;
+      }
+      continue;
+    }
+
+    if (line.startsWith("# branch.oid ") && state.detached) {
+      // Show a short SHA for detached HEAD.
+      const oid = line.slice("# branch.oid ".length).trim();
+      if (oid && oid !== "(initial)") state.branch = oid.slice(0, 7);
+      continue;
+    }
+
+    if (line.startsWith("# branch.ab ")) {
+      // Format: "# branch.ab +N -M"
+      const ab = line.slice("# branch.ab ".length).trim().split(" ");
+      const ahead = Number.parseInt(ab[0]?.replace("+", ""), 10);
+      const behind = Number.parseInt(ab[1]?.replace("-", ""), 10);
+      if (Number.isFinite(ahead)) state.ahead = ahead;
+      if (Number.isFinite(behind)) state.behind = behind;
+      state.hasUpstream = true;
+      continue;
+    }
+
+    // Untracked entries start with "? ".
+    if (line.startsWith("? ")) {
+      state.added += 1;
+      continue;
+    }
+
+    // Changed entries: "1" (ordinary) or "2" (renamed/copied). The XY field
+    // is the 2nd token (e.g. ".M", "M.", "MM", "D.", ".D").
+    if (line.startsWith("1 ") || line.startsWith("2 ")) {
+      const xy = line.split(" ")[1] ?? "..";
+      if (xy.includes("A")) {
+        // Staged additions count as "added".
+        state.added += 1;
+      } else if (xy.includes("D")) {
+        state.deleted += 1;
+      } else {
+        state.modified += 1;
+      }
+    }
+  }
+
+  return state;
+}
+
+function formatSegment(state: GitState): string {
+  const parts: string[] = [];
+
+  // Branch (truncated if long).
+  const rawBranch = state.branch || (state.detached ? "detached" : "?");
+  parts.push(` ${truncateBranch(rawBranch)}`);
+
+  // Ahead/behind vs upstream.
+  if (state.hasUpstream && (state.ahead || state.behind)) {
+    const ab: string[] = [];
+    if (state.ahead) ab.push(`↑${state.ahead}`);
+    if (state.behind) ab.push(`↓${state.behind}`);
+    parts.push(ab.join(""));
+  }
+
+  // File counts, or a clean marker.
+  const fileParts: string[] = [];
+  if (state.added) fileParts.push(`+${state.added}`);
+  if (state.modified) fileParts.push(`~${state.modified}`);
+  if (state.deleted) fileParts.push(`-${state.deleted}`);
+
+  if (fileParts.length > 0) {
+    parts.push(fileParts.join(" "));
+  } else {
+    parts.push("✓");
+  }
+
+  return parts.join(" ");
+}
+
+export default function activate(letta: any) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  let latest: GitState | null = null;
+  // The live working directory is provided by the statusline render context
+  // (ModContext.cwd), which tracks the session's current directory. The host
+  // `letta` object does not expose a workspace, so we capture cwd at render
+  // time and let the poll loop read the latest value.
+  let currentCwd = process.cwd();
+
+  const update = async () => {
+    if (!letta.capabilities.ui.statusValues) return;
+
+    let state: GitState | null = null;
+    try {
+      state = await readGitState(currentCwd);
+    } catch {
+      state = null;
+    }
+
+    latest = state;
+    if (!state) {
+      letta.ui.clearStatus("git");
+      return;
+    }
+
+    letta.ui.setStatus("git", formatSegment(state));
+  };
+
+  letta.ui.setStatuslineRenderer((context: any) => {
+    const { Box, Text } = context.components;
+    const model = context.model.displayName ?? context.model.id ?? "unknown";
+
+    // Track the live cwd from the render context so polling follows the
+    // session's current directory rather than the launch directory.
+    if (typeof context.cwd === "string" && context.cwd) {
+      currentCwd = context.cwd;
+    }
+
+    const dirty =
+      !!latest &&
+      latest.added + latest.modified + latest.deleted > 0;
+
+    return (
+      <Box justifyContent="space-between" width="100%">
+        <Box>
+          {context.statuses.git ? (
+            <Text color={dirty ? "yellow" : "green"}>
+              {context.statuses.git}
+            </Text>
+          ) : null}
+        </Box>
+        <Box>
+          <Text dimColor>
+            {context.agent.name ?? "Letta"}
+            {` · ${model}`}
+          </Text>
+        </Box>
+      </Box>
+    );
+  });
+
+  void update();
+  const timer = setInterval(() => void update(), REFRESH_MS);
+
+  return () => {
+    clearInterval(timer);
+    if (letta.capabilities.ui.statusValues) {
+      letta.ui.clearStatus("git");
+    }
+  };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@letta-ai/git-status",
+  "version": "0.1.0",
+  "description": "Letta Code statusline mod that shows the current git branch, dirty/clean state, file counts, and ahead/behind.",
+  "author": "christinatong",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "letta-package",
+    "letta-mod",
+    "letta-code",
+    "statusline",
+    "git"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letta-ai/mods.git",
+    "directory": "packages/git-status"
+  },
+  "files": [
+    "README.md",
+    "MOD.md",
+    "mods"
+  ],
+  "letta": {
+    "manifestVersion": 1,
+    "mods": ["./mods/index.tsx"],
+    "capabilities": ["ui.statusline", "ui.statusValues"],
+    "engines": {
+      "lettaCodeCli": ">=0.27.14"
+    }
+  }
+}