Plugins

wrong phrase => correct phrase
another mistake => fix | all

~/.clideck/plugins/my-plugin/
  clideck-plugin.json   # manifest (optional, recommended)
  index.js             # backend code (required)
  client.js            # frontend code (optional)
  public/              # static assets (optional)

~/.clideck/plugins/my-plugin/
  clideck-plugin.json   # manifest with "install": "npm"
  package.json          # npm dependencies
  index.js             # backend code (required)
  client.js            # frontend code (optional)

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "icon": "<svg class=\"w-4 h-4\" ...>...</svg>",
  "install": "npm",
  "settings": [
    { "key": "enabled", "label": "Enable feature", "type": "toggle", "default": true },
    { "key": "mode", "label": "Mode", "type": "select", "options": ["fast", "slow"], "default": "fast" },
    { "key": "limit", "label": "Max items", "type": "number", "min": 1, "max": 100, "default": 10 },
    { "key": "apiKey", "label": "API Key", "type": "text", "default": "" }
  ]
}

module.exports = {
  init(api) {
    // Your plugin code here
  }
};

// Transform input before it reaches the terminal
// Return a string to replace the input, or nothing to leave it unchanged
api.onSessionInput((sessionId, data) => {
  return data;
});

// Observe terminal output (read-only)
api.onSessionOutput((sessionId, data) => {
  // data is the raw terminal output
});

// React to working/idle transitions
api.onStatusChange((sessionId, working, source) => {
  // working: true = agent started working, false = agent went idle
  // source: 'telemetry', 'client', 'esc', 'menu', etc.
});

// React to interactive menu detection (choice menus in agent output)
api.onMenuDetected((sessionId, choices) => {
  // choices: [{ value, label, selected }]
});

// Receive clean, complete transcript entries (user inputs and agent outputs)
api.onTranscriptEntry((sessionId, role, text) => {
  // role: 'user' (complete input line) or 'agent' (processed output block)
  // text: clean text with ANSI codes stripped, ready to use
});

api.getSessions();    // [{ id, name, cwd, commandId, presetId, themeId, projectId, roleName, working }]
api.getSession(id);   // single session object, or null

// Send a message to the frontend
api.sendToFrontend('my-event', { key: 'value' });

// Receive a message from the frontend
api.onFrontendMessage('my-action', (msg) => {
  // handle message
});

// Write data to a session's terminal (as if the user typed it)
api.inputToSession(id, data);

// Create a new session programmatically
const sessionId = api.createSession({
  presetId: 'claude-code',   // or commandId
  name: 'My Session',
  cwd: '/path/to/project',
  projectId: 'uuid',         // optional
  roleName: 'Reviewer',      // optional
  ephemeral: true,            // optional — won't persist for resume
});

// Close a session
api.closeSession(id);

// Enable/disable auto-approval of interactive menus for a session
api.setAutoApproveMenu(id, true);

api.getRoles();       // all defined roles (deep copy)
api.getProjects();    // all defined projects (deep copy)

// Get the last N transcript turns (user/agent alternating entries)
api.getTranscript(id, 20);

// Get structured screen turns parsed from the terminal buffer
api.getScreenTurns(id, 'claude-code', { raw: false });

// Get the raw clean screen content
api.getScreen(id);

// Detect interactive menus from raw screen lines
api.detectMenu(lines, 'claude-code');

api.addToolbarAction({
  id: 'do-thing',
  title: 'Do Thing',
  icon: '<svg>...</svg>',  // inline SVG, 16x16
});

// Add a button to project headers in the sidebar
api.addProjectAction({
  id: 'run-workflow',
  title: 'Run Workflow',
  icon: '<svg>...</svg>',
});

// Create a pill
api.addSessionPill({ id: 'my-task', title: 'My Task', projectId: 'uuid', icon: '' });

// Update pill state
api.updateSessionPill('my-task', {
  working: true,
  statusText: 'Processing...',
  title: 'Updated Title',      // optional
  projectId: 'new-uuid',       // optional
});

// Append a timestamped log entry (viewable by clicking the pill)
api.appendPillLog('my-task', 'Step 1 complete');

// Remove the pill from the sidebar
api.removeSessionPill('my-task');

api.getSetting('mode');      // current value for a single key
api.getSettings();           // all settings as { key: value }

// Update a setting programmatically (validated against manifest)
api.setSetting('mode', 'fast');

// Set dropdown options at runtime for dynamic-select settings
api.setSettingOptions('model', [
  { value: 'gpt-4', label: 'GPT-4 ($30/M input)' },
  { value: 'gpt-3.5', label: 'GPT-3.5 ($0.50/M input)' },
]);

api.onSettingsChange((key, value) => {
  // called when the user changes a setting in the UI
});

api.log('message');          // log with [plugin:my-plugin] prefix
api.pluginId;                // this plugin's ID
api.pluginDir;               // absolute path to this plugin's folder
api.version;                 // API version (currently 1)

api.onShutdown(() => {
  // cleanup when CliDeck shuts down
});

// Resolve a package — checks plugin-local node_modules first, then app-level
const piAi = api.resolve('@mariozechner/pi-ai');

export function init(api) {
  // Send a message to the backend
  api.send('my-action', { key: 'value' });

  // Receive a message from the backend
  api.onMessage('my-event', (msg) => {
    // msg is the full message object including type
  });

  // Add a button to the terminal toolbar
  api.addToolbarButton({
    title: 'Do Thing',
    icon: '<svg>...</svg>',
    onClick: () => { /* handle click */ }
  });

  // Session helpers
  api.getActiveSessionId();       // current active session ID
  api.writeToSession(id, text);   // write text to a session's terminal

  // Toast notifications
  api.toast('Something happened', { type: 'success' });
}

api.toast(message, opts)

// Transient success
api.toast('Model loaded', { type: 'success' });

// Persistent progress (dismiss when done)
const t = api.toast('Installing dependencies...', { type: 'info', duration: 0, id: 'setup' });
// later...
t.dismiss();

// Replace previous toast with same id
api.toast('Dependencies installed', { type: 'success', id: 'setup' });

~/.clideck/plugins/work-logger/
  clideck-plugin.json
  index.js

{
  "id": "work-logger",
  "name": "Work Logger",
  "version": "1.0.0"
}

module.exports = {
  init(api) {
    api.onStatusChange((sessionId, working) => {
      const session = api.getSession(sessionId);
      const name = session?.name || sessionId;
      api.log(`${name} is now ${working ? 'working' : 'idle'}`);
    });

    api.onShutdown(() => {
      api.log('shutting down');
    });
  }
};