BBT for BBT Italiano

Posted on Nov 7

Usare Claude Code come worker di osFoundry con il proprio abbonamento Claude

#claude #mcp #osfoundry #tutorial

Alla fine di questa configurazione, il ruolo Worker in osFoundry è affidato a Claude Code. Quando uno step del piano arriva a lui, l'app desktop avvia claude nella cartella del tuo progetto, con l'accesso fatto tramite il tuo abbonamento Claude. Claude Code modifica i file con i propri tool e raggiunge i tool di osFoundry, come la ricerca nelle tue note, con il nome mcp__osfoundry__memory_search. Ognuna di queste chiamate compare nella chat di osFoundry come una riga "Using …".

Chi fa cosa

	Claude Code	App desktop di osFoundry
Login	Il tuo abbonamento Claude, salvato dalla CLI dopo `/login`	Non lo vede mai. Rimuove `ANTHROPIC_API_KEY` e variabili simili dall'ambiente del processo figlio, così l'esecuzione non può ripiegare sulla fatturazione API
Costo	Esce dal tuo abbonamento	Registra l'esecuzione con costo 0
File	I suoi Read, Edit e Bash, dentro una sola cartella (`--add-dir`)	Sceglie quella cartella: la più recente in Local Folders
Tool di osFoundry	Li chiama come `mcp__osfoundry__<tool>`	Li espone su una porta loopback solo per questa esecuzione e controlla ogni chiamata rispetto a una allowlist
Approvazione	Gira con `--permission-mode bypassPermissions` nella sua cartella	Ogni chiamata che passa dal bridge attraversa lo stesso gate di approvazione e policy della chiamata a tool di qualsiasi altro modello
Output	Testo finale	Diventa l'output del ruolo. L'attività dei tool viene mostrata come righe di avanzamento

Configurazione

1. Installa Claude Code e fai il login una volta

Installa la CLI come indicato nella documentazione di Anthropic. Poi fai il login da un terminale:

$ claude
> /login

osFoundry cerca il binario nel PATH, in ~/.claude/local e dentro il bundle dell'estensione VS Code (~/.vscode/extensions/anthropic.claude-code-*/resources/native-binary/claude). Quindi trova anche un Claude Code arrivato solo con l'estensione VS Code.

2. Attivalo in External AI

Nell'app desktop, clicca sull'icona della chiave nell'header (API Keys (BYOK)), poi apri la scheda External AI (AI esterna). La riga di Claude Code dovrebbe apparire così:

Claude Code   Installed                                  [Enabled]
/Users/you/.claude/local/claude
Model id: cli:claude (chat) · cli:claude:agent (autonomous)
[Verify sign-in]  [Sign in]

Esempio: Claude Code e Codex nella scheda External AI

Clicca su Verify sign-in (verifica accesso). L'app esegue una minuscola completion tramite la CLI e mostra ✓ Signed in oppure Needs sign-in. Sign in apre Claude Code in una finestra di terminale con l'indicazione "Type /login to sign in, then close this window."

Potresti vedere un badge API key in env. Significa che una variabile come ANTHROPIC_API_KEY è impostata nell'ambiente da cui è stato avviato osFoundry. L'app la rimuove prima di avviare claude, quindi l'esecuzione usa comunque il tuo abbonamento. Il badge è solo un avviso.

3. Dagli una cartella

La modalità agente lavora in una directory reale. Aggiungi il tuo progetto in Settings → Local Folders. Se ne hai più di uno, viene usato quello aggiunto per ultimo. Le esecuzioni avviate dalla superficie Code usano invece il repository registrato per quell'esecuzione.

4. Assegna il ruolo

Apri la scheda Pipeline → Pipeline Roles. In Agents, scegli Worker e seleziona cli:claude:agent dal gruppo External AI (subscription).

I due id corrispondono a due modalità diverse:

cli:claude:agent è autonomo. Claude Code ha i suoi tool nella tua cartella, più i tool di osFoundry tramite il bridge. Usalo per Worker, Researcher, Document Agent e ruoli simili.
cli:claude è la modalità chat. La CLI gira con --disallowedTools '*' e non può chiamare nulla. Va bene per ruoli solo testuali come Titling o Compaction. Se lo assegni a un ruolo che ha bisogno di tool, l'esecuzione fallisce con un messaggio che ti dice di usare cli:claude:agent.

