mcp-codex-dev

Instructions

Implementation Reference

• src/tools/codex-session.ts:103-133 (handler)

  The codexSessionList handler function that implements the session_list tool logic. It retrieves all tracked sessions from sessionManager, filters them by type and status if specified, and returns an array of session objects with sessionId, type, createdAt, and status fields.

  export async function codexSessionList(
    params: CodexSessionListParams
  ): Promise<{
    sessions: Array<{
      sessionId: string;
      type: "write" | "review" | "exec";
      createdAt: string;
      status: string;
    }>;
  }> {
    let sessions = await sessionManager.listAll({
      workingDirectory: params.workingDirectory,
    });
  
    if (params.type !== "all") {
      sessions = sessions.filter((s) => s.type === params.type);
    }
  
    if (params.status !== "all") {
      sessions = sessions.filter((s) => s.status === params.status);
    }
  
    return {
      sessions: sessions.map((s) => ({
        sessionId: s.sessionId,
        type: s.type,
        createdAt: s.createdAt,
        status: s.status,
      })),
    };
  }

• src/tools/codex-session.ts:89-101 (schema)

  The Zod schema (CodexSessionListParamsSchema) and TypeScript type (CodexSessionListParams) defining the input parameters for the session_list tool. Parameters include type (write/review/exec/all), status (active/completed/abandoned/all), and optional workingDirectory.

  export const CodexSessionListParamsSchema = z.object({
    type: z.enum(["write", "review", "exec", "all"]).optional().default("all"),
    status: z
      .enum(["active", "completed", "abandoned", "all"])
      .optional()
      .default("active"),
    workingDirectory: z
      .string()
      .optional()
      .describe("Project working directory (used to scope session tracking)"),
  });
  
  export type CodexSessionListParams = z.infer<typeof CodexSessionListParamsSchema>;

• src/index.ts:231-264 (registration)

  MCP tool registration for session_list. Registers the tool with the server, defines its description, input schema (matching the Zod schema), and the async handler that calls codexSessionList and formats the result as JSON content.

  // ─── session_list ──────────────────────────────────────────────────
  if (isToolEnabled(config, "session_list")) {
    server.tool(
      "session_list",
      "List tracked Codex sessions. Can filter by type and status.",
      {
        type: z
          .enum(["write", "review", "exec", "all"])
          .optional()
          .default("all")
          .describe("Session type filter"),
        status: z
          .enum(["active", "completed", "abandoned", "all"])
          .optional()
          .default("active")
          .describe("Session status filter"),
        workingDirectory: z
          .string()
          .optional()
          .describe("Project working directory (used to scope session tracking)"),
      },
      async (params) => {
        const result = await codexSessionList(params);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

• src/services/session-manager.ts:172-176 (helper)

  The listAll method in sessionManager that retrieves all tracked sessions. This helper is called by the codexSessionList handler to get the raw session data which is then filtered and formatted.

  async listAll(options: { workingDirectory?: string } = {}): Promise<TrackedSession[]> {
    const store = this.getStore(options.workingDirectory);
    await this.load(options);
    return Array.from(store.sessions.values());
  }