agentop: Skill for Claude Code

Jotai Atomic State Management

Fine-grained state management with Jotai atoms, optimized for entity-based data and real-time updates.

When to Use This Skill

• Setting up global application state
• Creating entity maps with atomFamily
• Deriving computed state from base atoms
• Syncing state with IPC/backend
• Managing streaming updates from agent sessions
• Implementing optimistic updates

Atom Architecture

Entity Map Pattern

// src/renderer/state/atoms.ts
import { atom, useAtom } from 'jotai';
import { atomFamily, atomWithStorage } from 'jotai/utils';
import type { Task, Outcome, AgentSession, AgentStep } from '@agentop/core';

// ============================================
// Entity Maps - Core Data Storage
// ============================================

// Tasks map: id -> Task
export const tasksMapAtom = atom<Map<string, Task>>(new Map());

// Outcomes map: id -> Outcome
export const outcomesMapAtom = atom<Map<string, Outcome>>(new Map());

// Sessions map: id -> AgentSession
export const sessionsMapAtom = atom<Map<string, AgentSession>>(new Map());

// Steps map: id -> AgentStep
export const stepsMapAtom = atom<Map<string, AgentStep>>(new Map());

// ============================================
// Atom Families - Individual Entity Access
// ============================================

// Get or create atom for specific task
export const taskAtomFamily = atomFamily((id: string) =>
  atom(
    (get) => get(tasksMapAtom).get(id),
    (get, set, update: Partial<Task>) => {
      const map = new Map(get(tasksMapAtom));
      const existing = map.get(id);
      if (existing) {
        map.set(id, { ...existing, ...update });
        set(tasksMapAtom, map);
      }
    }
  )
);

export const outcomeAtomFamily = atomFamily((id: string) =>
  atom(
    (get) => get(outcomesMapAtom).get(id),
    (get, set, update: Partial<Outcome>) => {
      const map = new Map(get(outcomesMapAtom));
      const existing = map.get(id);
      if (existing) {
        map.set(id, { ...existing, ...update });
        set(outcomesMapAtom, map);
      }
    }
  )
);

export const sessionAtomFamily = atomFamily((id: string) =>
  atom(
    (get) => get(sessionsMapAtom).get(id),
    (get, set, update: Partial<AgentSession>) => {
      const map = new Map(get(sessionsMapAtom));
      const existing = map.get(id);
      if (existing) {
        map.set(id, { ...existing, ...update });
        set(sessionsMapAtom, map);
      }
    }
  )
);

export const stepAtomFamily = atomFamily((id: string) =>
  atom(
    (get) => get(stepsMapAtom).get(id),
    (get, set, update: Partial<AgentStep>) => {
      const map = new Map(get(stepsMapAtom));
      const existing = map.get(id);
      if (existing) {
        map.set(id, { ...existing, ...update });
        set(stepsMapAtom, map);
      }
    }
  )
);