Official

codex

Codex agent provider: runs the Codex CLI's app-server 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/codex@0.2.5

Permissions in 0.2.5

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Codex agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Codex CLI, and ask or tell the installer that owns it (npm or Homebrew) about a newer versionPrograms: codexnpmbrew
  • Environment variables envMediumReads the listed environment variables.Find each account's Codex home, and pass extra app-server arguments set in CODEX_ARGSVariables: HOMECODEX_HOMECODEX_ARGS
  • Read files fs.readMediumReads files in the listed places.Notice a conversation started in the Codex app or CLI, so it shows up at once, and read, once, the accounts the previous Codex provider keptPlaces: its own data folder~/.codex/sessions~/.codex/sessions/**~/.codex*/sessions~/.codex*/sessions/**

Files

catalog.ts4.8 KB
// Codex supplies each configured provider and its own model catalog.
import * as Effect from "effect/Effect";
import type * as z from "zod";
import type * as wire from "./wire.ts";
import type { CodexAgent } from "./agent.ts";
import type { PluginServices } from "divergence/effect";
import type { TransportError } from "../sdk/effect.ts";
import type { AgentInfo, ConfigOption } from "./types.ts";
import type { Session } from "./types.ts";
import { ProviderError } from "../sdk/errors.ts";
import { RpcError, METHOD_NOT_FOUND } from "../sdk/jsonrpc.ts";
import { buildOptions, pick, resumeParams } from "./params.ts";

export const providers = Effect.fn("Codex.providers")(function* (agent: CodexAgent) {
  const { connection } = yield* agent.client();
  return yield* agent.request(connection, "modelProvider/list", {}).pipe(Effect.catchTag("TransportFailed", (error) =>
    error.cause instanceof RpcError && error.cause.code === METHOD_NOT_FOUND ? Effect.succeed(null) : Effect.fail(error),
  ));
});

export const loadModels = Effect.fn("Codex.loadModels")(function* (this: CodexAgent, provider = ""): Effect.fn.Return<wire.Model[], ProviderError | TransportError, PluginServices> {
  const cached = this.models.get(provider);
  if (cached) return cached;
  const { connection } = yield* this.client();
  const models: wire.Model[] = [];
  let cursor: string | null = null;
  for (;;) {
    const response: z.infer<(typeof wire.responses)["model/list"]> = yield* this.request(connection, "model/list", {
      cursor, limit: 100, ...(provider ? { modelProvider: provider } : {}),
    });
    models.push(...(response.data ?? []));
    if (!response.nextCursor) break;
    cursor = response.nextCursor;
  }
  const shown = models.filter((model) => !model.hidden);
  if (!shown.length) return yield* new ProviderError({ message: "Codex listed no models it can run" });
  this.models.set(provider, shown);
  return shown;
});

export const optionsFor = Effect.fn("Codex.optionsFor")(function* (this: CodexAgent, workspace: string, overrides: Record<string, unknown>): Effect.fn.Return<ConfigOption[], ProviderError | TransportError, PluginServices> {
  const config = yield* this.config(workspace);
  const catalog = yield* providers(this);
  const provider = pick(overrides, "model_provider") ?? config.model_provider ?? catalog?.defaultProviderId ?? "";
  const models = yield* this.loadModels(provider);
  const effective = (config.model_provider ?? catalog?.defaultProviderId ?? "") !== provider ? { ...config, model: null, model_reasoning_effort: null, service_tier: null } : config;
  const options = buildOptions(models, effective, overrides);
  if (catalog) options.push({ id: "model_provider", name: "Provider", category: "other", kind: "select", value: provider, choices: catalog.data.map(({ id, name }) => ({ value: id, name })) });
  return options;
});

export const selectProvider = Effect.fn("Codex.selectProvider")(function* (agent: CodexAgent, sessionId: string, state: Session, value: unknown) {
  if (state.run) return yield* new ProviderError({ message: "Wait for the current turn to finish before changing providers." });
  const catalog = yield* providers(agent);
  if (!catalog?.data.some((provider) => provider.id === value)) return yield* new ProviderError({ message: "Codex did not list that provider." });
  const options: Record<string, unknown> = { ...state.options, model_provider: value };
  delete options.model;
  delete options.reasoning;
  delete options.service_tier;
  const connection = yield* agent.loadedConnection(sessionId);
  const resumed = yield* agent.request(connection, "thread/resume", resumeParams(sessionId, { workspace: state.workspace, options }));
  if (resumed.modelProvider) options.model_provider = resumed.modelProvider;
  state.options = options;
  return { options: yield* agent.optionsFor(state.workspace, options) };
});

export const providerMethods = Effect.fn("Codex.providerMethods")(function* (agent: CodexAgent): Effect.fn.Return<{ methods: NonNullable<AgentInfo["authMethods"]>; status?: AgentInfo["status"] }, ProviderError | TransportError, PluginServices> {
  const catalog = yield* providers(agent);
  if (!catalog) return { methods: [] };
  const { connection } = yield* agent.client();
  const methods: NonNullable<AgentInfo["authMethods"]> = [];
  let status: AgentInfo["status"];
  for (const provider of catalog.data) {
    const response = yield* agent.request(connection, "account/gatewayOAuth/read", { modelProvider: provider.id });
    if (response.required) {
      methods.push({ id: `gateway:${provider.id}`, name: `Sign in to ${provider.name}`, description: "Authorizes this configured provider." });
      if (provider.id === catalog.defaultProviderId) status = response.status === "succeeded" ? { state: "ready" } : { state: "auth_required", message: response.error ?? `Sign in to ${provider.name}.` };
    }
  }
  return { methods, status };
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6121.1 KB4 permissionsListed
0.2.4Nov 16, 2026>=5 <6120.2 KB4 permissionsListed
0.2.3Nov 11, 2026>=5 <695.2 KB4 permissionsListed
0.2.2Nov 9, 2026>=5 <688.9 KB4 permissionsListed
0.2.1Oct 27, 2026>=2 <484.1 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.