hueyexe/opencode-ensemble: Team di agenti paralleli in OpenCode

Testato il: 2026-07-30 Ambiente: Node 24.15.0 · Bun 1.3.5 · opencode-ensemble 0.16.0

GitHub - hueyexe/opencode-ensemble: Agent teams for OpenCode. Run multiple agents in parallel with messaging, shared tasks, and coordinated execution.

Agent teams for OpenCode. Run multiple agents in parallel with messaging, shared tasks, and coordinated execution. - hueyexe/opencode-ensemble

GitHubhueyexe

Prerequisiti

• OpenCode installato e funzionante. OpenCode auto-installa i plugin npm alla partenza: devi solo modificare la config, non eseguire npm install a mano.
• Git (qualsiasi versione recente). I worktree sono il cuore dell'isolamento fra agenti: senza Git il plugin parte ma i teammate condividono il filesystem, vanificando il vantaggio principale.
• Node ≥ 24 oppure Bun ≥ 1.0. Il plugin usa node:sqlite (Node 24+) o bun:sqlite. Node 20.x non ha il modulo; Node 22.5–23 lo nasconde dietro --experimental-sqlite.

• Un progetto Git esistente su cui vuoi sperimentare. Non serve che sia un progetto vero: anche un repo vuoto con un README.md basta per il primo test.

1. Aggiungere il plugin a opencode.json

Il plugin si installa dichiarandolo nel file di configurazione di OpenCode. Puoi metterlo a livello progetto (opencode.json nella root del repo) o globale (~/.config/opencode/opencode.json). Per questa guida uso il progetto.

Apri (o crea) opencode.json nella root del tuo progetto:

{
  "plugin": ["@hueyexe/[email protected]"]
}

Se arrivi da una versione precedente e il plugin non si aggiorna, svuota la cache a mano:

rm -rf ~/.cache/opencode/packages/@hueyexe

Poi riavvia OpenCode.

Nella schermata iniziale della TUI vedi:

[INFO] Plugin @hueyexe/[email protected] loaded

Se vedi un errore su node:sqlite, il tuo Node è troppo vecchio (torna ai prerequisiti). Il plugin non si carica e i tool del team non compaiono.

2. Allowlistare i permessi worktree

I teammate lavorano in git worktree isolati fuori dalla directory di progetto, sotto ~/.local/share/opencode/worktree/. Senza permessi espliciti, OpenCode chiede approvazione per ogni singola operazione su file dentro quei path: impraticabile.

Aggiungi questo blocco al tuo opencode.json globale (~/.config/opencode/opencode.json, non quello di progetto):

{
  "permission": {
    "external_directory": {
      "~/.local/share/opencode/worktree/**": "allow"
    }
  }
}

Il pattern ** è importante: senza, il permesso copre solo la directory stessa, non i file e le sottodirectory dentro i worktree. Il plugin crea una sottodirectory per ogni teammate (es. ~/.local/share/opencode/worktree/scout/) e il glob deve matchare ricorsivamente.

3. (Opzionale) Installare la companion skill

Il plugin espone 14 tool via SDK, ma è l'agente lead a dover decidere quando e come usarli. La companion skill insegna al modello a formare team sensati, scrivere prompt efficaci per i teammate, scegliere i modelli giusti e gestire le dipendenze fra task con depends_on.

npx skills@latest add hueyexe/opencode-ensemble --skill opencode-ensemble

L'output ti dice dove è stata installata la skill. Dentro OpenCode diventa disponibile come tool aggiuntivo che il lead può consultare.

Senza la skill, il lead può comunque usare i tool del team: glielo chiedi tu a parole. Ma la skill riduce la probabilità che spawni 5 agenti quando ne bastano 2, o che dimentichi di mettere worktree: false sugli agenti read-only. Per un primo test puoi saltarla; per uso serio, installala.

4. Configurare ensemble.json

Il file ensemble.json controlla timeout, modelli, rate limiting e la dashboard. Si può mettere globale (~/.config/opencode/ensemble.json) o di progetto (.opencode/ensemble.json). Quello di progetto sovrascrive il globale chiave per chiave.

