How puppyone-ai/puppyone works
puppyone is a desktop workspace for local folders and coding agents, with optional Cloud access for sharing folders across agents and teammates. The principal flow is opening a folder, working with its files and Git history, and optionally connecting it to Cloud so agents can reach it; local agents can also run in the app. The graph emphasizes documented capabilities and relationships visible in the supplied excerpts or source index. Several subsystems are represented at directory level because their implementation was not sampled.
Main entry points: App.tsx Desktop App UI · useProjectOpeningSurfaces.tsx Project Opening · cloudApi.ts Cloud API · useDesktopGitController.ts Git Controller
Components 22
Workspace and Files
- Desktop App UI
src/App.tsx - Project Opening
src/app/useProjectOpeningSurfaces.tsx - Local File API
electron/local-api/files/path-policy.mjs - Document Editor
src/shared-ui/editor/document-session/documentStorageReads.ts - App Preview
src/shared-ui/editor/viewers/app/useAppPreviewSession.ts - Database Preview
src/platform/databasePreviewClient.ts
Agent Runtime
- Agent UI
src/features/desktop-agent/ui/useAgentReferenceIngestion.ts - Agent Runtime
electron/main/agent/application/agent-service.mjs - Agent Protocols
electron/main/agent/protocols/acp/acp-client.mjs - Agent Host
electron/main/agent/bootstrap/create-agent-runtime-host.mjs
Cloud and Sharing
- Cloud Authentication
src/features/cloud/hooks/useCloudAuthController.ts - Repository Cloud Context
src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts - Cloud API
src/lib/cloudApi.ts - Cloud Project Catalog
archive/desktop-cloud-catalog/src/features/cloud/data/useCloudProjectCatalog.ts - Cloud Preview
electron/main/cloud-native-preview-service.mjs - Cloud Folder
Source Control
- Git Controller
src/features/source-control/useDesktopGitController.ts - Git Lifecycle
src/features/source-control/useGitRepositoryLifecycle.ts
Desktop Services
- Desktop Auth Service
electron/cloud-auth-service.mjs - Local Git Operations
electron/local-api/git/runner.mjs
Other components
- User
- Connected Agents
Connections 21
- User → Desktop App UI: opens app
README.md - Desktop App UI → Project Opening: opens projects
src/App.tsx - Project Opening → Local File API: opens local files
- Desktop App UI → Git Controller: manages Git
- Git Controller → Local Git Operations: calls operations
- Git Controller → Git Lifecycle: uses lifecycle
src/features/source-control/useDesktopGitController.ts - Project Opening → Document Editor: shows documents
- Project Opening → App Preview: previews apps
- Project Opening → Database Preview: previews databases
- Desktop App UI → Agent UI: uses agents
- Agent UI → Agent Runtime: submits references
- Agent Runtime → Agent Protocols: uses protocols
- Agent Host → Agent Runtime: creates runtime
- Desktop App UI → Cloud Authentication: starts sign-in
- Cloud Authentication → Desktop Auth Service: starts OAuth
- Repository Cloud Context → Cloud API: resolves project
src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts - Cloud API → Cloud Folder: accesses folders
README.md - Desktop App UI → Cloud Project Catalog: browses projects
- Cloud API → Cloud Preview: requests preview
- Connected Agents → Cloud Folder: reads and writes
README.md - User → Cloud Folder: shares folder
README.md