# Desktop (/ro/docs/apps/desktop) Instalezi codai desktop, te autentifici, conversezi cu planuri și revizuiri, folosești istoricul și salvarea în cloud, triggerele, memoria, MCP, modelele locale, temele, workbench-ul, controlul computerului și host-urile — apoi actualizezi sau dezinstalezi. codai desktop îl lasă pe asistent să lucreze pe computerul **tău**: rulează comenzi, citește și editează fișiere în folderele pe care le aprobi, conduce un browser într-un profil separat și — pe Windows — dă click prin alte aplicații. Vine cu un mic workbench de cod (editoare Monaco, terminale, explorator de fișiere, vizualizare Git), ca să revizuiești fiecare schimbare înainte să fie aplicată. Apache-2.0, sursa la [github.com/codai-ro/codai-desktop](https://github.com/codai-ro/codai-desktop). ## Instalare [#instalare] Cel mai nou build îl iei de la [codai.ro/download](https://codai.ro/download) sau din [ultima versiune de pe GitHub](https://github.com/codai-ro/codai-desktop/releases/latest). Fiecare versiune este etichetată `desktop-v`; versiunea pe care o rulezi apare în **Settings → Device & gateway → Updates**. Trei artefacte, toate x64: | Fișier | Ce este | | --- | --- | | `codai__x64-setup.exe` | Installer NSIS. Se instalează **doar pentru utilizatorul curent** — fără prompt de administrator. Este cel folosit de actualizatorul automat. | | `codai__x64_en-US.msi` | Pachet MSI pentru instalări administrate / winget. | | `codai__x64-portable.zip` | Build portabil — dezarhivezi și rulezi `codai-desktop.exe`. Fără installer, fără actualizator. | Rulezi `.exe`-ul, apoi pornești **codai** din meniul Start. Windows 10/11 cu WebView2 (prezent deja pe ambele). **Microsoft Store**: build-ul din Store este aceeași aplicație, împachetată MSIX și semnată de Microsoft (fără avertisment SmartScreen). Store-ul o actualizează, așa că actualizatorul integrat și setarea canalului de lansare sunt oprite acolo; **Pornește odată cu Windows** apare și în **Setări → Aplicații → Pornire**. Installerul **nu este încă semnat Authenticode**, așa că SmartScreen poate afișa „Windows protected your PC” la prima rulare. Apasă **More info → Run anyway**, sau verifică întâi descărcarea — vezi [Verifică descărcările](./verify-downloads.mdx). Actualizatorul verifică deja o semnătură minisign la fiecare actualizare. `codai__amd64.AppImage`, `.deb` și `.rpm` sunt construite din aceeași sursă într-o mașină virtuală Linux și atașate versiunilor **atunci când a fost produs un build Linux pentru acea versiune** — unele versiuni au doar artefacte Windows. Verifică pagina versiunii. ```bash # AppImage chmod +x codai__amd64.AppImage && ./codai__amd64.AppImage # Debian / Ubuntu sudo apt install ./codai__amd64.deb # Fedora sudo dnf install ./codai--1.x86_64.rpm ``` AppImage-ul folosește `libGLESv2.so.2` din sistem. Pe un sistem minim care nu îl are, pornește cu copia inclusă și scrie `codai: this system has no libGLESv2.so.2; using the copy bundled in the AppImage` în terminal; ca să folosești varianta sistemului, instalează `libglvnd-gles` (Fedora, openSUSE) sau `libgles2` (Debian, Ubuntu). Controlul computerului și scurtăturile globale (`Ctrl+Alt+C`, `Ctrl+Alt+Space`) sunt **doar pe Windows**. Restul funcționează, dar a fost testat mult mai puțin pe Linux. Nepublicat încă. Proiectul este configurat să producă un `.dmg`, dar niciun build macOS nu a fost produs sau testat. Construiește din sursă cu `pnpm tauri build` dacă ai nevoie azi (necesită Xcode Command Line Tools); pagina Releases îl va lista când apare. ## Pachete necesare pe Linux [#pachete-necesare-pe-linux] Pachetele `.deb` și `.rpm` își declară dependențele, așa că `apt` și `dnf` le instalează singure. AppImage-ul conține majoritatea bibliotecilor, dar folosește tot WebKitGTK-ul sistemului, biblioteca pentru iconița din bara de sistem și driverul grafic. Instalează-le întâi dacă aplicația nu pornește, afișează o fereastră goală sau nu are iconiță în bara de sistem: | Ce trebuie | Debian / Ubuntu (`apt`) | Fedora (`dnf`) | Arch (`pacman`) | | --- | --- | --- | --- | | Vizualizarea web (WebKitGTK 4.1) și GTK 3 | `libwebkit2gtk-4.1-0 libgtk-3-0` | `webkit2gtk4.1 gtk3` | `webkit2gtk-4.1 gtk3` | | Iconița din bara de sistem | `libayatana-appindicator3-1` | `libayatana-appindicator-gtk3` | `libayatana-appindicator` | | Depozitul de secrete pentru cheie | `gnome-keyring libsecret-1-0` | `gnome-keyring libsecret` | `gnome-keyring libsecret` | | Deschiderea linkurilor, intrarea din meniu | `xdg-utils desktop-file-utils` | `xdg-utils desktop-file-utils` | `xdg-utils desktop-file-utils` | | Grafică (OpenGL / EGL), mai ales pentru AppImage | `libegl1 libgl1` | `libglvnd-egl libglvnd-glx` | `libglvnd` | | Rularea unui AppImage | `libfuse2` (`libfuse2t64` pe Ubuntu 24.04) | `fuse-libs` | `fuse2` | ```bash # Debian / Ubuntu sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1 gnome-keyring libsecret-1-0 xdg-utils # Fedora sudo dnf install webkit2gtk4.1 gtk3 libayatana-appindicator-gtk3 gnome-keyring libsecret xdg-utils # Arch sudo pacman -S webkit2gtk-4.1 gtk3 libayatana-appindicator gnome-keyring libsecret xdg-utils ``` - Pe **KDE** poți păstra KWallet în loc de GNOME Keyring: merge orice furnizor Secret Service. Fără unul, aplicația ține secretele într-un fișier pe care doar utilizatorul tău îl poate citi și îți spune asta în **Settings**. - **Fereastră goală sau albă cu driverul NVIDIA.** Aplicația dezactivează deja rendererul DMA-BUF al WebKit când găsește driverul NVIDIA. Ca să-l dezactivezi și în alte configurații, pornește aplicația cu `WEBKIT_DISABLE_DMABUF_RENDERER=1`; cu valoarea `0` îl reactivezi. - Încă nu există un pachet în AUR. Pe Arch, folosește AppImage-ul împreună cu pachetele de mai sus. ## Prima rulare [#prima-rulare] ### Accepți termenii [#accepți-termenii] Primul ecran este **Before you start**: Termenii și Politica de confidențialitate, plus comutatoare opționale (date de antrenare, referral-uri) care sunt consimțăminte separate și nu sunt necesare pentru a folosi aplicația. Când se schimbă o versiune, ești întrebat din nou. ### Te autentifici [#te-autentifici] Două căi: - **Continue in browser** — deschide [auth.codai.ro](https://auth.codai.ro) în browserul de sistem (Google sau e-mail). Când termini acolo, revii în aplicație: a primit o cheie `codai_` pentru **acest dispozitiv**, păstrată în secret store-ul aplicației, doar pe această mașină. - **I have an API key** — lipești o cheie `codai_…` din [hub.codai.ro](https://hub.codai.ro) → **Keys**. Aplicația o verifică pe gateway înainte să o salveze. A treia opțiune, **Use a local model instead**, sare peste cont complet: Ollama sau LM Studio pe acest computer, gratuit și privat, dar fără sincronizarea sesiunilor, partajare sau portofel. Lasă **Gateway URL** la valoarea implicită (`https://ai.codai.ro`) dacă nu te auto-găzduiești. ### Alegi un skin [#alegi-un-skin] **How should codai look?** — alegi **Assistant** (o coloană calmă de conversație, ca aplicația de telefon) sau **Developer** (editor, terminale, panouri — workbench-ul complet). Poți schimba oricând cu `Ctrl+K M` sau din **Settings → Skins**. ## Skin-uri [#skin-uri] *Skin-ul* este învelișul pe care îl randează fereastra principală. Schimbarea nu oprește nimic — terminalele, agenții, editoarele și tab-urile de browser continuă să ruleze dedesubt. | Skin | Ce vezi | Când | | --- | --- | --- | | **Assistant** | O coloană de conversație, un composer, pașii agentului. | Sarcini de zi cu zi, foldere fără cod. Implicit. | | **Developer** | Editor dockabil, revizuire de diff-uri, terminale, explorator de fișiere, Git, panou de supervizare. | Când lucrezi la un proiect. | | **Focus** | Developer cu tot chrome-ul ascuns; `Esc` îl readuce. | Concentrare maximă. | Deschizi un folder fără cod și codai propune Assistant; deschizi un proiect de cod și propune Developer. **Settings → Skins → Use for this workspace only** fixează un skin pe un folder. ## Chat [#chat] ### Trimitere, ghidare și coadă [#trimitere-ghidare-și-coadă] - **Enter** trimite; **Shift+Enter** adaugă un rând nou. - Cât timp rulează o tură, **Enter** cu text **ghidează** tura curentă: mesajul este adăugat ca „waiting for the current step” și agentul îl citește la pasul următor. - **Ctrl+Enter** în timpul unei ture **pune mesajul în coadă** ca tură separată („after this turn”); îl poți elimina înainte să înceapă. - Cu caseta goală în timpul unei ture, butonul de trimitere devine un **Stop** roșu. ### Întâi planul [#întâi-planul] Pastila **Plan** din composer are trei setări: **off** (acționează imediat), **auto** (implicit — face întâi un plan la cererile netriviale: lungi, agentice sau cu fișiere) și **always**. Indiferent de setare, poți forța sau sări planul pentru un singur mesaj (*Plan first: this message* / *Plan first: skip this message*). ### Întrebări de la agent [#întrebări-de-la-agent] Când e nevoie de o decizie, agentul afișează un card — „*N* decision(s) before continuing” — cu o opțiune **recommended** pentru fiecare întrebare. Apeși **Continue with the recommendations**, alegi alte opțiuni sau scrii propriul răspuns. ### Cost și context [#cost-și-context] - Fiecare tură încheiată își arată tokenii și costul (`… tok · $…`, cu `~` când e estimat); ține cursorul deasupra pentru tokenii de prompt, din cache, de completare și numărul de cereri. Composerul arată totalul curent al conversației și o estimare pentru cererea următoare. - **(v0.7+)** Un inel lângă composer arată cât de plină este fereastra de context a modelului (`Context: folosit / fereastră tokeni (pct%)`), inclusiv pragul la care conversația este compactată. ### Revizuirea schimbărilor [#revizuirea-schimbărilor] **(v0.7+)** Modificările propuse se deschid în **Review changes**, câte un hunk pe rând: | Tastă | Acțiune | | --- | --- | | `j` / `k` | Hunk-ul următor / anterior | | `a` / `r` | Accepți / respingi hunk-ul | | `Enter` | Aplici hunk-urile acceptate | **Accept all**, **Reject all** și **Apply (*N* accepted)** acționează asupra întregului set; click dreapta pe un hunk pentru *Accept This Hunk* / *Reject This Hunk*. Poți lăsa și un comentariu pe un hunk — comentariile sunt trimise agentului împreună cu decizia ta, ca să poată revizui. ### Anulezi o tură [#anulezi-o-tură] Înainte ca agentul să scrie un fișier, conținutul anterior este salvat ca checkpoint. Din meniul **Message actions** al unui mesaj: - **Restore checkpoint** — readuce fișierele modificate după acel mesaj și elimină mesajele de dedesubt (dezactivat cât rulează o tură). - **Fork from here** — pornește o conversație nouă de la acel mesaj. Poți pur și simplu să-i ceri agentului să anuleze; el își poate retrage seturile recente de modificări și poate șterge fișierele create de el. ## Istoric, snapshot-uri și revert [#istoric-snapshot-uri-și-revert] Deschizi **History** din bara laterală Assistant (lângă Chat, Sessions și Memory). Listează fiecare schimbare făcută de asistent în folderul deschis, cele mai noi primele, grupate pe zile; deschizi o intrare ca să-i vezi diff-ul. - **Snapshot-uri.** După fiecare tură a agentului care modifică fișiere, codai înregistrează un snapshot: un commit marcat `[codai snapshot]` pe ramura curentă (doar fișierele schimbate; hook-urile Git sunt sărite) plus un ref ascuns de checkpoint. Comportamentul este controlat de **Settings → Workbench → Keep a history of changes automatically** (activ implicit); cu el activ, un folder fără Git primește un depozit și un `.gitignore` la prima deschidere. - **Revert.** Readuce fișierele intrării la starea dinaintea acelui snapshot; celelalte schimbări ale tale rămân neatinse, iar ramura nu este mutată. Revert-ul primește propria intrare, cu **Revert again** pentru a-l anula. Primul snapshot al unui proiect nu poate fi anulat — nu există nimic înaintea lui. - **Restored later.** Un revert nu șterge niciodată fișiere. Fișierele pe care le-ar elimina (create de tura anulată) sunt mutate în `%LOCALAPPDATA%\codai\restored-later\` și listate sub **Restored later (*N*)**. Folosești **Bring back** ca să readuci unul (dacă există deja un fișier acolo, îl poți restaura alături ca `nume (restored …).ext`), **Delete permanently** pentru unul sau **Empty** pentru toate. Această plasă de siguranță există doar în aplicația desktop. Ref-urile ascunse vechi sunt curățate (se păstrează cele mai noi 200 și tot ce e mai nou de 30 de zile); commit-urile în sine rămân. ## Salvare în cloud [#salvare-în-cloud] Cardul **Save to cloud** se află în partea de sus a History și în vizualizarea Source Control. ### Te autentifici cu GitHub [#te-autentifici-cu-github] Un dialog afișează un cod de dispozitiv — **Copy code**, **Open GitHub**, aprobi, iar aplicația îl preia. Tokenul este păstrat în credential helper-ul Git (Git Credential Manager pe Windows) și în secret store-ul aplicației. ### Save to cloud [#save-to-cloud] Creează un depozit **privat** `/` (sau îl refolosește; `-2`, `-3`… dacă numele e ocupat) și trimite proiectul acolo. ### Sync [#sync] Face commit la ce e pe disc, face pull cu rebase și trimite ramura curentă. Dacă atât acest computer, cât și cloud-ul au modificat aceleași fișiere, rebase-ul este abandonat și nu se pierde nimic. **Fold assistant steps into one commit at Save to cloud** (Settings → Workbench, activ implicit) comprimă fiecare serie de commit-uri snapshot codai consecutive, netrimise încă, într-unul singur înainte de push. Commit-urile tale și tot ce a fost deja trimis nu sunt rescrise niciodată și nu există force-push. Salvarea în cloud are nevoie de client id-ul unei aplicații GitHub OAuth. Build-urile livrate fără unul afișează *Cloud saving is not configured in this build*. Creezi o aplicație GitHub OAuth cu device flow activat și lipești client id-ul în **Settings → Workbench → GitHub app for cloud saving**. ## Triggere și Inbox [#triggere-și-inbox] Paleta de comenzi → **Open event triggers** sau **Open inbox** deschide un tab cu **Triggers** și **Inbox**. Trebuie să fii autentificat în codai. - **New trigger** — alegi o sursă: **GitHub**, **Sentry**, **Google Cloud alerts**, **Any webhook (signed JSON)** sau **Contact / feedback form**. Primești un **Webhook URL** și un **Signing secret** (afișat o singură dată). GitHub și Sentry au butoane de configurare dintr-un click. - **What happens on an event** — modul (Notify only, Assisted, Autopilot, Smart după severitate; Autopilot nu face niciodată deploy), ce poate face agentul (Read only, Edit files, Open a PR), un prag de severitate, sesiuni pe oră, ore de liniște, bugete pe eveniment și pe zi, filtre și un prompt pentru agent cu substituenți `{{event.*}}`. - **Test fire**, **Enable/Disable**, **Rotate secret**; **Recent events** arată la ce a dus fiecare eveniment. - **Inbox** adună notificările de la triggere și sarcinile din cloud, necitite primele, cu **Mark read**, **Mark all read** și **Open link**. ### Ingress local [#ingress-local] Ca să primești webhook-uri de la unelte de pe propria mașină sau din LAN fără un URL public, activezi **Local ingress** într-un trigger (dezactivat implicit): **Listen for local webhooks**, **Listen on** *This computer only (127.0.0.1)* sau *Local network (LAN)* (caz în care **Allowed networks (CIDR)** este obligatoriu), **Port** (implicit `8788`), **Apply**. Setezi **Accept events from** al triggerului pe *Local ingress only* sau *Both*. Expeditorii trimit la `http://127.0.0.1:8788/hooks/`, semnat exact ca pentru URL-ul public; aplicația transmite corpul brut către gateway cu cheia ta. Corpul este limitat la 1 MiB, 60 de cereri pe minut, iar `Content-Length` este obligatoriu. Payload-urile și semnarea sunt descrise în [API-ul de triggere](../api/gateway/triggers.mdx). ## Memorie [#memorie] Deschizi **Memory** din bara laterală Assistant sau din meniul de layout. Notițele sunt fișiere Markdown pe care agentul le poate găsi și citi: | Tab | Unde | | --- | --- | | **User** | `~/.codai/memories` — toate proiectele | | **Repo** | `/.codai/memories` — acest proiect | | **Session** | doar această sesiune | | **Imported** | vizualizare doar-citire a `~/.claude/*.md`, `~/.claude/rules/*.md` și a folderelor de memorie VS Code ale acestui workspace | Folosești **New note**, **Rename**, **Delete**, **Edit** (deschide în editor) și **Search** (text integral, rezultate `fișier:linie`). Notițele importate nu sunt copiate — sunt citite de unde se află. Agentul învață și singur: un **playbook** de sfaturi scurte verificate, cu contoare utile/dăunătoare și un scor de încredere, **lecții** (simptom → ce se credea → ce s-a dovedit → soluție) și **episoade** (obiectiv, rezultat, verificat). Le revizuiești în **Settings → Executor → Memory & tools**: notezi elementele din playbook cu 👍/👎, **Consolidate now** (rulează și după 10 minute de inactivitate), **Export JSONL** (în `%LOCALAPPDATA%\codai\exports\`). Sunt păstrate în `%LOCALAPPDATA%\codai\memory.sqlite` și nu părăsesc niciodată acest PC. ## Servere MCP [#servere-mcp] **Settings → Executor → MCP servers** listează serverele pe care agentul le poate folosi, cu un comutator **Enabled**, starea (*Connected · N tools*, *Error*, *Disabled*), **Reconnect** și **Reconnect all**. Stările apar după prima rulare a agentului. Adaugi servere în JSON — fișierele ulterioare câștigă per id: 1. `~/.codai/mcp.json` 2. `/.codai/mcp.json` 3. `/.vscode/mcp.json` Sunt acceptate atât cheia `servers` (VS Code), cât și `mcpServers` (Claude Desktop), deci fișierele existente funcționează neschimbate: ```json { "servers": { "files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "remote": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer …" } } } } ``` Două transporturi: **stdio** (`command`, `args`, `cwd`, `env`) și **Streamable HTTP** (`url`, `headers`; intrările cu `"type": "sse"` folosesc același client). Agentul vede uneltele ca `mcp:_`, iar fiecare apel MCP cere aprobare, ca orice altă acțiune. **One-click servers** adaugă un preset cu un token păstrat în keychain-ul sistemului — deocamdată **Brivio** (doar citire). **(v0.7+)** Serverele la distanță care cer OAuth afișează un buton **Sign in** în locul câmpului de token. ## Modele locale [#modele-locale] Două moduri de a rula modele pe acest PC (**Settings → Providers**): - **codai engine** *(Windows x64)* — un server llama.cpp administrat. Aplicația descarcă build-ul llama.cpp potrivit plăcii tale video (CUDA 12, CUDA 13 pe Blackwell, Vulkan sau CPU) în `%LOCALAPPDATA%\codai\engine\`, apoi modele GGUF de pe Hugging Face (cu sumă de control verificată, descărcare reluabilă) în `%LOCALAPPDATA%\codai\models\` sau într-un folder ales de tine. Alegi **Download**, **Use**, **Switch** sau **Stop**; serverul ascultă pe un port aleator `127.0.0.1` și adoarme după 10 minute de inactivitate. **Re-tune GPU split** măsoară cât din model încape pe GPU și reține rezultatul per model și driver. - **Ollama / LM Studio** — dacă rulează pe porturile lor implicite (`11434` / `1234`), sunt detectate și listate lângă codai engine. ## Teme [#teme] **Settings → Color Themes** are 12 teme incluse — codai Dark (implicită), codai Light, Midnight Blue, Forest, Ember, Rosé Noir, Paper, Sky, Mint, Blossom, Dark High Contrast, Light High Contrast — plus **Follow system**. Temele tale sunt fișiere JSON în `%USERPROFILE%\.codai\themes\` (**Theme folder** îl deschide). Folosești **New theme**, **Duplicate**, **Edit JSON**, **Import JSON…** sau **Export JSON…**; modificările fișierelor se aplică în câteva secunde, fără reîncărcare. Un fișier de temă are `id`, `name`, `base` (`dark`/`light`), `accentHue`, `colors` (`bg`, `bgElevated`, `bgPanel`, `border`, `borderStrong`, `foreground`, `muted`, `muted2`, `danger`, `success`, `warning`) și, opțional, culorile ANSI `terminal`. **Use for this project** scrie `/.codai/theme.json`. ## Workbench [#workbench] În skin-ul Developer: - **Explorator** (`Alt+4`), **Deschidere rapidă** (`Ctrl+P`), **Căutare în fișiere** (`Ctrl+Shift+F`). - **Terminal** — comuți cu ``Ctrl+` ``, deschizi unul nou cu `Ctrl+Shift+~`, împarți cu `Ctrl+Shift+5`. Pe Windows: PowerShell 7 (dacă este instalat), Windows PowerShell sau Command Prompt. - **Sarcini** — definite în `/.codai/tasks.json` (`label`, `command`, opțional `args`, `cwd`). Fără acest fișier, sarcinile vin din scripturile `package.json` și din `Cargo.toml`. Fiecare sarcină rulează într-un terminal vizibil; `Ctrl+Shift+B` o rulează din nou pe ultima. - **Source Control** (`Ctrl+Shift+G`) — schimbări, commit-uri și cardul Save to cloud. **(v0.7+)** **Open pull request** și starea CI pentru ramura curentă, prin GitHub CLI (`gh`, autentificat). - **Ferestre detașate** — click dreapta pe un tab de editor → **Move into New Window**. ## Mecanismele agentului [#mecanismele-agentului] ### Instrucțiunile proiectului [#instrucțiunile-proiectului] La începutul unei ture, agentul citește din rădăcina folderului deschis: `AGENTS.md`, `CLAUDE.md` **(v0.7+ în rădăcina depozitului)**, `.claude/CLAUDE.md` și `.github/copilot-instructions.md`; din folderul tău home `~/.claude/CLAUDE.md` și `~/.copilot/copilot-instructions.md`. Regulile din `.github/instructions/*.instructions.md` și `~/.claude/rules/*.md` sunt adăugate când globurile lor `applyTo:` / `paths:` se potrivesc cu fișierele atinse. Fiecare fișier este limitat la 12.000 de caractere (48.000 în total). ### Skill-uri [#skill-uri] Un skill este un folder cu un `SKILL.md`. Agentul vede un index și deschide un skill când se potrivește. Sunt căutate în `~/.agents/skills`, `~/.copilot/skills`, `~/.claude/skills`, `~/.codai/skills`, apoi în `.github/skills` și `.codai/skills` ale proiectului — skill-urile proiectului le înlocuiesc pe cele personale, care le înlocuiesc pe cele incluse în aplicație. ### Subagenți [#subagenți] Pentru sarcini mai mari, agentul poate delega: - **explore** — investigație doar-citire într-un context nou; întoarce un rezumat cu referințe `fișier:linie`. - **review** — evaluează un diff față de plan și întoarce constatările. - **spawn_agent** — roluri explore, research, code, verify, review; până la 4 rulează în paralel după o singură aprobare, iar un agent de cod poate edita doar căile primite. - **ask_expert** — o întrebare către modelul frontier codai, maximum 4 per sarcină. ### Hook-uri [#hook-uri] Hook-urile rulează scripturile tale la `PreToolUse`, `PostToolUse` și `Stop`. Sunt citite din `~/.codai/hooks.json`, `~/.copilot/hooks.json`, `~/.copilot/hooks/*.json`, `/.codai/hooks.json` și `/.github/hooks/*.json`. Codul de ieșire `2` blochează acțiunea, iar mesajul este arătat agentului; timeout-urile (implicit 5 s) și alte erori lasă acțiunea să treacă. `PreToolUse` se declanșează pentru editări de fișiere și uneltele desktop. ### Poarta de reguli [#poarta-de-reguli] Un set minim inclus se aplică mereu: agentul nu poate modifica reguli, hook-uri, skill-uri, fișiere de instrucțiuni sau chei (poate doar propune schimbări), nu poate plăti peste mandatul portofelului tău și nu poate rescrie jurnalul de audit. Regulile contului tău sosesc ca manifest semnat, reîmprospătat la fiecare 6 ore. Dacă regulile nu pot fi încărcate, autonomia este forțată pe **Strict**. ## Niveluri de autonomie [#niveluri-de-autonomie] Autonomia controlează ce poate face agentul pe computerul tău **fără să întrebe**. Se aplică controlului computerului (aplicații Windows) și apare în bara de stare — click pentru a comuta. | Nivel | Comportament | | --- | --- | | **Strict** | Întreabă înainte de fiecare acțiune în aplicații sensibile și înainte de orice combinație de taste care poate închide sau distruge lucru. | | **Assisted** | Acționează liber în aplicații obișnuite; întreabă în cele sensibile (parole, banking, setări) și nu tastează niciodată secrete. **Recomandat.** | | **Autopilot** | Fără porți de aprobare, cu excepția filtrului de credențiale. Folosește-l doar când privești. | Independent de autonomie, comenzile shell, scrierile de fișiere și acțiunile din browser cer aprobare **prima dată per sesiune**: **Allow once**, **Always allow (this session)** sau **Deny**. Citirea fișierelor și un snapshot de browser nu întreabă niciodată. ## Controlul computerului și overlay-ul [#controlul-computerului-și-overlay-ul] **Settings → Computer control** îi permite agentului să vadă și să opereze aplicații Windows prin UI Automation: citește controalele unei ferestre, dă click, tastează, derulează, deschide programe. Acțiunile sunt filtrate de nivelul de autonomie de mai sus și oglindite pe **overlay** — un cursor fantomă, un inel de evidențiere pe țintă și o legendă care spune ce urmează să facă agentul. Dezactivezi overlay-ul cu *Show the overlay while the agent acts* dacă te distrage. **Buton de oprire:** `Ctrl+Alt+Space`, sau `Esc` de două ori, oprește agentul instantaneu. Propriile tale mișcări de mouse sau taste îl pun pe pauză. Doar Windows. ## Host-uri — servești telefonul și browserul [#host-uri--servești-telefonul-și-browserul] **Settings → Executor → Serve as a remote host for my phone** transformă acest desktop într-un **host**: o mașină pe care ceilalți clienți ai tăi pot rula operații de terminal și fișiere, în interiorul folderelor permise. Bara de stare arată *Relay: online* cât timp conexiunea la gateway este activă. Cine îl folosește: - **Aplicația Android** — sarcini de tip „rulează asta pe PC-ul meu” și backend-ul de terminal `hosts`. - **Aplicația web** de la [app.codai.ro](https://app.codai.ro) — selectorul **Run on** listează desktopurile tale online; browserul conversează, această mașină execută. Vezi [Web](./web.mdx). Doar dispozitivele autentificate cu **același cont** pot vedea sau folosi un host; un host dispare din listă 45 de secunde după ultimul heartbeat. Detaliile protocolului sunt pe pagina [releu de host-uri](../sessions/hosts.mdx). Separat, **`Run tasks dispatched to this device`** (aceeași secțiune de setări) permite telefonului sau hub-ului să *trimită* o sarcină întreagă către acest desktop; acesta verifică la fiecare 30 de secunde și o rulează aici. ## Dispozitive, chat flotant și cont [#dispozitive-chat-flotant-și-cont] - **Devices** (bara laterală, `Alt+3`) listează fiecare dispozitiv din contul tău — desktop, Android, iOS, web, CLI, agent — cu *this device* și *seen …*. **Revoke** scoate un dispozitiv din prezență și din dispecerizare; nu revocă cheia API a acelui dispozitiv (asta o faci din hub). - **Chat flotant** — `Ctrl+Alt+C` din orice aplicație *(scurtătura globală este doar pe Windows)*, elementul din tray **Floating chat** sau paleta de comenzi. O fereastră mică, mereu deasupra; închiderea ferestrei principale o ascunde în tray, iar **Quit** din tray închide aplicația. - **Start with Windows** (Settings → Chat) pornește codai ascuns în tray la autentificarea în Windows. - **Credits** (Settings → Account) arată soldul preplătit, expirarea, promoțiile și ultimele 10 înregistrări. - **Referrals** (Settings → Account) — alegi un nume de utilizator și îți dai consimțământul ca să primești **Your invite link**; vezi Invited / Rewarded / Pending sau introduci codul unui prieten înainte de termen. ## Ce poate atinge [#ce-poate-atinge] **Settings → Executor**: - **Approved folders** — singurele locuri unde uneltele de fișiere pot citi sau scrie. Implicit: folderul tău home. Căile sunt canonicalizate, așa că `..` și symlink-urile care ies în afară sunt refuzate. - **Browser executable** — detectează automat Edge sau Chrome; lansat mereu cu **propriul folder de profil**, așa că tab-urile, cookie-urile și parolele tale nu sunt implicate niciodată. - **Budgets** — timeout-uri pentru o comandă (implicit 30 s), un apel de unealtă și o tură întreagă (implicit 10 minute). Output-ul este limitat la 64 KB per stream. - **Semantic search** — model local opt-in (`multilingual-e5-small`, descărcare unică de ~205 MB) care indexează workspace-ul pe acest PC. Nimic nu îl părăsește. ## Actualizări [#actualizări] Aplicația caută actualizări la 60 de secunde după pornire și apoi la fiecare 6 ore. Dacă apare o versiune mai nouă, descarcă installerul, îi verifică **semnătura minisign față de cheia publică compilată în aplicație** și îl instalează când nu mai e deschisă nicio fereastră de workspace. O actualizare a cărei semnătură nu se potrivește este refuzată; actualizatorul nu face niciodată downgrade. Verifici manual din **About → Check for updates**. Build-ul din Microsoft Store este actualizat de Store; acolo **Check for updates** raportează mereu versiunea instalată ca fiind la zi. ### Canale [#canale] **Settings → Device & gateway → Updates → Channel**: **Stable** (`https://codai.ro/api/desktop/latest.json`, implicit) sau **Beta** (`https://codai.ro/api/desktop/beta/latest.json`). Schimbarea se aplică la verificarea următoare, fără repornire. Revenirea de la Beta la Stable nu face niciodată downgrade — îți păstrezi versiunea până când Stable o depășește. Dacă contul tău a activat Beta pentru tine, alegerea ta proprie are prioritate. Versiunile listează `windows-x86_64`, plus `linux-x86_64` când a fost construit un AppImage pentru acea versiune. `.zip`-ul portabil nu are actualizator. ### Actualizări de interfață [#actualizări-de-interfață] Corecturile mai mici ale interfeței pot sosi ca **pachet UI semnat**, fără reinstalare. Când unul este gata, vezi *Interface … is ready — reload to use it* cu **Reload now** sau **Reload when idle**. Fiecare fișier este verificat față de manifestul semnat; dacă noua interfață nu pornește sau se blochează, aplicația revine la cea anterioară și blochează versiunea defectă. ## Dezinstalare și locațiile datelor [#dezinstalare-și-locațiile-datelor] Dezinstalezi din **Settings → Apps** (Windows) sau cu managerul de pachete (Linux). Dezinstalarea **nu** șterge datele tale: | Ce | Unde (Windows) | | --- | --- | | Cheia ta | Windows Credential Manager (serviciul `ro.codai.desktop`) | | Setări, id-ul dispozitivului, registrul brokerului, canalul de actualizare | `%APPDATA%\ro.codai.desktop\` (`settings.json`, `device.json`, `broker.json`, `update-channel.json`) | | Trace-uri, memorie (`memory.sqlite`), checkpoint-uri de fișiere, Restored later, stare per workspace, motorul local și modelele | `%LOCALAPPDATA%\codai\` | | Memoriile, temele, serverele MCP, hook-urile și skill-urile tale | `%USERPROFILE%\.codai\` | | Profilul de browser folosit de unealta browser | în `%LOCALAPPDATA%\codai\` | Pe Linux aceleași foldere sunt sub `~/.config/ro.codai.desktop` și `~/.local/share/codai`. Înainte de dezinstalare, **Settings → Sign out** revocă pe server cheia acestui dispozitiv. Dacă ai uitat, revoc-o din [hub.codai.ro](https://hub.codai.ro) → **Security → Devices**. ## Liste și Trimite în codai [#liste-și-trimite-în-codai] **Liste** (bara laterală, `Alt+0`) păstrează linkurile, textul, imaginile și fișierele trimise în codai: **Inbox**, **Wishlist** și **Notițe** există de la început, iar alte liste le adaugi sau le reordonezi din **Setări → Liste**. **Lipește din clipboard** salvează ce ai copiat; fără o listă aleasă ajunge în Inbox și codai sugerează unde îi e locul. `Ctrl+Alt+S` face același lucru din orice aplicație, iar varianta din Microsoft Store apare în meniul de partajare Windows. O captură de ecran din clipboard se lipește direct în chat ca imagine. Linkurile de produse primesc titlu, imagine, preț și stoc; deschide o listă ca s-o exporți în Markdown sau să **întrebi codai** despre ea. Aceleași liste sunt pe telefon (meniul de partajare, partajare directă pe fiecare listă) și pe hub.codai.ro/lists. ## Taste [#taste] | Scurtătură | Acțiune | | --- | --- | | `Enter` | Trimite; în timpul unei ture, o ghidează | | `Ctrl+Enter` | În timpul unei ture, pune mesajul în coadă ca tura următoare | | `Esc` | Anulează tura în curs (pagina sesiunii) | | `Ctrl+Alt+C` | Deschide sau ascunde chat-ul flotant (din orice aplicație) | | `Ctrl+Alt+Space` | Buton de oprire — oprește controlul computerului (`Esc` ×2 la fel) | | `Ctrl+Shift+P` | Paleta de comenzi | | `Ctrl+P` | Deschidere rapidă | | `Ctrl+Shift+F` | Căutare în fișiere | | ``Ctrl+` `` | Comută terminalul | | `Ctrl+K M` | Comută skin-urile | | `Ctrl+Shift+G` | Vizualizarea Git | | `Alt+3` | Dispozitive | | `Ctrl+Alt+S` | Salvează clipboard-ul într-o listă (din orice aplicație) | | `Alt+0` | Liste | | `Ctrl+,` | Setări | Fiecare combinație poate fi schimbată în editorul de scurtături (`Ctrl+K Ctrl+S`).