Inicio rápido

Vincula un workspace, siémbralo, registra un proyecto, abre el primer asiento Chair, lanza un worker y lee tu consumo.

Siete pasos, unos diez minutos. Cada comando de abajo es el comando real: aquí no hay nada inventado salvo las rutas que elijas.

1. Vincula un workspace#

Crea la carpeta que contiene tu código o entra a ella con cd, y luego:

orch setup

orch setup es un asistente interactivo. Usa la carpeta actual como workspace (Enter) u otra ruta que escribas, escribe ahí orch.yaml y .orch/, pregunta por carpetas opcionales de proyectos y compartidas como nombres relativos, recuerda que los agentes en vivo necesitan llaves de API de proveedor en variables de entorno, y se ofrece a poner la carpeta del binario en el PATH de tu usuario.

Confirma el resultado cuando quieras:

orch workspace

que imprime las rutas resueltas orch.exe:, workspace:, config: y runtime:.

Fuera de un workspace vinculado orch corre en modo suelto (loose mode): el gateway funciona, pero los locks, el bus y el control de proyectos no.

2. Siembra el taller#

orch init

Córrelo dentro del taller ya vinculado. Pregunta por el locale de la documentación, las carpetas compartidas, los proyectos, identidades de git opcionales y si instalar los hooks de git de los guards. Luego siembra, sin pisar jamás un archivo no vacío que ya tengas:

También hace git init en cada proyecto y carpeta compartida (nunca en la raíz del taller), instala los skills sellados orch-* en el proyecto y conecta identidades de git con includeIf cuando diste perfiles.

Las últimas líneas que imprime son el resumen y la nota de prácticas:

workshop init OK · <workspace> · profile=lite · N shared · N projects · N git inits

Practices (optional — your docs/process win if you prefer them):
  Starter kit: DEV_PRACTICES.md + GATES.md (recommendations, not mandates).
  Built-ins when you want them: orch guard lang|code-lang|ddl|comment|lock|dup|tracker.

Usa orch init --dry-run primero si quieres el plan sin las escrituras, y --recommend para partir del layout shared/<lang>/ + projects/<app>/.

3. Registra un proyecto#

Un proyecto es un repositorio git que orch conoce. Registrarlo no crea carpetas:

orch project add products/billing

La salida nombra la ruta, el nombre corto derivado de la carpeta y el archivo de configuración donde quedó escrito:

registered products/billing
  short name: billing
  config: <workspace>/orch.yaml

Lístalos, con el Chair en curso y la cuenta de workers por proyecto cuando los hay:

orch project list

products/billing  (chair: claude, workers: 2)

4. Abre el primer asiento#

Desde la carpeta del proyecto, abre el agente que usas. Los presets registrados por defecto son agy, claude, codex, commandcode, copilot, cursor, grok, kimi, mimo, opencode y zcode; orch a secas lista bajo Detected agents los que realmente encontró en tu PATH:

orch claude

orch codex

orch opencode

El agente arranca con su interfaz de chat habitual. No pases tu prompt como argumentos: orch lo rechaza y te dice que escribas dentro del agente. El primer asiento interactivo de un proyecto queda como Chair; un segundo asiento en el mismo proyecto se rechaza con un mensaje que nombra la sesión que ya lo tiene.

5. Pídele al Chair que lance un worker#

Escribe esto dentro del chat del agente, no en tu shell:

Abre un worker de orch con codex sobre las pruebas que fallan en internal/billing, dale como criterio de aceptación que go test ./internal/billing/... pase, y que reporte de vuelta.

El Chair llama a dispatch_worker con el preset del agente y el prompt. Devuelve apenas el worker está corriendo: JSON que nombra la tarea, el id de sesión, el id del worker, el nombre visible, su estado (running), el worktree donde corrió y la ruta de su log. Por defecto el worker corre en su propio worktree git orch/<session>, así que no choca con tus propias ediciones; inplace lo pone en la raíz del proyecto.

Un worker no puede lanzar otro worker. Si lo intenta, orch responde:

dispatch_worker denied: ORCH_ROLE=worker — only the Chair may spawn (use orch msg to the Chair)

Antes de terminar, el worker llama a verify_report con las pruebas que corrió, los símbolos que exportó o reutilizó y cada criterio de aceptación marcado como cumplido o no.

6. Lee tu consumo#

De vuelta en tu shell:

orch usage

La primera línea es un resumen: intentos con sus conteos de ok y errores, tokens de prompt y de completado, los bytes que el crush mantuvo fuera del cable con su proporción, y la latencia promedio en milisegundos. Debajo vienen el bloque del grafo de código y los desgloses by session, by worker y by model, y luego los totales locales de transcripciones por fuente. El ledger detrás de la tabla nunca guarda prompts, así que toda la lectura es libre de contenido.

Forma legible por máquina, para un script o un agente:

orch usage --format json

7. Sigue adelante#

• orch ui abre la consola web local (por defecto http://127.0.0.1:8790) con consumo, ajustes, estado, sesiones y el board.
• orch worktree status lista los worktrees de sesión con marcas de sucio y huérfano; orch worktree promote <session> integra uno en la rama base, cerrando en falso ante conflictos y sin hacer push por ti.
• Qué leer después elige la ruta que corresponde a tu rol.