caelo: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

⚠️ READ FIRST — this repo is Caelo 2.0, not Caelo 1.x

This repository is a clone of grok_desktop_app (Caelo 0.1.5) taken as the foundation for Caelo 2.0, whose goal is merging Caelo with gemini-desktop-studio into one multi-provider app (xAI + Google). Everything below this banner still describes the code as it stands, and is accurate — but the target architecture is different, and the decisions in this section override anything below them when the two disagree.

Plan (source of truth for the integration): docs/plans/PLAN_INTEGRACJI.md

Git: the remote caelo-1x points at the local 1.x repo (for cherry-picking fixes). Since 2026-09-22 origin is the public repo AuraVixStudio/caelo (the user selected it) and Caelo 2.0 lives on its main. Upstream tracking is still deliberately off — git push alone does nothing, so publishing is always an explicit git push origin main. Never push to caelo-1x, and treat every push to origin as publishing: main is protected by 6 required status checks, so a push that bypasses them leaves CI to catch up afterwards.

The central idea

Caelo is the host. gemini-desktop-studio is the donor of the media architecture. xAI loses its privileged path.

The last part is the one that gets missed. Today api_manager.APIManager is called directly from backend_media.py, and responses_client.py says in its own docstring that it is „nie multi-provider". If Google is simply bolted on next to that, we get two parallel code paths inside one process — the exact problem the merge exists to remove. So xAI moves behind the new provider abstraction too. Refactoring xAI is part of the work, not a side effect.

Architecture decisions (ADR-1…8)

Full context and consequences in the plan; this is the binding summary.

#	Decision	Consequence for you
ADR-1	Google via raw REST (requests), not an SDK.	Every xAI call in this repo is already hand-rolled requests — no SDK anywhere. Keep it that way. @google/genai is documentation of the wire shape only. GCP/Vertex AI through ADC is required; google-auth is allowed only for acquiring/refreshing ADC credentials, while API calls remain raw requests. Phase-0 live result: Omni works through Agent Platform v1beta1 global Interactions with delivery: inline (URI requires gcs_uri) — but on Vertex the model id is gemini-omni-1.1-flash-preview, NOT the bare gemini-omni-1.1-flash the AI Studio catalog uses (LIVE 2026-09-01: bare id → 400 Unsupported model interaction). Mapped on the wire by VERTEX_OMNI_IDS, like VERTEX_VEO_IDS — the catalog/pricing id stays bare. Omni also needs a Vertex quota increase for that preview base model; with the default 0 quota every submit is 429; Veo uses regional Vertex v1, predictLongRunning + fetchPredictOperation, and the GA veo-3.1-fast-generate-001 model.
ADR-2	The Gemini queue model wins; caelo_core/genjobs.py is replaced, not extended.	Port the state machine from JobQueue.ts + JobRecovery.ts + RetryPolicy.ts. xAI becomes a handler under it, exactly like Google.
ADR-3	Gemini's normalized media schema wins; Caelo's history/FTS5/embeddings stay.	Add generations / generation_inputs / generation_outputs / jobs / … to caelo_history.db. Do not touch history_events, history_fts, event_embeddings. artifacts stays as the gallery index.
ADR-4	Model registry + capability guard live in Python and are the only source of truth.	The renderer holds no model lists. It reads /providers + /models at runtime; TS types are generated from the Python definitions and checked in CI.
ADR-5	Electron safeStorage is the secret vault; the sidecar receives secrets in memory.	No more plaintext keys in caelo_settings.json / caelo_auth.json. Pass them over the authenticated handshake channel — never via environment variables (they leak to the process list).
ADR-6	Gemini's React pages are NOT ported — only their logic.	Caelo's UI kit (Tailwind 4, components/ui/*) is the target. Zustand and TanStack Query do not enter. Exceptions: Asset Inspector and Diagnostics are new screens, built from scratch in Caelo's kit.
ADR-7	No Google code in the repo-root modules.	Nothing Google-related may touch config.py, api_manager.py, oauth_manager.py, chats_manager.py, history_manager.py (see "The single most important structural fact" below). Google lives only in caelo_core/providers/google/. The xAI provider is an adapter wrapping APIManager, not a rewrite of it.
ADR-8	Neutral tool-calling format at the agent boundary.	agent/session.py must see only the neutral format; each provider supplies a two-way adapter. xAI is OpenAI-shaped; Google uses functionCall/functionResponse parts. Phase-0 live result (gemini-3.5-flash): preserve native functionCall.id and copy it to functionResponse.id; synthesize an id only for older responses that omit it. Preserve the full model part with thoughtSignature, keep all parallel calls before their responses, and assemble streamed partialArgs by JSONPath.