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 divergence/claude@0.2.6

Permissions in 0.2.6

  • 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

state.ts10 KB
// What the plugin remembers about one host session beyond what the CLI's
// own transcript holds (the Rust `SessionState`): the id the CLI files it
// under, and the user record each of the host's prompts became.
//
// A rewind is resolved with the map, and it lives in this plugin alone:
// the CLI's file does not know the host's ids. The Rust plugin kept it in
// `<data dir>/agents/claude/sessions/<id>.json`; this one keeps it in its
// plugin storage under `session:<id>`, so a restart of the app, or of the
// session after an earlier rewind, can still rewind to a message sent
// before it. The old files are read into it once (`legacy.ts`); `ready`
// is that read, which every load waits for.
import * as Context from "effect/Context";
import * as Layer from "effect/Layer";
import * as Effect from "effect/Effect";
import { Plugin, Host } from "divergence/effect";
import type { PluginServices } from "divergence/effect";
import { adoptLegacy, legacyDir } from "./legacy.ts";
import { objectOf } from "./wire.ts";
import { join, readJson } from "./files.ts";
import type { Files } from "./files.ts";
import type { Sender } from "./records.ts";
import { ProviderError } from "./errors.ts";
import * as z from "zod";
import type { ScanStore } from "./history.ts";

export interface SessionState {
  cli: string | null;
  /// Each host message this plugin sent, by the uuid the CLI records it
  /// under; an older version kept the index of its user record instead.
  sent: Record<string, number | string>;
  /// The record a rewind went back to, until the next prompt follows it.
  /// The CLI's file still ends with the turns the rewind dropped, so a
  /// plain resume or read would take them back.
  rewound: string | null;
  /// The conversation a fork copies (and the record it stops at), until
  /// the fork's first prompt: the CLI writes the fork's own file only then,
  /// so a fork that stopped before it must start from its origin again.
  fork?: { origin: string; at?: string };
}

const PREFIX = "session:";

export function emptyState(): SessionState {
  return { cli: null, sent: {}, rewound: null };
}

function parse(raw: unknown) {
  const value = objectOf(raw);
  const state = emptyState();
  if (!value || typeof value !== "object") return state;
  if (typeof value.cli === "string" && value.cli) state.cli = value.cli;
  if (value.sent && typeof value.sent === "object") {
    for (const [item, sent] of Object.entries(value.sent))
      if ((typeof sent === "number" && Number.isInteger(sent) && sent >= 0) || (typeof sent === "string" && sent))
        state.sent[item] = sent;
  }
  if (typeof value.rewound === "string" && value.rewound) state.rewound = value.rewound;
  const fork = objectOf(value.fork);
  if (typeof fork.origin === "string" && fork.origin)
    state.fork = typeof fork.at === "string" && fork.at ? { origin: fork.origin, at: fork.at } : { origin: fork.origin };
  return state;
}

