ei-tui 0.1.10 → 0.1.13

package/src/integrations/claude-code/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Claude Code Integration Types
+ *
+ * These types represent the data structures read from Claude Code's storage.
+ * Sessions are stored as JSONL files in ~/.claude/projects/<encoded-path>/<uuid>.jsonl
+ *
+ * The encoded path replaces '/' with '-', so /home/user/myapp → -home-user-myapp.
+ */
+
+// ============================================================================
+// Reader Interface
+// ============================================================================
+
+export interface IClaudeCodeReader {
+  getSessions(): Promise<ClaudeCodeSession[]>;
+  getMessagesForSession(sessionId: string): Promise<ClaudeCodeMessage[]>;
+}
+
+// ============================================================================
+// Raw JSONL Record Types
+// ============================================================================
+
+/**
+ * Common envelope fields present on most records.
+ */
+interface ClaudeCodeRecordBase {
+  type: string;
+  uuid?: string;
+  parentUuid?: string | null;
+  sessionId?: string;
+  cwd?: string;
+  timestamp?: string;
+  isSidechain?: boolean;
+}
+
+/**
+ * user record — a message the human typed.
+ */
+export interface ClaudeCodeUserRecord extends ClaudeCodeRecordBase {
+  type: "user";
+  message: {
+    role: "user";
+    content: string;
+  };
+  uuid: string;
+  sessionId: string;
+  cwd: string;
+  timestamp: string;
+}
+
+/**
+ * assistant record — Claude's response.
+ * content is an array of blocks; we extract "text" blocks only.
+ */
+export interface ClaudeCodeAssistantRecord extends ClaudeCodeRecordBase {
+  type: "assistant";
+  message: {
+    model: string;
+    role: "assistant";
+    content: ClaudeCodeContentBlock[];
+  };
+  uuid: string;
+  sessionId: string;
+  cwd: string;
+  timestamp: string;
+  slug?: string;
+}
+
+export type ClaudeCodeContentBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "tool_use"; [key: string]: unknown }
+  | { type: string; [key: string]: unknown };
+
+/**
+ * summary record — compaction checkpoint with compressed history.
+ * We skip these for import (not conversational content).
+ */
+export interface ClaudeCodeSummaryRecord extends ClaudeCodeRecordBase {
+  type: "summary";
+  summary: string;
+}
+
+// Types we explicitly skip:
+// - file-history-snapshot: git working tree state
+// - system: slash commands, local_command records
+// - progress: hook progress events
+// - tool_use / tool_result: internal tool plumbing (only in transcripts/)
+
+export type ClaudeCodeRecord =
+  | ClaudeCodeUserRecord
+  | ClaudeCodeAssistantRecord
+  | ClaudeCodeSummaryRecord
+  | ClaudeCodeRecordBase; // catch-all for skipped types
+
+// ============================================================================
+// Cleaned Session / Message Types (for Ei consumption)
+// ============================================================================
+
+/**
+ * A Claude Code session (one JSONL file = one session).
+ */
+export interface ClaudeCodeSession {
+  /** UUID from the filename, e.g. "0da9e1e8-187f-40f9-a66b-c7f1ebf2a72e" */
+  id: string;
+  /** Working directory when the session was started */
+  cwd: string;
+  /** Derived title: last segment of cwd (e.g. "ei" from "/Users/foo/Projects/Personal/ei") */
+  title: string;
+  /** ISO timestamp of the first message */
+  firstMessageAt: string;
+  /** ISO timestamp of the last message */
+  lastMessageAt: string;
+}
+
+/**
+ * A single user↔assistant exchange, cleaned for Ei.
+ */
+export interface ClaudeCodeMessage {
+  id: string;
+  sessionId: string;
+  role: "user" | "assistant";
+  /** Concatenated text blocks only — tool calls, thinking, snapshots are stripped */
+  content: string;
+  timestamp: string;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** The single persona name for all Claude Code sessions */
+export const CLAUDE_CODE_PERSONA_NAME = "Claude Code";
+
+/** Topic groups assigned to Claude Code session topics */
+export const CLAUDE_CODE_TOPIC_GROUPS = ["General", "Coding", "Claude Code"];
+
+/**
+ * Minimum session age before we import it.
+ * Mirrors OpenCode's 20-minute rule — gives the session time to "settle."
+ */
+export const MIN_SESSION_AGE_MS = 20 * 60 * 1000;
+
+// ============================================================================
+// Human Settings Shape (mirrors OpenCodeSettings in core/types.ts)
+// ============================================================================
+
+/**
+ * Stored under human.settings.claudeCode
+ *
+ * ⚠️  ADDING A NEW FIELD HERE?
+ * If it's runtime-managed (not user-editable), you MUST also add it to the
+ * claudeCode reconstruction block in settingsFromYAML() in:
+ *   tui/src/util/yaml-serializers.ts
+ * Otherwise it will be silently wiped every time the user saves /settings.
+ * Same rule applies to any future integration settings (Cursor, etc.).
+ */
+export interface ClaudeCodeSettings {
+  integration?: boolean;
+  polling_interval_ms?: number;  // Default: 1800000 (30 min)
+  last_sync?: string;            // ISO timestamp
+  processed_sessions?: Record<string, string>; // sessionId → ISO timestamp of last import
+}

package/src/integrations/opencode/importer.ts

@@ -32,6 +32,7 @@ export interface OpenCodeImporterOptions {
   stateManager: StateManager;
   interface?: Ei_Interface;
   reader?: IOpenCodeReader;
+  signal?: AbortSignal;
 }
 
 // =============================================================================
@@ -94,7 +95,7 @@ function filterRelevantMessages(messages: OpenCodeMessage[]): OpenCodeMessage[]
 export async function importOpenCodeSessions(
   options: OpenCodeImporterOptions
 ): Promise<ImportResult> {
-  const { stateManager, interface: eiInterface } = options;
+  const { stateManager, interface: eiInterface, signal } = options;
   const reader = options.reader ?? await createOpenCodeReader();
 
   const result: ImportResult = {
@@ -110,6 +111,8 @@ export async function importOpenCodeSessions(
   // Always runs (cheap), so session titles stay current regardless of
   // whether we process messages this cycle.
   const allSessions = await reader.getSessionsUpdatedSince(new Date(0));
+
+  if (signal?.aborted) return result;
   const primarySessions = allSessions.filter(s => !s.parentId);
 
   for (const session of primarySessions) {
@@ -156,6 +159,7 @@ export async function importOpenCodeSessions(
     // Nothing new to process — bump last_sync and return
     console.log(`[OpenCode] All sessions processed, nothing new since extraction_point`);
     return result;
+  if (signal?.aborted) return result;
   }
 
   console.log(
@@ -171,6 +175,7 @@ export async function importOpenCodeSessions(
     // Empty session — mark processed and advance
     updateExtractionState(stateManager, targetSession);
     return result;
+  if (signal?.aborted) return result;
   }
 
   // ─── Step 4: Resolve agents → personas, group by persona ID ────────
@@ -241,8 +246,10 @@ export async function importOpenCodeSessions(
         messages_analyze: toAnalyze,
       };
 
-      queueAllScans(context, stateManager);
-      result.extractionScansQueued += 4;
+      if (!signal?.aborted) {
+        queueAllScans(context, stateManager);
+        result.extractionScansQueued += 4;
+      }
     }
   }
 

package/src/prompts/generation/persona.ts

@@ -138,9 +138,11 @@ ${schemaFragment}`;
     userPrompt += `## User's Topics (PRESERVE EXACTLY, add more if fewer than 3)\n`;
     for (const topic of data.existing_topics ?? []) {
       if (topic.name?.trim()) {
-        userPrompt += `- ${topic.name}`;
-        if (topic.description) userPrompt += `: ${topic.description}`;
-        userPrompt += `\n`;
+        userPrompt += `- ${topic.name}\n`;
+        if (topic.perspective) userPrompt += `  perspective: ${topic.perspective}\n`;
+        if (topic.approach) userPrompt += `  approach: ${topic.approach}\n`;
+        if (topic.personal_stake) userPrompt += `  personal_stake: ${topic.personal_stake}\n`;
+        if (topic.sentiment !== undefined) userPrompt += `  sentiment: ${topic.sentiment}\n`;
       }
     }
     userPrompt += `\n`;

package/src/prompts/generation/types.ts

@@ -10,7 +10,7 @@ export interface PersonaGenerationPromptData {
   long_description?: string;
   short_description?: string;
   existing_traits?: Array<{ name?: string; description?: string; sentiment?: number; strength?: number }>;
-  existing_topics?: Array<{ name?: string; description?: string; sentiment?: number; exposure_current?: number; exposure_desired?: number }>;
+  existing_topics?: Array<{ name?: string; perspective?: string; approach?: string; personal_stake?: string; sentiment?: number; exposure_current?: number; exposure_desired?: number }>;
 }
 
 export interface PersonaGenerationResult {

package/src/prompts/human/fact-scan.ts

@@ -98,9 +98,9 @@ The JSON format is:
 {
   "facts": [
     {
-        "type_of_fact": "Birthday|User's Name|Location|see above",
-        "value_of_fact": "May 26th, 1984|Samwise|Seattle|etc.",
-        "reason": "User stated...|User implied...|User responded..."
+        "type_of_fact": "The Fact Type from above",
+        "value_of_fact": "The exact value of the fact",
+        "reason": "The justification of including this specific fact"
     }
   ]
 }
@@ -140,9 +140,9 @@ Scan the "Most Recent Messages" for FACTS about the human user.
 {
   "facts": [
     {
-        "type_of_fact": "Birthday|Name|etc.",
-        "value_of_fact": "May 26th, 1984|Samwise|etc.",
-        "reason": "User stated..."
+        "type_of_fact": "The Fact Type from above",
+        "value_of_fact": "The exact value of the fact",
+        "reason": "The justification of including this specific fact"
     }
   ]
 }

package/src/prompts/human/person-scan.ts

@@ -57,9 +57,9 @@ The JSON format is:
 {
   "people": [
     {
-        "type_of_person": "Father|Friend|Love Interest|Unknown|etc.",
-        "name_of_person": "Bob|Alice|Charles|Name Unknown|etc.",
-        "reason": "User stated...|Assumed from..."
+        "type_of_person": "The relationship from the list above",
+        "name_of_person": "The person's name",
+        "reason": "The justification of including this specific person"
     }
   ]
 }
@@ -97,9 +97,9 @@ Scan the "Most Recent Messages" for PEOPLE mentioned by the human user.
 {
   "people": [
     {
-        "type_of_person": "Father|Friend|Love Interest|Unknown|etc.",
-        "name_of_person": "Bob|Alice|Charles|Name Unknown|etc.",
-        "reason": "User stated..."
+        "type_of_person": "The relationship from the list above",
+        "name_of_person": "The person's name",
+        "reason": "The justification of including this specific person"
     }
   ]
 }

package/src/prompts/human/topic-scan.ts

@@ -81,9 +81,9 @@ The JSON format is:
 {
   "topics": [
     {
-        "type_of_topic": "Interest|Goal|Dream|Conflict|Concern|etc.",
-        "type_of_topic": "Interest|Goal|Dream|Conflict|Concern|etc.",
+        "type_of_topic": "The Topic Type from the list above",
         "value_of_topic": "<actual topic from the conversation>",
+        "reason": "The justification of including this specific topic"
     }
   ]
 }
@@ -123,9 +123,9 @@ Scan the "Most Recent Messages" for TOPICS of interest to the human user.
 {
   "topics": [
     {
-        "type_of_topic": "Interest|Goal|Dream|etc.",
+        "type_of_topic": "The Topic Type from the list above",
         "value_of_topic": "<actual topic from the conversation>",
-        "reason": "User stated..."
+        "reason": "The justification of including this specific topic"
     }
   ]
 }

package/src/prompts/human/trait-scan.ts

@@ -63,9 +63,9 @@ The JSON format is:
 {
   "traits": [
     {
-        "type_of_trait": "Personality Pattern|Communication Style|etc.",
-        "value_of_trait": "Introverted|Assertive|etc.",
-        "reason": "User stated...|Assumed from..."
+        "type_of_trait": "The type of trait from the list above",
+        "value_of_trait": "A short description of the trait",
+        "reason": "The justification of including this specific trait"
     }
   ]
 }
@@ -103,9 +103,9 @@ Scan the "Most Recent Messages" for TRAITS of the human user.
 {
   "traits": [
     {
-        "type_of_trait": "Personality Pattern|Communication Style|etc.",
-        "value_of_trait": "Introverted|Assertive|etc.",
-        "reason": "User stated..."
+        "type_of_trait": "The type of trait from the list above",
+        "value_of_trait": "A short description of the trait",
+        "reason": "The justification of including this specific trait"
     }
   ]
 }

package/src/prompts/persona/traits.ts

@@ -76,8 +76,8 @@ ${formatTraitsForPrompt(data.current_traits)}
 \`\`\`json
 [
   {
-    "name": "Concise",
-    "description": "User asked me to keep responses shorter",
+    "name": "A one- or two-word Title for the trait",
+    "description": "A brief instruction on how the trait is exhibited",
     "sentiment": 0.3,
     "strength": 0.7
   }

package/src/prompts/response/sections.ts

@@ -319,6 +319,20 @@ export function buildSystemKnowledgeSection(isTUI: boolean): string {
 - Hover over a persona to see controls: pause, edit (Pencil), archive, delete (Trash)
 - Click a persona to switch conversations
 - The [+] button creates new personas`;
+  const externalImportNotes = isTUI ? `
+
+### Coding Agent Integrations
+Ei can silently read session histories from AI coding tools and build memories from them — so you learn who the human works with, what projects they care about, and what they've been building, without them having to relay it manually.
+
+Both integrations are enabled here in settings. Look for the \`opencode\` or \`claudeCode\` section and set \`integration: true\`.
+
+#### OpenCode
+When enabled, Ei reads OpenCode's session history and builds a persona for each AI agent the human works with (Sisyphus, Oracle, etc.). Each session becomes a topic on that persona, so Ei can discuss the work in context.
+
+The connection also runs the other direction: running \`ei --install\` in the terminal registers Ei as a tool inside both OpenCode and Claude Code at the same time. Once installed, those coding agents can query Ei's memory directly — facts, traits, topics, people, quotes — giving them persistent knowledge about the human across sessions.
+
+#### Claude Code
+When enabled, Ei reads Claude Code's session history (stored in \`~/.claude/projects/\`) and creates a single "Claude Code" persona representing those conversations. Sessions become topics, and Ei learns from the work without the human having to explain it.` : "";
 
   return `# System Knowledge
 
@@ -364,6 +378,7 @@ The human can view and edit all of this by ${seeHumanDataAction}.
 - Configure LLM providers (local or cloud)
 - Set up device sync (encrypted backup to restore on other devices)
 - Adjust ceremony timing (overnight persona evolution)
+${externalImportNotes}
 
 ### Tips You Can Share
 - If they want to talk to a persona privately, tell them about the "Groups" functionality

package/src/storage/interface.ts

@@ -6,4 +6,6 @@ export interface Storage {
   load(): Promise<StorageState | null>;
   moveToBackup(): Promise<void>;
   loadBackup(): Promise<StorageState | null>;
+  /** Save a rolling backup of state with a local timestamp filename. Prunes oldest if over limit. */
+  saveRollingBackup(state: StorageState, maxBackups: number): Promise<void>;
 }

package/src/storage/local.ts

@@ -81,4 +81,9 @@ export class LocalStorage implements Storage {
       (e.name === "QuotaExceededError" || e.name === "NS_ERROR_DOM_QUOTA_REACHED")
     );
   }
+  /** No-op in browser — rolling backups are TUI-only (filesystem required). */
+  async saveRollingBackup(_state: StorageState, _maxBackups: number): Promise<void> {
+    // Intentional no-op: localStorage has no directory/file concept.
+    // The Processor gates this call with `this.isTUI` so it never runs in the browser.
+  }
 }

package/tui/README.md

@@ -99,6 +99,19 @@ All commands start with `/`. Append `!` to any command as a shorthand for `--for
 | `Ctrl+E` | Open `$EDITOR` (preserves current input) |
 | `PageUp / PageDown` | Scroll message history |
 
+# Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EI_DATA_PATH` | `~/.local/share/ei` | Path to Ei's persistent data directory. Set this to keep multiple profiles or point to a shared/synced folder. |
+| `XDG_DATA_HOME` | `~/.local/share` | XDG base directory. Ignored if `EI_DATA_PATH` is set. |
+| `EI_SYNC_USERNAME` | — | Username for remote sync. If set at startup, bootstraps sync credentials automatically (useful for dotfiles/scripts). |
+| `EI_SYNC_PASSPHRASE` | — | Passphrase for remote sync. Paired with `EI_SYNC_USERNAME`. |
+| `EDITOR` / `VISUAL` | `vi` | Editor opened by `/details`, `/me`, `/settings`, `/context`, `/quotes`, etc. Falls back to `VISUAL` if `EDITOR` is unset. |
+
+> **Tip**: `tail -f $EI_DATA_PATH/tui.log` to watch live debug output.
+
+
 # Development
 
 ## Requirements

package/tui/src/index.tsx

@@ -1,5 +1,25 @@
 import { render } from "@opentui/solid";
 import { App } from "./app";
+import { InstanceLock } from "./util/instance-lock";
+import { FileStorage } from "./storage/file";
+
+const storage = new FileStorage(Bun.env.EI_DATA_PATH);
+const lock = new InstanceLock(storage.getDataPath());
+const lockResult = await lock.acquire();
+
+if (!lockResult.acquired) {
+  process.stderr.write(
+    `\nEi cannot start: another instance is already running.\n` +
+    `  PID:     ${lockResult.pid}\n` +
+    `  Started: ${lockResult.started}\n` +
+    `  Lock:    ${storage.getDataPath()}/ei.lock\n\n` +
+    `Close the other instance first, or delete the lock file if it is stale.\n\n`
+  );
+  process.exit(1);
+}
+
+// Release lock when the app exits (keyboard context calls process.exit(0) on normal quit)
+process.on("exit", () => { void lock.release(); });
 
 render(App, {
   exitOnCtrlC: false,

package/tui/src/storage/file.ts

@@ -1,15 +1,16 @@
 import type { StorageState } from "../../../src/core/types";
 import type { Storage } from "../../../src/storage/interface";
 import { join } from "path";
-import { mkdir, rename, unlink } from "fs/promises";
+import { mkdir, rename, unlink, readdir } from "fs/promises";
 
 const STATE_FILE = "state.json";
 const BACKUP_FILE = "state.backup.json";
+const BACKUPS_DIR = "backups";
 const LOCK_TIMEOUT_MS = 5000;
 const LOCK_RETRY_DELAY_MS = 50;
 
 export class FileStorage implements Storage {
-  private dataPath: string;
+  private readonly dataPath: string;
 
   constructor(dataPath?: string) {
     if (dataPath) {
@@ -22,6 +23,10 @@ export class FileStorage implements Storage {
     }
   }
 
+  getDataPath(): string {
+    return this.dataPath;
+  }
+
   async isAvailable(): Promise<boolean> {
     try {
       await this.ensureDataDir();
@@ -101,6 +106,38 @@ export class FileStorage implements Storage {
 
     return null;
   }
+  async saveRollingBackup(state: StorageState, maxBackups: number): Promise<void> {
+    const backupsPath = join(this.dataPath, BACKUPS_DIR);
+    await mkdir(backupsPath, { recursive: true });
+
+    // Filename is local timestamp: YYYY-MM-DDTHH-MM-SS (colons replaced for FS compat)
+    const now = new Date();
+    const pad = (n: number) => String(n).padStart(2, "0");
+    const name = [
+      now.getFullYear(),
+      "-", pad(now.getMonth() + 1),
+      "-", pad(now.getDate()),
+      "T", pad(now.getHours()),
+      "-", pad(now.getMinutes()),
+      "-", pad(now.getSeconds()),
+    ].join("") + ".json";
+
+    const destPath = join(backupsPath, name);
+    await this.atomicWrite(destPath, JSON.stringify(state, null, 2));
+
+    // Prune: keep only the newest maxBackups files
+    const entries = await readdir(backupsPath);
+    const jsonFiles = entries
+      .filter(f => f.endsWith(".json"))
+      .sort();  // ISO-like names sort chronologically
+
+    const excess = jsonFiles.length - maxBackups;
+    if (excess > 0) {
+      for (const old of jsonFiles.slice(0, excess)) {
+        await unlink(join(backupsPath, old));
+      }
+    }
+  }
 
   private async ensureDataDir(): Promise<void> {
     try {

package/tui/src/util/instance-lock.ts

@@ -0,0 +1,92 @@
+import { join } from "path";
+import { unlink } from "fs/promises";
+
+const LOCK_FILE = "ei.lock";
+
+export interface LockData {
+  pid: number;
+  started: string;
+  frontend: string;
+}
+
+export type AcquireResult =
+  | { acquired: true }
+  | { acquired: false; reason: "live_process"; pid: number; started: string };
+
+export class InstanceLock {
+  private lockPath: string;
+  private held = false;
+
+  constructor(dataPath: string) {
+    this.lockPath = join(dataPath, LOCK_FILE);
+  }
+
+  /**
+   * Try to acquire the instance lock.
+   *
+   * - No lock file → write and proceed.
+   * - Lock file exists, PID is dead → steal and proceed.
+   * - Lock file exists, PID is live → return { acquired: false }.
+   */
+  async acquire(): Promise<AcquireResult> {
+    const existing = await this.readLock();
+
+    if (existing) {
+      const alive = isProcessAlive(existing.pid);
+      if (alive) {
+        return { acquired: false, reason: "live_process", pid: existing.pid, started: existing.started };
+      }
+      // Stale lock — fall through and overwrite
+    }
+
+    await this.writeLock();
+    this.held = true;
+    return { acquired: true };
+  }
+
+  /**
+   * Release the lock. Safe to call multiple times / if never acquired.
+   */
+  async release(): Promise<void> {
+    if (!this.held) return;
+    this.held = false;
+    try {
+      await unlink(this.lockPath);
+    } catch {
+      // Already gone — that's fine
+    }
+  }
+
+  private async readLock(): Promise<LockData | null> {
+    try {
+      const file = Bun.file(this.lockPath);
+      if (!(await file.exists())) return null;
+      const text = await file.text();
+      return JSON.parse(text) as LockData;
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeLock(): Promise<void> {
+    const data: LockData = {
+      pid: process.pid,
+      started: new Date().toISOString(),
+      frontend: "tui",
+    };
+    await Bun.write(this.lockPath, JSON.stringify(data, null, 2));
+  }
+}
+
+/**
+ * Check whether a process with the given PID is currently running.
+ * Uses kill(pid, 0) — sends no signal, just checks existence.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/tui/src/util/logger.ts

@@ -46,9 +46,7 @@ function formatMessage(level: LogLevel, message: string, data?: unknown): string
 
 function writeLogSync(level: LogLevel, message: string, data?: unknown): void {
   if (!shouldLog(level)) return;
-  
   const line = formatMessage(level, message, data);
-  
   try {
     appendFileSync(getLogPath(), line);
   } catch {}