“Context Mode is an MCP server that sits between Claude Code and these outputs. 315 KB becomes 5.4 KB. 98% reduction.” — Mert Köseoğlu, Creador

En 2026, context-mode es el framework de optimización de contexto más popular para agentes de IA: 16,361 estrellas en GitHub, 1,180 forks, soportado en 15 plataformas y desarrollado por Mert Köseoğlu (mksglu), quien también mantiene el MCP Directory con 100K+ peticiones diarias.

Pero ¿qué hace que context-mode funcione tan bien? No es magia — son 4 soluciones integradas:

1. Context Saving — Sandbox que captura stdout
2. Session Continuity — SQLite + FTS5 + BM25 search
3. Think in Code — Scripts reemplazan tool calls
4. No prose enforcement — Flexibilidad completa

Este artículo cubre: arquitectura interna, instalación paso a paso, pitfalls comunes, benchmarks reales, y cuándo usarlo (o NO usarlo).

1. Introducción — Qué es y quién lo mantiene

El creador

Mert Köseoğlu (mksglu) — Senior Software Engineer, AI consultant.

• Creador del MCP Directory & Hub (100K+ daily requests)
• Ve todos los MCP servers que se publican
• Identificó el patrón: “todos construyen tools que dumpan raw data en contexto. Nadie resolvía el output side”
• Construyó context-mode primero para sus propias sesiones de Claude Code
• Notó que podía trabajar 6x más antes de la degradación de contexto
• Open-sourced con licencia MIT

El proyecto

Repositorio

GitHub: https://github.com/mksglu/context-mode
Blog oficial: https://mksg.lu/blog/context-mode
Docs: https://context-mode.mksg.lu/
Creator: https://mksg.lu
Social: @mksglu (X), linkedin.com/in/mksglu

2. Arquitectura — Cómo funciona internamente

Diagrama de flujo

┌─────────────────┐
│ Claude Code     │
│ (200K context)  │
└────────┬────────┘
         │ 1. Tool call
         ▼
┌─────────────────┐
│ Context Mode    │
│ (Middleware)    │
└────────┬────────┘
         │ 2. PreToolUse hook intercepta
         ▼
┌─────────────────┐
│ Sandbox (10 runtimes)
│ - JavaScript/TypeScript
│ - Python
│ - Shell
│ - Ruby
│ - Go
│ - Rust
│ - PHP
│ - Perl
│ - R
│ - Bun (3-5x faster JS/TS)
└────────┬────────┘
         │ 3. Ejecuta script
         │ 4. Captura SOLO stdout
         ▼
┌─────────────────┐
│ SQLite + FTS5   │
│ (Knowledge Base)│
│ - BM25 ranking  │
│ - Porter stem   │
└────────┬────────┘
         │ 5. Indexa chunks
         ▼
┌─────────────────┐
│ Claude Code     │
│ (Solo metadata) │
└─────────────────┘

Las 4 soluciones

2.1 Context Saving — Sandbox output capture

Cada llamada execute() spawn un subproceso aislado con su own boundary:

• Scripts NO pueden acceder a memoria/state de otros scripts
• El subprocess ejecuta tu código
• Captura SOLO stdout
• Solo ese stdout entra en el conversation context
• Los raw data (logs, API responses, snapshots) NUNCA dejan el sandbox

Runtimes disponibles (10):

2.2 Session Continuity — SQLite + FTS5 + BM25 search

La herramienta index chunk markdown por headings mientras mantiene code blocks intactos, luego los store en una SQLite FTS5 virtual table.

Cómo funciona el search:

• BM25 ranking — Algoritmo probabilístico que scorea documentos basado en:
  • Term frequency (TF)
  • Inverse document frequency (IDF)
  • Document length normalization
• Porter stemming — Aplicado en index time
  • “running”, “runs”, “ran” → match el mismo stem
• Exact code blocks — Retorna código exacto con heading hierarchy
  • NO summaries
  • NO approximations
  • El actual indexed content

Extensión a URLs:

fetch_and_index extiende esto a URLs:

1. Fetch
2. Convert HTML to markdown
3. Chunk
4. Index
5. El raw page NUNCA entra en contexto

2.3 Think in Code — Paradigma OBLIGATORIO

Este es el single most impactful behavioral shift.

BEFORE (mal):

// 47 × Read() = 700 KB
const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
files.forEach(f => {
  const content = fs.readFileSync('src/' + f, 'utf8');
  // ... procesamiento ...
  console.log(f + ': ' + content.split('\n').length + ' lines');
});

AFTER (buen):

// 1 × ctx_execute() = 3.6 KB
ctx_execute("typescript", `
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\\n').length + ' lines'));
`);

Por qué funciona:

