Introduzione a CodeCourier

CodeCourier è una piattaforma di orchestrazione di workflow IA che permette ai team di sviluppo di eseguire agenti di coding IA - Claude Code, OpenCode, Codex, Pi e altri - all’interno di sandbox cloud E2B isolate. Invece di far girare assistenti IA sulla tua macchina locale, CodeCourier fornisce su richiesta ambienti Linux completi, esegue workflow di sviluppo multi-step e cattura la conoscenza istituzionale che i tuoi agenti producono lungo il percorso.

Che tu abbia bisogno di una singola sandbox per prototipare una feature, di una pipeline di design e review a più iterazioni, di uno sprint completamente automatizzato che trasforma un piano di progetto in pull request, o di un task ricorrente pianificato che gira al ritmo del tuo team - CodeCourier ti offre un unico control plane per gestire tutto.

Perché CodeCourier

Eseguire agenti di coding IA in locale crea una serie di problemi pratici: gli ambienti divergono tra le macchine, i task di lunga durata bloccano la tua workstation, i secret finiscono nelle shell locali e non esiste alcuna traccia condivisa di ciò che l’agente ha fatto o imparato. CodeCourier affronta ognuno di questi problemi spostando l’esecuzione degli agenti nel cloud e avvolgendola in uno strato di workflow strutturato.

• Isolamento - Ogni sandbox è una VM Linux usa e getta alimentata da E2B. Gli agenti possono installare pacchetti, modificare file ed eseguire comandi arbitrari senza toccare la tua macchina o altri progetti.
• Riproducibilità - I sandbox template definiscono l’immagine di base, gli strumenti installati e i client CLI preconfigurati. Ogni run parte da uno stato noto, arricchito dai contesti del tuo progetto e dai learning approvati.
• Osservabilità - Ogni messaggio scambiato tra la piattaforma e l’agente viene memorizzato in tempo reale. Puoi rivedere l’intera conversazione, ispezionare i verdetti passo dopo passo dei checker agent, consultare i punteggi di qualità di ogni step di run, monitorare lo stato dei check CI e tracciare costo e consumo di token fino al singolo step di run.
• Cattura della conoscenza - Quando un agente scopre un tranello, un pattern o una preferenza, CodeCourier lo estrae in un record di learning strutturato. I learning approvati vengono compilati in markdown e iniettati automaticamente nelle sessioni future, così i tuoi agenti diventano più intelligenti nel tempo.
• Collaborazione di team - I progetti supportano i ruoli owner, admin e member. I membri del team condividono workflow, personas, contesti, asset e learning all’interno di un progetto mantenendo le proprie configurazioni di chiavi API.

Funzionalità principali

Progetti

Un progetto è il workspace di livello più alto in CodeCourier. Rattacha ogni altra risorsa - sandbox, workflow, personas, contesti, asset, piani, learning, issue e membri del team - a un unico contesto. I progetti sono identificati da uno slug univoco e possono, in via opzionale, essere collegati a un repository GitHub per la gestione dei branch e la creazione di pull request.

Sandbox

Le sandbox sono ambienti Linux isolati forniti tramite E2B. Ogni sandbox ha un template configurabile (che determina lo strumento CLI preinstallato, come Claude Code o OpenCode), un’allocazione di memoria da 256 MB a 8 GB, un numero di CPU da 1 a 8 core e un timeout da 1 minuto a 4 ore. Le sandbox possono essere create manualmente per l’esplorazione interattiva o avviate automaticamente come parte di un run di workflow.

Workflow

I workflow definiscono processi IA multi-step ripetibili. CodeCourier supporta quattro tipi di workflow:

• Single Designer - Un singolo agente esegue il prompt in un’unica passata.
• Designer & Checker - Un designer agent scrive codice, poi un checker agent lo revisiona. Se il checker rifiuta, il designer itera. Questo ciclo continua fino a un numero massimo di iterazioni configurabile.
• Custom Pipeline - Definisci una sequenza arbitraria di tipi di step (designer, checker, optimizer, prompter, investigator, evaluator, judge) con loop opzionali e override di modello per step.
• Persona Pipeline - Concatena personas denominate, ciascuna con le proprie istruzioni, i propri set di skill e la propria configurazione di modello, in una pipeline sequenziale.

Personas

