Research Proposal: Cloud State Sync

This document explores the architectural shift of moving the global ~/.gemini folder to the cloud. The goal is to enable a shared data store for plans, settings, and configurations across devices, instances, and sessions while maintaining performance, security, and portability.

Objective

Transition Gemini CLI from a local-first state management system to a distributed, synchronized agent. This allows you to start a task on one machine (e.g., a local laptop) and resume it seamlessly on another (e.g., a remote workstation or a different office machine).

Data Categorization

Not all data within ~/.gemini should be treated equally. We categorize the contents to determine the most effective synchronization strategy.

Static and Configuration: settings.json, projects.json, and policies/. These are small files with low-frequency updates, making them ideal for simple cloud synchronization.
Sensitive and Identity: google_accounts.json and installation_id. These contain refresh tokens and unique identifiers that require high-grade, client-side encryption before leaving the device.
High-Volume and Ephemeral: history/, tmp/, and antigravity/ (browser profiles). These are large or frequently updated. Naive synchronization would be slow and resource-intensive.
Computed and Environment-Specific: extension_integrity.json and trustedFolders.json. These often contain absolute local paths that may not be valid across different machines or operating systems.

Architectural Approaches

We are evaluating three primary methods for implementing cloud synchronization.

Virtual Filesystem (VFS) Layer

Implement an abstraction layer for Node.js fs calls that transparently redirects operations to a cloud provider like GCS or S3.

Pros: Requires minimal changes to existing high-level logic.
Cons: Network latency on every file operation could degrade the user experience. Requires a robust local LRU (Least Recently Used) cache.

Git-Ops and Snapshot Syncing

Automatically commit and push state changes to a private, hidden repository.

Pros: Provides built-in versioning, conflict resolution, and portability.
Cons: High overhead for frequent, small writes, such as session history updates.

Centralized State Server (The "Brain")

Communicate with a lightweight service (gRPC or WebSockets) that acts as the single source of truth for the agent's state.

Pros: Enables real-time synchronization across active sessions.
Cons: Requires a hosted service and a persistent internet connection.

Technical Considerations

The following table outlines the primary technical challenges and proposed solutions for a cloud-synced state.

Dimension	Challenge	Potential Solution
Performance	Shell startup latency is critical.	Stale-While-Revalidate: Load local cache instantly; sync in the background.
Security	Secrets management in the cloud.	Zero-Knowledge Encryption: Encrypt secrets client-side with a user passphrase.
Portability	Inconsistent absolute paths.	Path Normalization: Store paths relative to `$HOME` or use UUIDs.
Conflicts	Simultaneous edits on multiple devices.	CRDTs: Use Conflict-free Replicated Data Types for plans and history.

Hybrid Strategy Proposal

A tiered synchronization model balances performance with portability.

Tier 1 (Cloud Native): Sync settings, plans, and global memories immediately via a structured API.
Tier 2 (Lazy Sync): Upload session history and logs at the end of a session or when explicitly resuming on another device.
Tier 3 (Local Only): Keep large caches, browser profiles, and environment-specific integrity checks local to the device.

Next Steps

To move forward with this proposal, we must perform the following actions:

Audit the current ~/.gemini directory to determine the typical data volume, particularly within the history/ folder.
Identify all files within ~/.gemini that contain environment-dependent absolute paths.
Prototype a synchronization provider using a private Git repository or a dedicated cloud storage bucket.

4.2 KiB Raw Permalink Blame History