Per cominciare, crea un file minimo .opencode/ensemble.json nel tuo progetto:

{
  "dashboardPort": 4747,
  "timeoutMs": 1800000,
  "stallThresholdMs": 300000,
  "rateLimitCapacity": 10
}

Tutti i campi sono opzionali: se il file non esiste, il plugin usa i default. I valori sopra sono già i default, ma averli espliciti aiuta a sapere cosa modificare quando serve.

Campi che vorrai toccare quasi subito:

5. Primo team: due explore agent in parallelo

L'obiettivo di questo passo è verificare che tutto funzioni: crei un team, spawni due agenti explore read-only, li fai lavorare in parallelo, raccogli i risultati e pulisci.

Apri OpenCode nella root del tuo progetto e chiedi al lead di creare un team:

Crea un team chiamato "first-flight". Poi spawna due explore agent, "alfa" e "bravo", entrambi con worktree: false.
Alfa deve mappare la struttura del progetto: directory, file principali, pattern ricorrenti.
Bravo deve analizzare il file più modificato nella history git (o il README se è un repo nuovo) e
riassumere lo scopo del progetto.
Tutti e due devono riportare i risultati con team_message e poi fermarsi.

La sequenza è:

1. Il lead chiama team_create con project_name: "first-flight". Nella sidebar della TUI compare il tool.
2. Il lead chiama team_spawn per alfa, poi per bravo. Vedi due toast di spawn.
3. I due agenti lavorano in parallelo: se apri la dashboard su http://localhost:4747, vedi entrambi con stato "working" contemporaneamente.
4. Quando un agente finisce, arriva un messaggio nella sessione del lead: [Team message from alfa]: ...
5. Il lead raccoglie i risultati con team_results.
6. Spegni i teammate con team_shutdown, uno alla volta, poi fai team_cleanup.

La dashboard a http://localhost:4747 ti dà una vista in tempo reale: agent cards con sparkline di attività, task board, feed dei messaggi e timeline degli eventi. Naviga gli agenti con j/k, apri il drawer con Enter.

Se qualcosa va storto, i problemi più comuni:

• "Permission required" a raffica: non hai configurato i permessi worktree (torna al passo 2).
• Teammate in "error" dopo pochi secondi: probabilmente il modello configurato in OpenCode non è accessibile o ha esaurito i rate limit.
• Nessun toast di spawn: il plugin non si è caricato. Controlla il log di avvio di OpenCode.
• Dashboard non raggiungibile: la porta 4747 è occupata o l'hai disabilitata con dashboardPort: 0.

Verifica

Per confermare che l'installazione funziona end-to-end, esegui questa procedura minima:

1. Controlla che il plugin sia caricato: riavvia OpenCode e verifica il messaggio Plugin @hueyexe/[email protected] loaded nel log di avvio.
2. Controlla che i tool siano registrati: nella sessione OpenCode, chiedi team_status. Se il tool non esiste, il plugin non è partito.
3. Spawna un teammate minimo: chiedi al lead Crea un team "smoke-test", spawna un explore agent chiamato "test" con worktree: false e prompt "Conta i file nella root del progetto e torna il numero con team_message." Se ricevi il messaggio di risposta, la comunicazione funziona.
4. Verifica la dashboard: apri http://localhost:4747 e controlla che mostri il team e l'agente.
5. Pulisci: team_shutdown, poi team_cleanup.

Limiti noti

Due problemi da tenere presenti, entrambi segnalati ma non risolti alla versione 0.16.0:

Lo stato dei task non è sempre accurato. Issue #27 aperta: in alcune condizioni di race, un task può apparire come "pending" quando è già stato completato, o viceversa. Se il comportamento della task board ti sembra incoerente, controlla lo stato reale con team_status e fidati più dei messaggi diretti che della board.

GitHub - hueyexe/opencode-ensemble: Agent teams for OpenCode. Run multiple agents in parallel with messaging, shared tasks, and coordinated execution.

Agent teams for OpenCode. Run multiple agents in parallel with messaging, shared tasks, and coordinated execution. - hueyexe/opencode-ensemble

GitHubhueyexe