Le personas sono configurazioni di agente IA riutilizzabili limitate a un progetto. Ogni persona ha un tipo (designer, checker, optimizer, prompter, investigator, planner, deep-dive, reviewer o custom), un override di modello opzionale, un livello di thinking effort, istruzioni personalizzate e set di skill, command e script attivati. Le personas ti permettono di standardizzare il comportamento degli agenti da un run all’altro - una persona “security reviewer”, ad esempio, potrebbe usare un thinking effort elevato con skill orientati alla sicurezza attivati e command mirati per l’analisi statica.

Contesti

I contesti sono documenti di system prompt e CLAUDE.md riutilizzabili e versionati, che possono essere legati a specifici tipi di sessione all’interno di un progetto. Invece di mantenere un unico system prompt globale, puoi creare documenti di contesto distinti per ogni tipo di sessione - uno per le sessioni di scan delle issue, un altro per le sessioni di learning, un altro ancora per le operazioni di merge - e aggiornarli in modo indipendente man mano che il tuo progetto evolve. Ogni documento di contesto è versionato, così puoi tracciare come cambiano le istruzioni dei tuoi agenti nel tempo e tornare indietro se necessario.

Asset: Skill, Command e Script

Gli asset sono package versionati in modo indipendente e pubblicabili, che estendono il comportamento dell’agente nella sandbox. Esistono tre tipi di asset:

• Skill - Package di conoscenza specialistica composti da uno o più file (ad es. uno skill di pattern Convex potrebbe includere un file di riferimento, snippet di codice e linee guida architetturali). Gli skill vengono scritti sul filesystem della sandbox e referenziati nel contesto dell’agente.
• Command - Alias di comandi shell che gli agenti possono invocare all’interno della sandbox. I command standardizzano le operazioni comuni come eseguire i test, il linting o invocare tooling specifico del progetto.
• Script - Script eseguibili che possono essere lanciati nella sandbox in punti precisi di un workflow. Gli script sono utili per il setup prima del run, il teardown dopo il run o l’iniezione di contesto dinamico nelle sessioni dell’agente.

Tutti i tipi di asset sono selezionabili per persona e per tipo di sessione, dandoti un controllo granulare sulle capacità a cui ogni ruolo di agente ha accesso.

Issue

Le sessioni di issue ti permettono di scansionare una codebase alla ricerca di bug, debito tecnico o opportunità di miglioramento. CodeCourier analizza il repository e genera issue strutturate con titoli, descrizioni, priorità e prompt suggeriti. Quando una sessione di issue produce domande o ipotesi che richiedono chiarimenti, una answering session permette all’agente IA di risolvere quelle domande prima che inizi l’implementazione. Le issue possono poi essere eseguite singolarmente o raggruppate in work chain o sprint chain.

Sprint Chain

Le sprint chain sono pipeline di orchestrazione in batch che eseguono più run di workflow attraverso i branch, in sequenza. A differenza delle work chain (che elaborano una lista di issue su un singolo branch), le sprint chain definiscono un intervallo di sprint, tracciano un indice di sprint corrente e mantengono un tracciamento delle pull request per sprint. Le sprint chain sono ideali per eseguire una roadmap pianificata di feature o fix dove ogni sprint produce la propria PR.

Task ricorrenti

I task ricorrenti ti permettono di pianificare qualsiasi workflow perché venga eseguito automaticamente secondo una pianificazione ricorrente. Configuri la frequenza (giornaliera, un giorno sì e uno no, settimanale, bisettimanale o mensile), il fuso orario e l’ora e il minuto di esecuzione. CodeCourier traccia il prossimo orario di esecuzione pianificato e lo avvia automaticamente. I task ricorrenti sono utili per run di test notturni, audit settimanali delle dipendenze o qualsiasi workflow ripetitivo che il tuo team vuole automatizzare.

Learning

I learning catturano la conoscenza istituzionale dalle sessioni di agente. Ogni record di learning include una descrizione, una condizione di trigger, il comportamento corretto, una severità (critical, important o minor) e una categoria (preference, pattern, gotcha, tool o architecture). I learning passano attraverso un workflow di review - pending, approved o rejected - e i learning approvati vengono versionati e compilati in markdown, incluso automaticamente nei prompt di sandbox futuri.

Scoring di qualità

