Conectar un repositorio

Este flujo es el mas habitual: tienes una cuenta en Almirant (SaaS o self-hosted) y quieres que tu repo local aparezca como un proyecto, con agentes de IA accesibles desde tu IDE (Claude Code, Codex, OpenCode, Cursor, etc.).

Tiempo estimado: 2 minutos.

Requisitos

• El CLI instalado (bun add -g almirant@latest o npm i -g almirant).
• Una cuenta en Almirant. Si aun no la tienes, crea una en almirant.ai o despliega tu propia instancia siguiendo la guia self-hosted.

Paso 1 — Autenticarte

Elige el comando segun contra que backend te autenticas:

# SaaS
almirant login

# Instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

El CLI abre el navegador para OAuth y guarda la cuenta en ~/.almirant/config.json con permisos 600.

tip

Solo necesitas hacer login una vez por backend. Si trabajas con varias instancias (p. ej. SaaS y self-hosted a la vez), ejecuta almirant login una vez por cada una, ponles labels con almirant accounts rename y cambia la activa con almirant use. Ver Trabajar con varias cuentas.

Paso 2 — Elegir la cuenta activa

Si tienes mas de una cuenta, usa labels. Dentro de cuatro meses te acordaras de local-m1pro; no de una URL larga.

almirant accounts list
almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Paso 3 — Vincular el repo

Ve a la raiz del repositorio que quieres conectar y ejecuta:

cd mi-repo
almirant link

El CLI:

1. Lee tus cuentas guardadas y usa la activa o te deja elegir.
2. Lista los proyectos de esa cuenta y te deja elegir uno, o crear uno nuevo.
3. Fusiona una entrada almirant en .mcp.json usando el proxy stdio local.
4. Copia las plantillas de skills en .claude/skills/ y .agents/skills/.

Si es tu primera vez y todavia no has hecho almirant login, usa almirant init en lugar de link — init dispara tambien el flujo OAuth como parte del mismo comando.

Paso 4 — Verificar en tu IDE

Abre el repo en tu agente y pide algo como:

Lista mis work items de Almirant

Si ves la lista, todo esta conectado. Si obtienes Unauthorized, revisa:

• Que .mcp.json exista en la raiz del repo.
• Que el --account de .mcp.json apunte a una cuenta existente (almirant accounts list).
• Que la API key local siga vigente (almirant current muestra solo el prefijo, no el secreto).
• Que el backend este levantado y accesible, especialmente si es self-hosted.

Que queda en tu repo

Despues de link, tu repo tiene:

mi-repo/
├── .mcp.json              ← arranca almirant mcp proxy; no contiene tokens
├── .claude/
│   └── skills/            ← plantillas de skills para Claude Code
└── .agents/
    └── skills/            ← mismo contenido, para agentes no-Claude

La entrada MCP generada tiene este patron:

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}

info

La API key vive en ~/.almirant/config.json, no en .mcp.json. El proxy adjunta el bearer token en memoria cuando el agente lo arranca.

Codex .codex/config.toml

Si usas Codex y el servidor MCP se declara en .codex/config.toml, usa el mismo proxy:

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id-or-label>"]

No escribas bearer tokens en .codex/config.toml. Si quieres que ese repo siga siempre la cuenta activa, omite --account; para trabajo en equipo o repos antiguos, preferimos dejarlo fijado por ID.

Migrar desde configuraciones antiguas

Si tu .mcp.json contiene type: "http", url y Authorization: Bearer ..., reejecuta:

almirant link

Si ese token estuvo alguna vez en git, rotalo:

almirant config rotate api-key --account <ref>

Gestionar varias cuentas y proyectos

Si trabajas con mas de una cuenta (tipico: cuenta personal + empresa, o SaaS + instancia interna), consulta Trabajar con varias cuentas.

Para cambiar el proyecto vinculado de un repo ya inicializado, vuelve a ejecutar almirant link y elige el proyecto nuevo — el CLI reescribe la entrada almirant de .mcp.json conservando otros servidores.