/// The session states in the plugin's storage.
export class SessionStore {
  constructor(readonlyReady: Effect.Effect<unknown, never, PluginServices> = Effect.void) {
    this.ready = readonlyReady;
  }
  ready: Effect.Effect<unknown, never, PluginServices>;
  load = Effect.fn("Claude.state.load")(function* (this: SessionStore, id: string) {
    yield* this.ready;
    const host = yield* Host;
    // Read as empty, a resume would fall back to the host's id and could
    // open another conversation than the session's own.
    return yield* host.call("host/storage.get", { key: PREFIX + id }).pipe(
      Effect.map((result) => parse(result.value)),
      Effect.mapError(
        (error) =>
          new ProviderError({
            message: `the state of session ${id} could not be read: ${error.message}`,
            cause: error,
          }),
      ),
    );
  });
  save = Effect.fn("Claude.state.save")(function* (this: SessionStore, id: string, state: SessionState) {
    const value: Partial<SessionState> = { sent: state.sent };
    if (state.cli) value.cli = state.cli;
    if (state.rewound) value.rewound = state.rewound;
    if (state.fork) value.fork = state.fork;
    yield* (yield* Host).call("host/storage.set", { key: PREFIX + id, value }).pipe(
      Effect.catchTag(["HostCallFailed", "PermissionNotGranted", "NeedsReview"], (error) =>
        Effect.sync(() => {
          console.warn(`claude: the state of session ${id} could not be kept: ${error.message}`);
        }),
      ),
    );
  });
  cliIdOf = Effect.fn("Claude.state.cliIdOf")(function* (this: SessionStore, id: string) {
    return (yield* this.load(id)).cli ?? id;
  });
  /// Notes that the CLI's file `cli` holds the host session `id`, which
  /// the host already has a chat for: listing leaves it out (`aliases`).
  keepAlias = Effect.fn("Claude.state.keepAlias")(function* (this: SessionStore, cli: string, id: string) {
    yield* (yield* Host).call("host/storage.set", { key: ALIAS + cli, value: id }).pipe(
      Effect.catchTag(["HostCallFailed", "PermissionNotGranted", "NeedsReview"], (error) =>
        Effect.sync(() => {
          console.warn(`claude: the CLI id of session ${id} could not be kept: ${error.message}`);
        }),
      ),
    );
  });
  /// Which of the CLI's files `ids` are another session's (`keepAlias`).
  aliases = Effect.fn("Claude.state.aliases")(function* (this: SessionStore, ids: readonly string[]) {
    if (!ids.length) return new Set<string>();
    const { values } = yield* (yield* Host).call("host/storage.get_many", { keys: ids.map((id) => ALIAS + id) });
    return new Set(ids.filter((_, at) => typeof values[at] === "string"));
  });
  /// The host session each message from another session came from, by the
  /// message's id, for those the plugin can tell. The CLI notes a running
  /// session under its process id (`<config dir>/sessions/<pid>.json`)
  /// only while it runs, so an answer is kept once found; a note that
  /// started after the message arrived is a later process under the same id.
  senders = Effect.fn("Claude.state.senders")(
    function* (this: SessionStore, files: Files, configDir: string | null, senders: readonly Sender[]) {
      const found = new Map<string, string>();
      if (!senders.length) return found;
      const host = yield* Host;
      const kept = yield* host.call("host/storage.get_many", { keys: senders.map((sender) => SENDER + sender.id) });
      const cli = new Map<string, string>();
      for (const [at, sender] of senders.entries()) {
        const session = kept.values[at];
        if (typeof session === "string") found.set(sender.id, session);
        else if (configDir) {
          const note = objectOf(yield* readJson(files, join(configDir, "sessions", `${sender.pid}.json`)));
          if (typeof note.sessionId === "string" && typeof note.startedAt === "number" && note.startedAt <= sender.at)
            cli.set(sender.id, note.sessionId);
        }
      }
      if (!cli.size) return found;
      // A session the host started over under a new CLI id goes by its alias.
      const ids = [...new Set(cli.values())];
      const { values } = yield* host.call("host/storage.get_many", { keys: ids.map((id) => ALIAS + id) });
      const hostIds = new Map(ids.map((id, at) => [id, typeof values[at] === "string" ? values[at] : id]));
      for (const [message, id] of cli) {
        const session = hostIds.get(id) ?? id;
        found.set(message, session);
        yield* host.call("host/storage.set", { key: SENDER + message, value: session });
      }
      return found;
    },
    // Without its sender a message still shows, under the sender's name.
    Effect.catchTag(["HostCallFailed", "PermissionNotGranted", "NeedsReview"], (error) =>
      Effect.sync(() => {
        console.warn(`claude: the sessions that sent messages could not be told: ${error.message}`);
        return new Map<string, string>();
      }),
    ),
  );
}

const ALIAS = "alias:";
const SENDER = "sender:";
const SCANS = "scans:";
/// Raised when `SummaryState` changes, so scans kept before are read again.
const SCAN_FORMAT = 1;

const scanSchema = z.object({
  end: z.number().int().nonnegative(),
  summary: z.object({
    records: z.number().int().nonnegative(),
    title: z.string().nullable(),
    custom: z.string().nullable(),
    prompt: z.string().nullable(),
    createdAt: z.string().nullable(),
    updatedAt: z.string().nullable(),
    first: z.string().nullable(),
  }),
});
const scansSchema = z.object({ format: z.literal(SCAN_FORMAT), scans: z.record(z.string(), scanSchema) });

/// Listing scans kept in the plugin's storage, one value per workspace
/// folder, so a launch does not read every transcript again.
export function storedScans(): ScanStore {
  return {
    load: (dir) =>
      Effect.gen(function* () {
        const { value } = yield* (yield* Host).call("host/storage.get", { key: SCANS + dir });
        const parsed = scansSchema.safeParse(value);
        return parsed.success ? parsed.data.scans : {};
      }).pipe(
        // Without them the listing reads every transcript, as it did before.
        Effect.catchTag(["HostCallFailed", "PermissionNotGranted", "NeedsReview"], (error) =>
          Effect.sync(() => {
            console.warn(`claude: the kept listing of ${dir} could not be read: ${error.message}`);
            return {};
          }),
        ),
      ),
    save: (dir, scans) =>
      Effect.gen(function* () {
        yield* (yield* Host).call("host/storage.set", { key: SCANS + dir, value: { format: SCAN_FORMAT, scans } });
      }).pipe(
        Effect.catchTag(["HostCallFailed", "PermissionNotGranted", "NeedsReview"], (error) =>
          Effect.sync(() => {
            console.warn(`claude: the listing of ${dir} could not be kept: ${error.message}`);
          }),
        ),
      ),
  };
}

export class SessionStates extends Context.Service<SessionStates, SessionStore>()("claude/SessionStates") {
  static readonly layer = Layer.effect(
    SessionStates,
    Effect.gen(function* () {
      const plugin = yield* Plugin;
      const legacy = yield* Effect.cached(adoptLegacy(legacyDir(plugin.api)));
      yield* Effect.forkScoped(legacy);
      return new SessionStore(legacy);
    }),
  );
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.7latestNov 21, 2026>=5 <6207.5 KB4 permissionsListed
0.2.6Nov 16, 2026>=5 <6206 KB4 permissionsListed
0.2.5Nov 11, 2026>=5 <6168.3 KB4 permissionsListed
0.2.4Nov 9, 2026>=5 <6166.1 KB4 permissionsListed
0.2.3Oct 27, 2026>=2 <4151.6 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.