Ogni step di run include un punteggio di qualità strutturato che valuta l’output dell’agente su sei dimensioni: correttezza, type safety, stile del codice, copertura dei test, completezza e un punteggio composito che le aggrega. I run tracciano un punteggio di qualità complessivo derivato dai loro step. I punteggi di qualità permettono ai team di monitorare la qualità dell’output nel tempo e di identificare quali configurazioni di workflow producono i risultati migliori.

Check CI

I run tracciano lo stato dei check CI tramite un oggetto ciChecks che registra lo stato complessivo, l’array dei risultati dei singoli check e l’orario dell’ultima interrogazione. Questo ti dà una vista in tempo reale sul fatto che il codice generato dall’agente superi la tua pipeline CI, senza lasciare l’interfaccia di CodeCourier.

Come funziona

Il flusso tipico attraverso CodeCourier segue questo percorso:

1. Configura il tuo progetto - Crea un progetto, collega il tuo repository GitHub, aggiungi le chiavi API per E2B, Anthropic (o OpenRouter / OpenAI) e GitHub, e invita il tuo team.
2. Imposta contesti e asset - Definisci documenti di contesto per ogni tipo di sessione (issues, learning, merging, answering, evaluating, judging) e crea gli asset skill, command e script che gli agenti useranno.
3. Definisci personas e workflow - Imposta le personalità di agente di cui hai bisogno (un designer veloce, un checker rigoroso, un evaluator di qualità) e crea blueprint di workflow che le concatenano.
4. Esegui - Avvia un run da un workflow, da una issue o da una pianificazione di task ricorrente. CodeCourier invia un job in background tramite Trigger.dev, che fornisce una sandbox E2B, installa lo strumento CLI configurato e gli passa il tuo prompt insieme al documento di contesto attivo e a tutti i learning compilati.
5. Itera - Per i workflow multi-step, la piattaforma gestisce automaticamente il ciclo designer/checker, creando nuove sessioni di sandbox per ogni step, registrando ogni messaggio in tempo reale e valutando la qualità dell’output a ogni step.
6. Consegna - Al termine del run, CodeCourier può creare automaticamente una pull request sul tuo repository GitHub collegato, estrarre i learning dalla sessione e notificare il tuo team. Lo stato dei check CI viene tracciato dopo il merge.

Panoramica dell’architettura

CodeCourier si basa su quattro servizi centrali, ciascuno responsabile di uno strato distinto della piattaforma:

• Frontend Next.js - Un’applicazione Next.js 16 con App Router, server component e internazionalizzazione tramite next-intl. L’interfaccia è costruita con Tailwind CSS, le primitive Radix UI e i componenti shadcn/ui, con Framer Motion per le animazioni.
• Backend Convex - Convex fornisce il database, le subscription in tempo reale, le server function (query, mutation, action) e lo storage dei file. Tutta la logica di business - controlli di autenticazione, autorizzazione, validazione dei dati - gira in Convex function. Lo schema definisce tabelle per utenti, progetti, sandbox, workflow, run, run step, personas, contesti, asset, issue, sessioni di issue, learning, task ricorrenti, sprint chain, record di utilizzo, notifiche e altro.
• Sandbox E2B - E2B fornisce le macchine virtuali Linux isolate in cui gli agenti IA vengono eseguiti. CodeCourier gestisce il ciclo di vita delle sandbox (create, pause, resume, kill) e comunica con la CLI dell’agente che vi gira tramite l’SDK E2B.
• Job Trigger.dev - Trigger.dev si occupa dell’orchestrazione dei job in background. Le operazioni di lunga durata come il provisioning della sandbox, l’esecuzione di workflow multi-step, le sessioni di issue, le sprint chain e l’avvio dei task ricorrenti vengono gestite come task Trigger.dev, con callback secret per una comunicazione sicura di ritorno verso Convex.

L’autenticazione è gestita da Clerk, che fornisce OAuth, e-mail/password e gestione delle sessioni. I JWT Clerk vengono verificati nelle Convex server function per applicare l’autorizzazione per utente e per progetto.

Prossimi passi

Pronto a iniziare? La guida di quickstart ti accompagna nel tuo primo run in meno di dieci minuti, oppure immergiti nei core concept per una comprensione più profonda dei mattoni della piattaforma.