mirror of https://github.com/jlengrand/Maestro.git synced 2026-03-10 08:31:19 +00:00

Files

Pedram Amini f87d072f96 ## CHANGES

- Split monolithic CLAUDE.md into focused, indexed sub-docs for faster onboarding 📚
- Added deep Agent support guide: capabilities, flags, parsers, storage, and adding agents 🤖
- Documented full `window.maestro` IPC surface with clearer namespaces and History API 📡
- Captured core implementation patterns: processes, security, settings, modals, SSH, Auto Run 🧭
- Published performance playbook for React, IPC batching, caching, and debouncing 🚀
- Formalized Session interface docs, including multi-tab, queues, stats, and error fields 🧩
- Session-level custom agent path now overrides detected binary during spawn 🛠️
- New rendering settings: disable GPU acceleration (early startup) and disable confetti 🖥️
- Confetti effects now respect user preference across celebration overlays and wizard completion 🎊
- File explorer now distinguishes “loading” vs “no files found” empty states 🗂️

2026-01-13 11:14:59 -06:00

3.3 KiB

Raw Blame History

CLAUDE-IPC.md

IPC API surface documentation for the Maestro codebase. For the main guide, see CLAUDE.md.

Overview

The window.maestro API exposes the following namespaces:

Core APIs

settings - Get/set app settings
sessions / groups - Persistence
process - Spawn, write, kill, resize
fs - readDir, readFile
dialog - Folder selection
shells - Detect available shells
logger - System logging

Agent & Agent Sessions

agents - Detect, get, config, refresh, custom paths, getCapabilities
agentSessions - Generic agent session storage API (list, read, search, delete)
agentError - Agent error handling (clearError, retryAfterError)
claude - (Deprecated) Claude Code sessions - use agentSessions instead

Git Integration

git - Status, diff, isRepo, numstat, branches, tags, info
git - Worktree support: worktreeInfo, getRepoRoot, worktreeSetup, worktreeCheckout
git - PR creation: createPR, checkGhCli, getDefaultBranch

Web & Live Sessions

web - Broadcast user input, Auto Run state, tab changes to web clients
live - Toggle live sessions, get status, dashboard URL, connected clients
webserver - Get URL, connected client count
tunnel - Cloudflare tunnel: isCloudflaredInstalled, start, stop, getStatus

Automation

autorun - Document and image management for Auto Run
playbooks - Batch run configuration management
history - Per-session execution history (see History API below)
cli - CLI activity detection for playbook runs
tempfile - Temporary file management for batch processing

Analytics & Visualization

stats - Usage statistics: recordQuery, getAggregatedStats, exportCsv, clearOldData, getDatabaseSize
stats - Auto Run tracking: startAutoRun, endAutoRun, recordTask, getAutoRunSessions
stats - Real-time updates via stats:updated event broadcast
documentGraph - File watching: watchFolder, unwatchFolder
documentGraph - Real-time updates via documentGraph:filesChanged event

History API

Per-session history storage with 5,000 entries per session (up from 1,000 global). Each session's history is stored as a JSON file in ~/Library/Application Support/Maestro/history/{sessionId}.json.

window.maestro.history = {
  getAll: (projectPath?, sessionId?) => Promise<HistoryEntry[]>,
  add: (entry) => Promise<boolean>,
  clear: (projectPath?, sessionId?) => Promise<boolean>,
  delete: (entryId, sessionId?) => Promise<boolean>,
  update: (entryId, updates, sessionId?) => Promise<boolean>,
  // For AI context integration:
  getFilePath: (sessionId) => Promise<string | null>,
  listSessions: () => Promise<string[]>,
  // External change detection:
  onExternalChange: (handler) => () => void,
  reload: () => Promise<boolean>,
};

AI Context Integration: Use getFilePath(sessionId) to get the path to a session's history file. This file can be passed directly to AI agents as context, giving them visibility into past completed tasks, decisions, and work patterns.

Power Management

power - Sleep prevention: setEnabled, isEnabled, getStatus, addReason, removeReason

Utilities

fonts - Font detection
notification - Desktop notifications, text-to-speech
devtools - Developer tools: open, close, toggle
attachments - Image attachment management

3.3 KiB Raw Blame History