• LLM programa, no procesa datos
• Scripts reemplazan tool calls
• Output es solo el resultado, no los datos intermedios
• Los data intermedios nunca entran en contexto

2.4 No prose enforcement

Context-mode NO dicta cómo debes responder:

• Puedes ser verbose si quieres
• Puedes usar tu propio estilo
• No forcing patterns de respuesta
• Flexibilidad completa

3. Instalación paso a paso

Prerrequisitos

• Node.js 18+ (para plugin marketplace)
• O npx (para MCP-only)
• Claude Code (para hooks automáticos)

Opción 1: Plugin Marketplace (RECOMENDADO)

Da hooks automáticos + slash commands:

# 1. Añadir el plugin
/plugin marketplace add mksglu/claude-context-mode

# 2. Instalar el plugin
/plugin install context-mode@claude-context-mode

# 3. Restart Claude Code
# Done!

Opción 2: MCP-only (si solo quieres las tools)

# 1. Añadir como servidor MCP
claude mcp add context-mode -- npx -y context-mode

# 2. Restart Claude Code
# Done!

Verificación

# Context-mode tools disponibles
/tools

# Deberías ver:
# - execute (sandbox code execution)
# - index (chunk & index markdown)
# - search (search indexed content)
# - fetch_and_index (fetch URL + index)

# Diagnóstico
/context-mode:ctx-doctor

4. Configuración — Config files y ejemplos

Config default (sin cambios)

Context-mode funciona out-of-the-box sin configuración.

El único cambio es: PreToolUse hook intercepta automáticamente tool outputs y los routea por el sandbox.

Hooks automáticos

Context-mode incluye un PreToolUse hook que:

1. Intercepta cada tool call
2. Routea tool outputs a través del sandbox
3. Subagents aprenden a usar batch_execute como tool primario
4. Bash subagents se upgradean a general-purpose para acceder a MCP tools

Config avanzada (opcional)

Si necesitas customizar el sandbox, puedes editar ~/.context-mode/config.json:

{
  "runtimes": {
    "python": {
      "path": "/usr/bin/python3",
      "version": "3.11"
    },
    "typescript": {
      "path": "/usr/bin/tsc",
      "bundler": "bun"
    }
  },
  "indexing": {
    "chunkSize": 1000,
    "maxChunks": 1000
  },
  "sandbox": {
    "timeout": 30000,
    "memoryLimit": "512M"
  }
}

💡 Nota: La mayoría de usuarios NO necesitan esto. Context-mode auto-detecta runtimes y config.

5. Uso práctico — Comandos clave y workflows

Comandos principales

5.1 execute — Sandbox code execution

Ejecuta código en un runtime aislado.

# Ejemplo 1: Contar líneas en archivos TypeScript
execute("typescript", `
  const fs = require('fs');
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => {
    const content = fs.readFileSync('src/' + f, 'utf8');
    console.log(f + ': ' + content.split('\\n').length + ' lines');
  });
`)
# Output: solo los resultados (3-4 KB), NO los archivos enteros

# Ejemplo 2: Procesar CSV
execute("python", `
  import csv
  with open('data.csv', 'r') as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(f"{row['name']}: {row['value']}")
`)
# Output: solo las filas procesadas, NO el CSV entero

5.2 index — Chunk & index markdown

# Index documentación
index("path/to/docs/")

# Index con opciones
index("path/to/docs/", {
  "chunkSize": 1500,
  "maxChunks": 500,
  "includeCodeBlocks": true
})

Qué hace:

1. Chunks markdown por headings
2. Mantiene code blocks intactos
3. Store en SQLite FTS5

5.3 search — Search indexed content

# Simple search
search("authentication flow")

# Search con filtro
search("authentication flow", {
  "limit": 10,
  "contextLines": 3
})

# Search en URLs indexadas
search("react hooks", {
  "source": "urls"
})

Qué retorna:

• Exact code blocks con heading hierarchy
• NO summaries
• NO approximations
• El actual indexed content

5.4 fetch_and_index — Fetch URL + index

# Fetch y index una URL
fetch_and_index("https://docs.example.com/api")

# Fetch y index múltiples URLs
fetch_and_index([
  "https://docs.example.com/api",
  "https://docs.example.com/auth",
  "https://docs.example.com/database"
])

Qué hace:

1. Fetch URL
2. Convert HTML to markdown
3. Chunk
4. Index
5. El raw page NUNCA entra en contexto

Workflows típicos

Workflow 1: Triangular test failures

# 1. Index test files
index("tests/")

# 2. Search failing tests
search("test failures authentication")

# 3. Execute fix script
execute("typescript", `
  // Fix authentication tests
  // ... código ...
`)

Workflow 2: Investigar bug en repo grande

# 1. Index relevant files
index("src/auth/")

# 2. Search bug-related code
search("JWT token expiration")

