# Agente da terminale

> Un agente che legge, cerca e modifica i file del tuo progetto ed esegue comandi sulla tua macchina, con la tua approvazione.


Questi comandi richiedono la CLI installata e l'accesso fatto. Vedi [Installa la CLI](/it/cli/install).

Esegui `notholy` dentro un progetto. L'agente può usare questi strumenti sulla tua macchina:

| Strumento | Cosa fa |
|---|---|
| `read`, `grep`, `glob` | Legge e cerca file |
| `edit`, `write` | Modifica file |
| `bash` | Esegue un comando |
| `cve_lookup`, `kb_search`, `web_search` | Strumenti di ricerca remoti |

## Modalità

| Modalità | Comportamento |
|---|---|
| `plan` | Solo lettura |
| `ask` | Predefinita. Chiede prima di ogni scrittura e di ogni comando |
| `auto-edit` | Modifica senza chiedere. Per i comandi chiede ancora |
| `yolo` | Non chiede mai. Serve `--yolo` a ogni avvio |

I comandi girano sulla tua macchina, sotto la tua autorizzazione. I server di NotHoly non eseguono mai nulla contro i tuoi target.

Metti le istruzioni del progetto in `NOTHOLY.md` nella radice. Il contenuto dei file e l'output dei comandi vengono trattati come dati, mai come istruzioni per l'agente.

Flag: `--mode`, `--model`, `--yolo` e `-p` per eseguire un solo prompt e uscire.

Comandi slash: `/model`, `/effort` (off, low, high o max), `/mode` (plan, ask o auto-edit), `/cost`, `/compact`, `/autocompact`, `/mcp`, `/resume` (la sessione più recente), `/exit`. Le sessioni vengono salvate in `~/.notholy/sessions` con permessi `600`.

```bash
notholy --mode plan -p "map the auth flow in this repo"
```

## Engagements

`notholy engage` registra cosa può toccare un test e controlla i comandi prima che girino. Servono un nome, uno scope e un riferimento all'autorizzazione: un contratto, la URL del programma o un ticket. Lo scope accetta host, wildcard `*.`, IP e CIDR. `--exclude` prevale sullo scope, e `--from` e `--until` fissano una finestra.

```bash
notholy engage init --name acme-q4 --scope "*.acme-staging.test,10.20.0.0/24" --exclude vpn.acme-staging.test --until 2026-12-20 --auth "contract 2026-117"
notholy engage status
notholy engage off
```

Regole e log restano in `~/.notholy/engagements/<id>/`, fuori dal repository, così un repository non può impiantare il proprio scope. Non viene inviato nulla.

Con un engagement attivo, l'agente legge i target di ogni comando `bash` prima di eseguirlo. Un comando in scope segue la normale approvazione. Un target fuori scope richiede di digitare l'host, e l'eccezione finisce nel log. `yolo` è spento. Un target noto solo a runtime, come una variabile di shell, genera un avviso da controllare.

Ogni decisione va in `log.jsonl` con comando, target, codice di uscita e SHA-256 dell'output, e ogni voce è concatenata all'hash della precedente.

`notholy connect claude` installa lo stesso controllo come hook `PreToolUse` sulle chiamate Bash. Lì un comando fuori scope viene negato.

Il controllo legge il testo della shell e non risolve il DNS. Intercetta gli errori operativi e non è una sandbox, quindi un comando può raggiungere un host che non nomina.

## Sessioni lunghe

Ogni modello ha una dimensione del contesto, indicata come `context_length` in `GET /v1/models`. L'agente la legge da lì e compatta la conversazione prima che una richiesta superi circa l'80% di quel valore. Quando succede, compare una riga attenuata.

La compattazione sostituisce la parte più vecchia della conversazione con un solo riassunto, scritto dal modello della sessione in una chiamata senza strumenti. Il riassunto conserva l'obiettivo, le decisioni, i file toccati, i finding, i comandi eseguiti e i compiti aperti. Il messaggio di sistema, la tua ultima richiesta e i messaggi più recenti, fino a circa il 30% del contesto, restano come sono, tranne un output di strumento molto lungo in quella parte, che può essere tagliato a metà. Una chiamata di strumento e i suoi risultati non vengono mai separati. La chiamata per il riassunto si paga come qualsiasi altra richiesta e conta in `/cost`.

| Comando | Cosa fa |
|---|---|
| `/compact` | Compatta subito e stampa la dimensione stimata prima e dopo |
| `/compact keep the auth findings` | Come sopra, e dice al riassunto su cosa concentrarsi |
| `/autocompact on\|off` | Attiva o disattiva la compattazione automatica per questa sessione. All'avvio è attiva |

Se la chiamata per il riassunto fallisce, l'agente tiene i messaggi più recenti, scarta quelli più vecchi e te lo dice. Un'interruzione o un errore di account, crediti o limite di richieste ferma la compattazione e lascia intatta la cronologia. Se l'API risponde [`context_length_exceeded`](/it/guides/errors#lunghezza-del-contesto), l'agente compatta una volta e riprova quel passo. Con `/autocompact off` ricevi invece l'errore.

## Prossimi passi

- [Collega e avvia](/it/cli/connect-and-run)
- [Strumenti dell'harness](/it/chat/harness)