Anche gli agenti che definisci nella schermata Agents possono usarlo. Il loro selettore di modello lo mostra sotto CLI agents, con l'etichetta "autonomous — runs in your local folder".

5. Cosa avvia davvero l'app

Per ogni esecuzione, osFoundry avvia un bridge MCP nuovo, poi lancia la CLI più o meno così. I flag vengono da build_claude_command in src-tauri/src/providers/agent_cli.rs:

claude -p "<conversation>" \
  --output-format stream-json --verbose --include-partial-messages \
  --permission-mode bypassPermissions \
  --add-dir /Users/you/work/site \
  --mcp-config '{"mcpServers":{"osfoundry":{"type":"http",
      "url":"http://127.0.0.1:<port>/mcp",
      "headers":{"Authorization":"Bearer <per-run token>"},
      "timeout":120000}}}' \
  --strict-mcp-config \
  --append-system-prompt "<role prompt>"

--strict-mcp-config tiene fuori da questa esecuzione i tuoi server MCP globali o di progetto. Viene collegato solo il server osfoundry. Porta e token sono nuovi a ogni esecuzione, e il listener si chiude quando il processo termina.

Un'esecuzione reale

Esempio. La nota e il repository sono contenuti demo.

Tu (chat Maestro, Worker = cli:claude:agent)
  Trova nelle mie note quando c'è la review del budget Q4 e aggiungila a TODO.md.

Chiamate a tool di Claude Code
  mcp__osfoundry__memory_search  {"query": "review del budget Q4"}
    → "Review del budget Q4: gio 14:00."
  Read   TODO.md
  Edit   TODO.md   (+ "- [ ] Preparare i numeri per la review del budget Q4 (gio 14:00)")

Righe di avanzamento di osFoundry
  Using memory_search — {"query":"review del budget Q4"}
  Using Read — {"file_path":"TODO.md"}
  Using Edit — {"file_path":"TODO.md", …}

Risposta
  Aggiunto "Preparare i numeri per la review del budget Q4 (gio 14:00)" a TODO.md.
  L'orario viene dalla tua nota "Review del budget Q4: gio 14:00."

Il prefisso mcp__osfoundry__ è il modo in cui Claude Code chiama i tool di un server di nome osfoundry. osFoundry lo toglie nella riga di avanzamento, così memory_search si legge come con un modello via API.

Dove sta il confine

Il bridge offre una lista breve e fissa. Comprende tool di sola lettura come memory_search, web_search, extract_content, code_search, todo_list, transcribe e i tool di lettura cloud_*, più l'orchestrazione (spawn_fleet, graph_run, loop_run), lo schermo live e i tool di Canvas. Lascia fuori di proposito read_file, write_file ed execute_command. Claude Code ne ha già versioni limitate alla sua cartella, e un secondo esecutore senza limiti via MCP arriverebbe oltre --add-dir.

La allowlist è applicata dal bridge, non da un flag della CLI. Un'esecuzione in modalità bypassPermissions non rispetta --allowedTools, quindi osFoundry non lo passa. Una chiamata a un tool fuori dalla lista dell'esecuzione riceve un errore JSON-RPC: "tool '…' is not available to this agent".

Workspace e canale vengono fissati all'avvio del bridge. Una chiamata a tool non può reindirizzarsi verso un altro workspace tramite i suoi argomenti.

Le scritture sullo schermo o in un editor Canvas (ui_agent_act, i tool di scrittura di Canvas) ti chiedono sempre prima conferma, come con un modello via API. Le esecuzioni che nessuno sta guardando, come un agente che risponde a una menzione in un canale, rifiutano un tool che richiede approvazione invece di aspettare un clic che non arriverà.

I tuoi file non passano mai da osFoundry. Claude Code li legge e li modifica direttamente, e il suo traffico va ad Anthropic con il tuo login, come farebbe in un terminale.

Il passo successivo è assegnare cli:claude:agent anche al ruolo Researcher, accanto a Worker, e lanciare un task orchestrato. La pagina dei ruoli della Pipeline elenca tutti i ruoli che puoi affidargli, e Local Folders spiega come viene scelta la cartella di lavoro.

DEV Community