Manuale
IA
Omarchy include launcher per gli agenti di coding elencati di seguito senza sceglierne uno predefinito per te. Esegui un comando per installare la sua CLI al primo utilizzo, poi autenticati quando richiesto. Hermes è l’eccezione: al primo utilizzo non viene installato nulla per lui e, se lo scegli, viene installato Hermes Desktop, come spiega App desktop più avanti.
| Comando | Agente |
|---|---|
claude |
Claude Code |
codex |
OpenAI Codex |
opencode |
OpenCode |
agy |
Google Antigravity CLI |
amp |
Amp |
commandcode |
Command Code |
copilot |
GitHub Copilot CLI |
crush |
Crush |
cursor-agent |
Cursor CLI |
devin |
Devin CLI di Cognition |
dsh |
DeepSeek Harness |
freebuff |
Freebuff, l’agente di coding gratuito e supportato da pubblicità di Codebuff |
grok |
Grok Build di xAI |
hermes |
Hermes, l’agente di Nous Research |
kilo |
Kilo, un agente di coding basato su OpenCode |
kimi |
Kimi Code |
kiro-cli |
Kiro CLI |
mcode |
MiniMax Code, l’agente di coding di MiniMax |
muse |
Muse Code, l’agente di coding di Meta |
omp |
Oh My Pi |
ori |
Ori, l’harness di OpenRouter |
pi |
Pi di Mario Zechner |
qwen |
Qwen Code, l’agente di coding di Alibaba |
ori è il caso a parte: esegue gli altri harness sull’intero catalogo di modelli di OpenRouter, quindi ori claude, ori codex o ori opencode avviano quegli agenti su qualsiasi modello tu indichi, mentre ori code è l’agente di Ori stesso.
Installazione e aggiornamento degli agenti
Tranne Hermes, questi agenti usano l’installazione lazy di mise: il primo avvio installa la CLI e gli avvii successivi la riutilizzano. mise controlla anche se per un agente installato c’è una nuova release al massimo una volta ogni quattro ore, subito prima del suo avvio o in background al prompt della shell. Se quell’aggiornamento fallisce o sei offline, viene eseguita la versione installata. omarchy update aggiorna gli agenti installati insieme al resto di Omarchy, mentre mup aggiorna solo gli strumenti gestiti da mise.
L’updater proprio di un agente, come claude update, codex update o un pulsante di aggiornamento in un’app, non aggiorna l’installazione gestita da mise. codex update fallisce, e claude update può segnalare un successo installando però una copia separata che mise non tiene tracciata. Se preferisci usare l’installer e l’updater nativi di un agente, aggiungilo a disable_tools; vedi Strumenti CLI preinstallati.
Per installare tutti gli strumenti lazy configurati prima di averne bisogno, esegui mise install --include-lazy. Sono inclusi anche gli altri strumenti CLI predefiniti di Omarchy, oltre agli agenti. Vedi Strumenti CLI preinstallati per installare un singolo strumento o usare una tua installazione.
grok viene installato tramite il pacchetto first-party grok di mise, allo stesso modo di claude e codex. Esegui grok, oppure sceglilo in Setup > Defaults > Agent. Evita l’installer curl | bash su x.ai. Quel percorso mette una seconda copia in ~/.grok/bin, la antepone nel PATH e sovrascrive il wrapper di Omarchy.
dsh apre la sua interfaccia browser su 127.0.0.1:3080, con la directory di avvio come workspace predefinito. La sua interfaccia browser non accetta un prompt iniziale, quindi omarchy agent prompt la apre con il prompt negli appunti, pronto da incollare. Omarchy lo avvia con il preset di permessi senza approvazione di DeepSeek. DeepSeek Harness carica i log di sessione su DeepSeek quando usi la sua API ufficiale dei modelli; disattivalo in Settings > General > Upload Session Log nella sua interfaccia browser. Anche i feedback che gli invii vengono caricati insieme alla sessione, a meno che tu non lo avvii con DSH_TELEMETRY_MODE=DISABLED.
L’agente predefinito
Scegli il tuo agente predefinito con omarchy default agent <name> oppure in Setup > Defaults > Agent nel Menu Omarchy (Super + Space). Se l’agente non è ancora installato, sceglierlo lo installa prima. Un Omarchy appena installato ti inviterà a fare questa scelta con una notifica mostrata una sola volta.
Scegliere Claude prova anche a configurare la sua estensione per browser per Chromium, Chrome, Brave, Brave Origin ed Edge. La configurazione dell’estensione si applica a tutti gli utenti e potrebbe chiederti la password di sistema; annullare o un’installazione dell’estensione fallita seleziona e avvia comunque Claude. Riavvia il browser, abilita l’estensione se richiesto e accedi a Claude per completare la connessione. Esegui /chrome in Claude per controllare la connessione. Firefox e Zen non supportano questa estensione. Se Claude era già il tuo predefinito prima che questa configurazione venisse aggiunta, selezionalo di nuovo per installare l’estensione.
Una volta scelto, Super + Shift + Ctrl + A avvia l’agente predefinito in una finestra di terminale dedicata (oppure mostra il selettore se non hai ancora scelto). Puoi anche avviarlo direttamente su un’attività con omarchy agent prompt "Review this project". Freebuff e DeepSeek Harness non accettano un prompt iniziale, quindi si aprono con il prompt negli appunti, pronto da incollare. Gli agenti avviati in questo modo lavorano senza supervisione nelle rispettive modalità “non fermarti a chiedere”, quindi preparati al fatto che facciano davvero cose! MiniMax Code non ha una modalità del genere per le sue sessioni interattive, quindi chiede i permessi come al solito. E siccome gli agenti rifiutano di memorizzare la fiducia per la tua directory home, gli avvii da $HOME partono invece in ~/Work.
Ci sono anche scorciatoie da terminale: a esegue l’agente predefinito inline nel terminale corrente, mentre c, cx e cy avviano direttamente OpenCode, Claude Code e Codex (anche in questo caso nelle loro modalità ad approvazione automatica). Anche i cambi di tema si sincronizzano con gli agenti: Claude Code, Pi, OpenCode ed Hermes (una volta che Omarchy lo ha installato) ti seguono tutti quando cambi il tema di Omarchy.
Il pannello degli agenti
La barra superiore ha un’icona degli agenti. Prima che tu abbia configurato un agente, il suo pannello ti accompagna nell’accesso a Claude, Codex o Grok, e il primo diventa il tuo agente predefinito. Dopo, il pannello mette ogni abbonamento in un’unica pagina: ogni agente e account con il suo piano, un indicatore per ciascuno dei suoi limiti di sessione di 5 ore e settimanali con il tempo che manca al reset (passa il mouse sopra per la percentuale esatta), oppure il saldo prepagato rimanente, sotto una riga che ruota tra ciò che hai usato in tutti loro, come i token di questa settimana e il tuo modello più usato. In Make something offre prompt iniziali per un nuovo tema, plugin o app che affidano il compito al tuo agente predefinito. Le app sono costruite allo stesso modo delle app di Omarchy Hype, Monologue e Omacut, in C++ e Qt Quick, seguendo la skill per agenti omarchy-app, e il compilatore e i componenti Qt che servono sono già installati. Claude Code, Codex, Grok, Kimi, Cursor e la sua quota Grok Bot, GitHub Copilot, Muse, Antigravity, Kimchi e Devin sono coperti immediatamente con i loro limiti, ed Hermes, Mistral Vibe e Qwen Code mostrano le loro sessioni e i loro token una volta che li hai usati. Compaiono anche i piani e le chiavi dei provider che usi tramite pi, omp o opencode: OpenCode Zen e Go, lo Z.ai GLM Coding Plan, Ollama Cloud, il MiniMax Token Plan e Synthetic con i loro limiti; Fireworks, OpenRouter e DeepSeek con i loro saldi prepagati; e i modelli che esegui sul tuo hardware in Local models. Ogni agente viene contato una sola volta, sotto chi lo fattura, indipendentemente da quanti harness usi per pilotarlo.
Fai clic con il pulsante sinistro sull’icona nella barra per il pannello, clic con il pulsante destro per avviare il tuo agente predefinito. I dati di utilizzo dietro di esso vengono rigenerati ogni 15 minuti da omarchy agent usage-update, e il pannello può persino unire l’utilizzo delle tue altre macchine tramite una cartella sincronizzata. Vedi il README in $OMARCHY_PATH/shell/plugins/agents/ per tutte le impostazioni.
Più abbonamenti
Se paghi più di un piano Claude, Codex o Grok - un Max personale e uno di lavoro, per dire - Omarchy può mantenerli tutti connessi e passare dall’uno all’altro. Aggiungi un abbonamento con il + nel pannello degli agenti, che ti accompagna lì sul posto, oppure con omarchy agent account add claude Work (oppure codex, o grok). Installa la CLI se manca. Il primo account per un provider accede tramite il tuo browser normale, proprio dove la CLI guarda sempre. Ogni account successivo accede tramite una finestra privata, così l’account a cui il tuo browser è già connesso non viene rilevato per sbaglio; lì accedi come l’account che stai aggiungendo, e prima chiudi qualsiasi finestra privata tu abbia già aperta. Non disconnetterti mai dalla CLI per farlo: disconnettersi revoca l’accesso salvato, e quell’account dovrebbe essere aggiunto di nuovo.
Per copiare i tuoi login di abbonamento su un’altra macchina Omarchy tramite SSH, esegui omarchy agent account copy user@laptop. Il mittente fornisce un ricevitore temporaneo quando la destinazione non ne ha uno installato, così le macchine Omarchy più vecchie possono ricevere account senza un aggiornamento. I ricevitori installati hanno la precedenza. Questo copia tutti gli abbonamenti Claude, Codex e Grok; aggiungi i nomi dei provider per selezionarli, come in omarchy agent account copy laptop claude. I nomi degli account e gli ID dei comandi corrispondono a quelli della sorgente, inclusi gli account già presenti sulla destinazione. Gli account di destinazione non correlati ricevono un suffisso numerico se i loro nomi sono in conflitto, e impostazioni, skill, plugin e cronologia delle conversazioni restano locali su ogni macchina.
Le credenziali di destinazione esistenti vengono conservate. Un account sorgente già connesso lì vede il proprio nome sincronizzato senza sostituire le sue credenziali; gli altri account vengono aggiunti accanto ad esso. Per sostituire le credenziali salvate per gli account corrispondenti, usa omarchy agent account copy --replace laptop claude dopo aver chiuso le sessioni di quell’account sulla destinazione. Una destinazione nuova riceve anche l’account attivo e le preferenze di cambio della sorgente; una destinazione già consolidata mantiene le proprie.
Le credenziali viaggiano tramite SSH e sono memorizzate in file privati sulla destinazione, quindi copia solo su macchine di cui ti fidi. Questa è una copia una tantum, non una sincronizzazione continua. I token di refresh di Codex possono essere ruotati da un’altra macchina, lasciando un login copiato bisognoso di rinnovo; accessi separati restano la scelta più affidabile per l’uso simultaneo su più macchine. Vedi la guida di Codex all’autenticazione degli account.
È attivo un solo account per provider, e ogni nuova sessione parte come lui: cx, cy, un semplice claude, codex o grok, qualsiasi cosa avviata tramite omarchy agent, e script o editor che trovano la CLI nel PATH. Cambia con omarchy agent account use work (e torna indietro con omarchy agent account use main), oppure nel pannello premendo il numero di un account e poi Enter (oppure facendo clic sul suo pulsante Use). Le sessioni già in esecuzione restano sull’account con cui sono partite. Cronologia delle conversazioni, impostazioni, skill e plugin sono condivisi tra gli account, quindi claude --continue nella stessa cartella riprende da dove avevi interrotto sul nuovo account.
Con più di un account, il pannello mostra i limiti di ciascun account fianco a fianco, con quello attivo contrassegnato. Per impostazione predefinita Omarchy ti avvisa quando l’account attivo supera il 95% di un limite, e facendo clic sulla notifica passi all’account con più margine disponibile. Passa il mouse sulla riga di un account nel pannello e fai clic su Autoswitch che compare accanto a Use (oppure premi m), oppure esegui omarchy agent account mode auto, per farlo cambiare da solo; mentre è attivo, Autoswitch prende il posto di Use, e facendoci di nuovo clic si torna alle notifiche. Aggiungi un numero per cambiare la soglia, come in omarchy agent account mode auto 90. Se ogni account è oltre la soglia, te lo farà sapere una volta, insieme a quale account si libera per primo. Mentre un account attivo è entro 15 punti dalla sua soglia (80% con l’impostazione predefinita), i suoi limiti vengono controllati ogni tre minuti invece che ogni 15.
omarchy agent account list mostra ogni account e i suoi limiti più recenti, omarchy agent account remove work ne dimentica uno, e omarchy agent account rename primary Hey ne rinomina uno (oppure fai clic sul nome di un account nel pannello). Questi comandi funzionano sugli account del tuo agente predefinito; per raggiungere l’altro provider, nominalo prima, come in omarchy agent account use codex side. Il login che avevi già in ~/.claude o ~/.codex è l’account Main e resta dov’è. Un account rimasto inutilizzato per più di circa otto ore può mostrare Sign-in required; fai clic su di esso per connettere di nuovo quell’account proprio nel pannello, oppure avvia una sessione in esso, che aggiorna l’accesso da sola. I server MCP che avevi quando un account è stato aggiunto lo seguono, ma quelli che aggiungi in seguito con claude mcp add raggiungono solo l’account in cui li hai aggiunti. Claude Desktop e gli strumenti configurati con un percorso assoluto a un binario CLI non seguono il cambio. Un CLAUDE_CONFIG_DIR, CODEX_HOME o GROK_HOME esplicito ha la precedenza sull’account selezionato.
Diagnosi dei crash
Omarchy osserva systemd-coredump per i crash dei processi. Quando qualcosa va in segfault, riceverai una notifica “Process crashed” - fai clic su di essa, e il crash viene affidato al tuo agente predefinito insieme alla skill diagnose-crash di Omarchy, che accompagna l’agente nello stabilire i fatti dal core dump e nel decidere se vale la pena segnalare il crash upstream. Puoi anche eseguirla a mano su qualsiasi PID da coredumpctl list con omarchy agent crash <pid>.
L’osservazione è attiva per impostazione predefinita. Disattivala in Trigger > Toggle > Crash Capture (oppure con omarchy toggle crash-capture) e le notifiche si fermeranno; omarchy agent crash <pid> continuerà a funzionare a mano.
I crash possono anche essere silenziati un programma alla volta, che è ciò che la diagnosi ti offre alla fine. omarchy crash mute hyprland ferma le notifiche solo per quel programma, omarchy crash mute hyprland off le riattiva, e omarchy crash mute da solo elenca ciò che hai silenziato. Accetta il percorso del binario con la stessa facilità del suo nome, quindi omarchy crash mute /usr/bin/hyprland fa la stessa cosa. Metti tra virgolette un nome con uno spazio, come in omarchy crash mute 'Some App'. Tutto il resto continua a notificare, e il programma silenziato continua ad andare in crash - questo nasconde il promemoria, non risolve nulla.
App desktop
Il menu Install > AI include anche alcune app IA grafiche: l’app desktop di ChatGPT, l’app desktop di Claude (la beta Linux di Anthropic, con schede Chat, Cowork e Claude Code), Grok Bot per chattare con i modelli di xAI, Hermes Desktop, OpenClaw, l’app desktop di Perplexity e T3 Code. Grok Bot è l’app desktop di chat. L’agente di coding è il comando grok.
Hermes Desktop è quella da conoscere, perché una macchina ha un solo Hermes, ed è quello dell’app: Hermes viene installato solo e sempre tramite l’app, e il comando hermes che l’agente predefinito esegue è quello dell’app. Scegliere Hermes come agente predefinito installa la stessa cosa della voce Install > AI: il pacchetto, e un runtime Hermes in ~/.hermes configurato dall’installer di Hermes stesso, che la prima volta richiede alcuni minuti. Quel runtime è l’unico Hermes che usano il comando hermes da terminale, l’agente predefinito e l’app, e si aggiorna da solo con hermes update invece di aspettare una release di Omarchy. Installarlo consegna inoltre a Hermes il tema Omarchy come skin chiamata omarchy, che ogni superficie di Hermes segue quando cambi tema; scegline un’altra nelle impostazioni Appearance di Hermes o con /skin se preferisci che non lo faccia, e Omarchy lascia stare quella scelta. Rimuovere l’app in Remove > AI chiude prima Hermes, gateway incluso, porta via quel runtime con sé e conserva le tue chat, le memorie e le skill che Hermes ha scritto per sé, a meno che tu non gli dica il contrario: chiede, con no come impostazione predefinita, se anche quei dati e le tue impostazioni di connessione debbano sparire.
L’esperienza desktop di OpenClaw è la sua Control UI, che si apre come web app supportata dal suo gateway locale. OpenClaw vive in ~/.openclaw e si aggiorna da solo: usa il pulsante “Update Gateway” della Control UI oppure esegui openclaw update, e il gateway si riavvia sulla nuova versione. Omarchy sceglie solo la release da cui parte un’installazione nuova. Rimuovere OpenClaw in Remove > AI porta via con sé il servizio gateway e l’app e poi chiede se debba sparire anche ~/.openclaw, dato che contiene le tue chat e le credenziali insieme a OpenClaw stesso e ai runtime dei plugin che scarica; l’impostazione predefinita lo conserva, e installare di nuovo OpenClaw lo riprende.
T3 Code viene eseguito dalla sua release ufficiale AppImage in ~/.local/share/t3code invece che da un pacchetto, quindi si aggiorna da solo. Installarlo chiede se partire sul canale Stable o Nightly; cambia in seguito nelle impostazioni di T3 Code. I tuoi thread e le tue impostazioni vivono in ~/.t3, e rimuovere T3 Code in Remove > AI li porta via con sé.
LLM locali
Omarchy consiglia due modi per eseguire modelli LLM locali: LM Studio e Ollama. LM Studio fornisce un’interfaccia GUI per trovare modelli open-weight, installarli ed eseguirli. È un ottimo modo per partire facilmente. Ollama offre una CLI per fare lo stesso. Ma se sei nuovo ai modelli locali, io inizierei con LM Studio. Puoi installare l’uno o l’altro in Install > AI nel Menu Omarchy.
La skill di Omarchy
Le skill per agenti aiutano l’IA a usare strumenti specifici in un modo specifico, e Omarchy viene fornito con una skill predefinita per personalizzare il sistema. Come modificare la tua configurazione di Hyprland, regolare la barra, o persino creare un nuovo tema da zero. È collegata tramite symlink nelle directory delle skill per Claude Code (~/.claude/skills), Codex (~/.codex/skills), Pi (~/.pi/agent/skills), Antigravity (~/.gemini/config/skills), Hermes (~/.hermes/skills e ogni ~/.hermes/profiles/*/skills), e nella posizione generica ~/.agents/skills, quindi la maggior parte degli harness la rileva automaticamente.
Ma dovresti trattare questa skill come sperimentale. Modelli diversi la useranno con effetti diversi. È meglio eseguirla prima in modalità pianificazione, così hai un’idea di ciò che l’agente vorrebbe cambiare. E poi preparati ad annullare le modifiche o persino a invocare omarchy reinstall configs, se l’agente fa un disastro di tutto.