# 3. Execute investigation script
execute("python", `
  # Analyze token expiration logic
  # ... código ...
`)

Workflow 3: Documentación lookup

# 1. Fetch y index docs
fetch_and_index("https://react.dev/learn")

# 2. Search documentation
search("useEffect cleanup")

# 3. Output es SOLO las secciones relevantes
# NO toda la documentación

6. Pitfalls — Problemas comunes y soluciones

Pitfall 1: Proceso queda en background

Problema: El sandbox有时候 quedan procesos zombie.

Solución:

# Matar procesos huérfanos
pkill -f context-mode

# O restart Claude Code
/restart

Pitfall 2: File reads sin delta compression

Problema: Re-reads no se comprimen.

Solución:

# Use read_file_delta para re-reads
# El primer read es full, los siguientes son delta
read_file_delta("src/file.ts")

Pitfall 3: Indexing muy lento

Problema: Indexing de docs grandes (>100 MB) tarda.

Solución:

# Index en chunks más pequeños
index("docs/", {
  "chunkSize": 500,  # Default es 1000
  "maxChunks": 100   # Limita total chunks
})

# O usa fetch_and_index con cache
fetch_and_index("https://docs.example.com/api", {
  "cache": true
})

Pitfall 4: Think in Code no funciona

Problema: LLM sigue haciendo tool calls en vez de scripts.

Solución:

# El subagent necesita aprender el patrón
# Dile explícitamente:
"Use ctx_execute() instead of multiple tool calls"

# O usa el slash command:
/context-mode:teach-subagent

Pitfall 5: Missing runtime

Problema: Runtime no disponible (e.g., Python no instalado).

Solución:

# Verifica runtimes disponibles
/context-mode:doctor

# Instala runtime faltante
# e.g., instalar Python 3.11+
sudo apt install python3.11

7. Benchmarking — Rendimiento y ahorro real medido

Benchmarks del blog oficial (VERIFICADO)

Session economics

Latency

Nota: Latency depende de tamaño de input y complexity de script.

8. Casos de uso — Cuándo usarlo (y cuándo NO)

✅ Cuándo usar context-mode

❌ Cuándo NO usar context-mode

9. Comparación — vs otros proyectos

Context-mode vs mcp-compressor

Veredicto: Complementarios. Usa ambos para maximum optimization.

Context-mode vs Sophon

Veredicto: Context-mode para Claude Code/Codex. Sophon para compression determinista + neural embeddings.

Context-mode vs TOON-MCP

Veredicto: Context-mode es más completo. TOON-MCP para JSON-specific compression.

10. Conclusión — Recomendación final

Resumen

Context-mode es el framework de optimización de contexto más popular y completo para agentes de IA en 2026:

• ✅ 16,361 stars — Comunidad masiva
• ✅ 98% ahorro — Benchmarks verificados
• ✅ 15 plataformas — Hooks automáticos
• ✅ 4 soluciones integradas — Sandbox + SQLite + Think in Code
• ✅ 6x más session time — 30 min → 3 horas

Cuándo usarlo

Use context-mode si:

• Usas Claude Code, Codex, u OpenClaw
• Necesitas session continuity
• Haces sesiones largas (>1 hora)
• Trabajas con repos grandes (100+ files)
• Need docs lookup eficiente

Don’t use context-mode si:

• Solo usas Hermes Agent
• Sessions cortas (<15 min)
• Solo 1-2 MCP servers
• Need full context (no summaries)
• Real-time streaming requirements

Setup recomendado

# Para Claude Code
/plugin marketplace add mksglu/claude-context-mode
/plugin install context-mode@claude-context-mode

# Verificar
/context-mode:ctx-doctor

Combinación ganadora

Para maximum optimization:

Claude Code + Context Mode + mcp-compressor

• Context-mode comprime output (98%)
• mcp-compressor comprime tool definitions (70-97%)
• Ahorro total: ~95% en input + output

Next steps

Si quieres más detalles:

• Official docs
• GitHub repo
• Creator’s blog
• MCP Directory — mantenido por el mismo creador

📚 Recursos adicionales

Documentation

• Context-mode v1.0.0 docs
• BENCHMARK.md
• CHANGELOG.md

Artículos relacionados

• MCP Token Optimization: 4 proyectos comparados — Artículo anterior en esta serie
• mcp-compressor en profundidad — Próximo artículo
• Sophon: Deterministic context compressor — Comparativa

Social

• @mksglu — Creator en X
• linkedin.com/in/mksglu — Creator en LinkedIn
• mksg.lu — Blog del creador

💭 ¿Qué te parece?

¿Has usado context-mode? ¿Qué experiencia tuviste? ¿Cuál es tu stack actual de optimización de contexto? Déjame un comentario.