Official

claude

Claude Code agent provider: runs the Claude Code CLI headless for each account.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install convergence/claude@0.2.2

Permissions in 0.2.2

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Claude Code agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Claude Code CLI (sessions, sign-in, `claude update`), and ask the npm installation that owns it about a newer versionPrograms: claudenpm
  • Read files fs.readMediumReads files in the listed places.Read Claude Code's sessions, settings and skills (in ~/.claude, other accounts' ~/.claude-* folders, the shared skills and the folder you choose in Settings), the project's .claude folder, the administrator's skill policy, and once, what the previous provider keptPlaces: ~/.claude/**~/.claude*/**~/.agents/skills/**the open workspaceits own data folder/Library/Application Support/ClaudeCode/managed-settings.json/etc/claude-code/managed-settings.json${settings.configDir}
  • Environment variables envMediumReads the listed environment variables.Find Claude Code's configuration directory, and the launch settings you set in CLAUDE_* variables (extra arguments, MCP servers, setting sources, appended system prompt, extra folders)Variables: HOMECLAUDE_CONFIG_DIRCLAUDE_EXTRA_ARGSCLAUDE_MCP_CONFIGCLAUDE_STRICT_MCP_CONFIGCLAUDE_SETTING_SOURCESCLAUDE_APPEND_SYSTEM_PROMPTCLAUDE_ADD_DIRS

Files

history.ts10.9 KB
// Reads the transcripts Claude Code stores itself (the Rust `history.rs`).
//
// The CLI keeps one JSONL file per session under
// `<config dir>/projects/<encoded workspace>/<session id>.jsonl`, where the
// encoding replaces every character that is not a letter, a digit or a
// hyphen with a hyphen (`/private/tmp/a_b.c` becomes `-private-tmp-a-b-c`).
// The CLI records the resolved working directory; the host already names
// a workspace by its resolved path, so the path is encoded as given.
import * as Effect from "effect/Effect";
import * as wire from "./wire.ts";
import type { Files } from "./files.ts";
import type { SessionSummary } from "./types.ts";
import { CHUNK, join, mapLimit, parseLines, readLines } from "./files.ts";
import { firstText, recordsToItems, timestamp } from "./records.ts";
import { attachSubagents } from "./subagents.ts";
import { attachWorkflows } from "./workflow.ts";

const NEWLINE = 10;
const decoder = new TextDecoder();

/// The folder name Claude Code uses for `workspace`.
export function encodeWorkspace(workspace: string) {
  return String(workspace).replace(/[^A-Za-z0-9-]/g, "-");
}

/// The folder of one workspace's transcripts in the configuration
/// directory `configDir`.
export function workspaceDir(configDir: string | null, workspace: string) {
  return configDir ? join(configDir, "projects", encodeWorkspace(workspace)) : null;
}

export function sessionFile(configDir: string | null, workspace: string, session: string) {
  const dir = workspaceDir(configDir, workspace);
  return dir ? join(dir, `${session}.jsonl`) : null;
}

/// Title, first and last activity of a transcript, taken a record at a
/// time.
class Summary {
  private records = 0;
  private title: string | null = null;
  private custom: string | null = null;
  private firstPrompt: string | null = null;
  private createdAt: string | null = null;
  private updatedAt: string | null = null;

  add(record: wire.Record) {
    this.records += 1;
    if (record?.type === "custom-title" && typeof record.customTitle === "string") this.custom = record.customTitle;
    else if (record?.type === "ai-title" && typeof record.aiTitle === "string") this.title = record.aiTitle;
    else if (record?.type === "user" && this.firstPrompt === null && record.isSidechain !== true)
      this.firstPrompt = firstText(record.message?.content);
    const time = timestamp(record);
    if (time !== null) {
      this.createdAt ??= time;
      this.updatedAt = time;
    }
  }

  result(id: string) {
    if (!this.records) return null;
    let chosen = this.custom ?? this.title;
    if (chosen === null && this.firstPrompt !== null) {
      const line = (this.firstPrompt.split("\n").find((line) => line.trim()) ?? "").trim();
      const chars = [...line];
      chosen = chars.length > 80 ? `${chars.slice(0, 80).join("")}…` : line;
    }
    const out: SessionSummary = { id };
    if (chosen !== null) out.title = chosen;
    if (this.createdAt !== null) out.createdAt = this.createdAt;
    if (this.updatedAt !== null) out.updatedAt = this.updatedAt;
    return out;
  }
}

/// Title, first and last activity of one transcript's records.
export function summarize(records: wire.Record[], id: string) {
  const summary = new Summary();
  for (const record of records) summary.add(record);
  return summary.result(id);
}

/// `summarize` of the transcript at `path`, read a piece at a time: a
/// transcript can be hundreds of megabytes, and listing a workspace reads
/// several at once.
const summarizeFile = Effect.fn("Claude.summarizeFile")(function* (files: Files, path: string, id: string) {
  const stat = yield* files.stat(path);
  if (!stat) return null;
  const summary = new Summary();
  let rest = new Uint8Array(0);
  for (let offset = 0; offset < stat.size; offset += CHUNK) {
    const piece = yield* files.range(path, offset, CHUNK);
    if (!piece?.length) break;
    const joined = new Uint8Array(rest.length + piece.length);
    joined.set(rest, 0);
    joined.set(piece, rest.length);
    const end = joined.lastIndexOf(NEWLINE);
    for (const record of parseLines(decoder.decode(joined.subarray(0, end + 1)))) summary.add(record);
    rest = joined.subarray(end + 1);
  }
  for (const record of parseLines(decoder.decode(rest))) summary.add(record);
  return summary.result(id);
});

/// Every session Claude Code stored for `workspace`, newest first.
export const listSessions = Effect.fn("Claude.listSessions")(function* (
  files: Files,
  configDir: string | null,
  workspace: string,
) {
  const dir = workspaceDir(configDir, workspace);
  if (!dir) return [];
  const entries = yield* files.list(dir);
  if (!entries) return [];
  const transcripts = entries.filter((entry) => entry.kind !== "dir" && entry.name.endsWith(".jsonl"));
  const sessions = yield* mapLimit(transcripts, 8, (entry) =>
    summarizeFile(files, join(dir, entry.name), entry.name.slice(0, -".jsonl".length)),
  );
  return sessions
    .filter((session) => session !== null)
    .sort((a, b) =>
      (b.updatedAt ?? "") > (a.updatedAt ?? "") ? 1 : (b.updatedAt ?? "") < (a.updatedAt ?? "") ? -1 : 0,
    );
});

/// The user messages of a transcript, sidechains aside.
export function userRecords(records: wire.Record[]) {
  return records.filter(
    (record) => record?.type === "user" && record.isSidechain !== true && record.message?.content !== undefined,
  );
}

/// How many user messages the stored transcript holds. Read just before a
/// prompt is sent, it is the index the CLI will give that prompt's record.
export const userRecordCount = Effect.fn("Claude.userRecordCount")(function* (
  files: Files,
  configDir: string | null,
  workspace: string,
  session: string,
) {
  const path = sessionFile(configDir, workspace, session);
  return path ? userRecords(yield* readLines(files, path)).length : 0;
});

/// Where a conversation goes back to when a user message is forgotten:
/// `{ fresh: true }` for the first message (nothing came before it, so the
/// conversation starts over), else `{ at: <the record just before it> }`.
/// `--resume-session-at` keeps the message it names, so the target is the
/// message's own parent.
export function rewindBefore(record: wire.Record) {
  return typeof record?.parentUuid === "string" ? { at: record.parentUuid } : { fresh: true };
}

/// How to rewind so that the `index`th user message and everything after
/// it are forgotten. `null` when there is no such message.
export const rewindTargetAt = Effect.fn("Claude.rewindTargetAt")(function* (
  files: Files,
  configDir: string | null,
  workspace: string,
  session: string,
  index: number,
) {
  const path = sessionFile(configDir, workspace, session);
  if (!path) return null;
  const record = userRecords(yield* readLines(files, path))[index];
  return record ? rewindBefore(record) : null;
});

/// The record to resume at so that the item `itemId` of the CLI's own file
/// and everything after it is forgotten. Assistant items are
/// `<uuid>:<block index>`; the record is the uuid. `null` for an item with
/// no parent or none at all: the rewind is refused, not half done.
export const rewindTarget = Effect.fn("Claude.rewindTarget")(function* (
  files: Files,
  configDir: string | null,
  workspace: string,
  session: string,
  itemId: string,
) {
  const path = sessionFile(configDir, workspace, session);
  if (!path) return null;
  const uuid = String(itemId).split(":")[0];
  const record = (yield* readLines(files, path)).find((record) => record?.uuid === uuid);
  return typeof record?.parentUuid === "string" ? record.parentUuid : null;
});

/// Parses one stored transcript into items, each subagent and workflow as
/// a task item with its own transcript inside.
export const readSession = Effect.fn("Claude.readSession")(function* (
  files: Files,
  configDir: string | null,
  workspace: string,
  session: string,
) {
  const path = sessionFile(configDir, workspace, session);
  return path ? yield* readFile(files, path) : [];
});

/// Parses the transcript at `path` (`<session id>.jsonl`), with the
/// subagents from the `<session id>/` folder beside it.
export const readFile = Effect.fn("Claude.readFile")(function* (files: Files, path: string) {
  return (yield* readSessionFile(files, path, { tasks: "all" })).items;
});

/// The records of a transcript up to its last newline, and where that is,
/// so that a later read takes only what was appended (`Tail`).
export interface Tail {
  path: string;
  offset: number;
  records: wire.Record[];
}

/// The records of the transcript at `path`. With the tail of an earlier
/// read of the same file, only the bytes written after it are read: the
/// CLI appends. A file that shrank, or whose byte before the tail is not
/// the newline it was, is read whole; so is the answer of a host without
/// ranged reads (the whole file, not the range asked for).
export const readRecords = Effect.fn("Claude.readRecords")(function* (files: Files, path: string, tail?: Tail) {
  const stat = yield* files.stat(path);
  if (!stat) return { records: [], tail: undefined };
  const settle = (records: wire.Record[], offset: number, rest: Uint8Array) => {
    const kept: Tail = { path, offset, records };
    // A last line with no newline yet is parsed now and read again later.
    return { records: rest.length ? [...records, ...parseLines(decoder.decode(rest))] : records, tail: kept };
  };
  if (tail && tail.path === path && tail.offset > 0 && stat.size >= tail.offset) {
    const length = stat.size - tail.offset + 1;
    const bytes = yield* files.range(path, tail.offset - 1, length);
    if (bytes && bytes.length === length && bytes[0] === NEWLINE) {
      const end = bytes.lastIndexOf(NEWLINE);
      const added = end > 0 ? parseLines(decoder.decode(bytes.subarray(1, end + 1))) : [];
      return settle(added.length ? [...tail.records, ...added] : tail.records, tail.offset + end, bytes.subarray(end + 1));
    }
  }
  const bytes = yield* files.bytes(path);
  if (!bytes) return { records: [], tail: undefined };
  const end = bytes.lastIndexOf(NEWLINE);
  return settle(parseLines(decoder.decode(bytes.subarray(0, end + 1))), end + 1, bytes.subarray(end + 1));
});

/// `readFile`, reading only what was appended since `tail`, and the
/// transcripts of only the subagents in `tasks` (by task id), those still
/// running, and the ones they started; the others come with no items and
/// are listed in `omitted`.
export const readSessionFile = Effect.fn("Claude.readSessionFile")(function* (
  files: Files,
  path: string,
  options: { tail?: Tail; tasks: ReadonlySet<string> | "all" },
) {
  const read = yield* readRecords(files, path, options.tail);
  // Old CLIs wrote subagents inline as sidechain records; the current one
  // writes them to their own files, read below.
  const records = read.records.filter((record) => record?.isSidechain !== true);
  const items = recordsToItems(records);
  const sessionDir = path.replace(/\.jsonl$/, "");
  const omitted = yield* attachSubagents(files, items, records, sessionDir, options.tasks);
  yield* attachWorkflows(files, items, records, sessionDir);
  return { items, tail: read.tail, omitted };
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.3latestNov 21, 2026>=2 <4146.9 KB4 permissionsListed
0.2.2Oct 25, 2026>=2 <4145.5 KB4 permissionsListed
0.2.1Oct 23, 2026>=2 <4143.4 KB4 permissionsListed
0.2.0Oct 5, 2026>=2 <3128.7 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.