Instalación

Requisitos

El binario kj incluye su propio runtime, pero orquesta herramientas externas — no las instala. Tras instalar, ejecuta kj doctor para comprobar tu máquina.

Requerido (kj no funciona sin esto):

• git — Karajan trabaja sobre repositorios git
• Al menos un CLI de agente de IA — Claude, Codex, Gemini, Aider u OpenCode (ver Paso 1)

Opcional (cada uno habilita funciones extra):

• Docker — modelos locales y análisis estático con SonarQube. Desactiva Sonar con --no-sonar o sonarqube.enabled: false
• Node.js >= 18 / npm — habilita la vía de instalación npm y las herramientas auxiliares (Squeezr, qmd)

Paso 1: Instala al menos un agente de IA

Necesitas al menos un agente instalado antes de ejecutar kj init. Instala uno o más:

Agente	CLI	Instalación
Claude	claude	npm install -g @anthropic-ai/claude-code
Codex	codex	npm install -g @openai/codex
Gemini	gemini	Ver Gemini CLI docs
Aider	aider	pip install aider-chat
OpenCode	opencode	Ver opencode.ai

Paso 2: Instala Karajan Code

La vía recomendada es el binario standalone — un único ejecutable autónomo. El instalador descarga el binario para tu plataforma, verifica su checksum SHA256 y deja kj en tu PATH.

Linux (x64)

curl -fsSL https://karajancode.com/install.sh | sh

Windows (x64, PowerShell)

irm https://karajancode.com/install.ps1 | iex

macOS (Apple Silicon)

curl -fsSL https://karajancode.com/install.sh | sh

Vía npm (cualquier plataforma, Node.js 18+)

Instala con npm en los Mac Intel o en cualquier plataforma donde prefieras ejecutar kj sobre Node:

npm install -g karajan-code

Paso 3: Ejecuta el wizard de configuración

kj init

El wizard auto-detecta tus agentes instalados y te guía en la configuración:

1. Seleccionar agente coder por defecto — Qué IA escribe el código (ej: Claude)
2. Seleccionar agente reviewer por defecto — Qué IA revisa el código (ej: Codex)
3. ¿Activar triage? — Clasificar automáticamente la complejidad de las tareas para activar solo los roles necesarios (por defecto: No)
4. ¿Activar SonarQube? — Análisis estático con quality gates via Docker (por defecto: Sí)
5. Metodología de desarrollo — TDD (test-driven, recomendado) o Standard

¿Solo un agente?

Si solo tienes un agente instalado, kj init lo asigna automáticamente a los roles de coder y reviewer. Puedes cambiarlo después en la config.

Al completar el wizard, se crean:

• ~/.karajan/kj.config.yml — Fichero principal de configuración (o $KJ_HOME/kj.config.yml)
• review-rules.md — Directrices de revisión por defecto (en el directorio del proyecto)
• coder-rules.md — Directrices del coder por defecto (en el directorio del proyecto)

Si SonarQube está activado, el wizard también inicia un contenedor Docker (karajan-sonarqube) y proporciona instrucciones para generar tu token de SonarQube.

Paso 4: Verifica la instalación

kj doctor

Esto verifica tu entorno completo: git, Docker, conectividad con SonarQube, CLIs de agentes y ficheros de reglas. Corrige cualquier problema que reporte antes de ejecutar tu primera tarea.

Alternativa: Instalar desde código fuente

git clone https://github.com/manufosela/karajan-code.git
cd karajan-code
./scripts/install.sh

Alternativa: Setup no interactivo (CI/automatización)

Para pipelines de CI o entornos automatizados donde no puedes ejecutar el wizard interactivo:

./scripts/install.sh \
  --non-interactive \
  --kj-home /ruta/a/.karajan \
  --sonar-host http://localhost:9000 \
  --sonar-token "$KJ_SONAR_TOKEN" \
  --coder claude \
  --reviewer codex \
  --run-doctor true

Configuración del Token de SonarQube

Si activaste SonarQube durante kj init:

1. Abre http://localhost:9000 en tu navegador
2. Inicia sesión con las credenciales por defecto (admin / admin) — te pedirá cambiar la contraseña
3. Ve a My Account → Security → Generate Tokens
4. Crea un Global Analysis Token
5. Añádelo a tu config:

# En ~/.karajan/kj.config.yml
sonarqube:
  token: "tu-token-aqui"

O establece la variable de entorno:

export KJ_SONAR_TOKEN="tu-token-aqui"

Alternativa: Docker

Ejecuta Karajan Code en un contenedor (Alpine + Node 20) — todo va dentro de la imagen:

docker run --rm -it ghcr.io/manufosela/karajan-code kj doctor

O usalo como imagen base para pipelines de CI:

FROM ghcr.io/manufosela/karajan-code
COPY . /workspace
WORKDIR /workspace
RUN kj init --non-interactive --coder claude --reviewer codex

Alternativa: Wrapper Python (pip install)

Si prefieres instalar via pip:

cd wrappers/python && pip install .

Esto instala el comando kj mediante un wrapper Python que delega al CLI de Node.js.

Alternativa: Descarga manual del binario (fijar versión)

Si prefieres descargar una versión concreta manualmente en lugar de usar el instalador de una línea, coge el binario para tu plataforma desde GitHub Releases:

# Linux x64
curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-linux-x64 -o kj && chmod +x kj

# macOS (Apple Silicon)
curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-darwin-arm64 -o kj && chmod +x kj

# Windows (PowerShell)
curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe

Mueve el binario a un directorio en tu PATH (ej. /usr/local/bin/kj). Los checksums SHA256 están disponibles junto a cada binario. El binario de macOS es kj-darwin-arm64 (Apple Silicon); los Mac Intel se instalan vía npm.

Alternativa: Homebrew (macOS)

brew install manufosela/tap/karajan-code

Opcional: Instalar RTK para Ahorro de Tokens

RTK (Rust Token Killer) reduce el consumo de tokens en un 60-90% en las salidas de comandos Bash. Instálalo globalmente y KJ se beneficia automáticamente:

brew install rtk
rtk init --global

Consulta RTK en GitHub para más detalles.

Siguientes Pasos

• Inicio Rápido — Ejecutar tu primera tarea