Hace un mes me convertí en una especie de “gym bro” de bajo nivel. La última vez que había ido a un gimnasio antes de eso fue hace casi 15 años, y muchas cosas han cambiado desde entonces, especialmente en lo que respecta al uso de la tecnología en los gimnasios.

Hoy en día, con un smartphone puedes hacer un seguimiento de tus entrenamientos, preparar rutinas para la próxima sesión e incluso recibir comentarios sobre tu técnica. Un amigo mío, Eloy Coto, me sugirió que usara Hevy para registrar mis entrenamientos y preguntara a la IA por las mejores rutinas basadas en mi historial y objetivos. Empecé de forma sencilla, con Gemini, pero nada sofisticado, simplemente usando la interfaz de chat y pidiendo consejos sobre cómo mejorar mi rutina. Me sorprendió mucho la calidad de las sugerencias, al menos para un novato como yo.

Durante los días siguientes, utilicé la función de exportación que tiene Hevy para exportar mis entrenamientos como un archivo CSV y lo subí al chat de Gemini, siempre usando la misma conversación para mantener el contexto. Gemini fue capaz de analizar los datos y darme feedback sobre cómo mejorar mi rutina, y también sugerir nuevos ejercicios o nuevos pesos para los mismos ejercicios. También le pedí a Gemini que me diera los nombres de los ejercicios tal como aparecen en Hevy para poder encontrarlos en la aplicación, y fue capaz de hacerlo sin ningún problema.

Esto funcionó bien, pero seguía requiriendo mucho trabajo manual: tenía que exportar los datos de Hevy, subirlos a Gemini, pedir feedback y luego tomar las sugerencias y actualizar mi rutina en Hevy.

Empecé a pensar que sería genial si pudiera automatizar este proceso, pero no quería dedicarle demasiado tiempo. Mi primera idea fue hacer vibe-coding de una aplicación sencilla usando AI SDK, pero aún así tendría que gestionar la autenticación con Hevy, el almacenamiento del contexto del agente, archivos de configuración, herramientas básicas para obtener datos, actualizaciones de archivos, tal vez una base de datos para el contexto y la compactación del contexto cuando se hiciera demasiado grande, etc. No quería perder tiempo en todo eso para algo tan simple. Quería centrarme en la lógica del agente, no en la infraestructura.

Entonces recordé que OpenCode tiene una función llamada “agents”, que te permite crear agentes que puedes limitar a solo unas pocas herramientas, darles una “personalidad” (un prompt inicial que le da al agente un comportamiento específico) y confiar en ellos para gestionar y compactar el contexto y usar skills.

Antes de profundizar en la implementación, quiero explicar qué es OpenCode, qué son los agentes personalizados de OpenCode y algunas diferencias clave con los subagentes de Claude Code.

¿Qué es OpenCode?

OpenCode es un “agente de programación de IA de código abierto”. Puede utilizar muchos proveedores y modelos para ejecutar las tareas que el usuario solicita. Está diseñado para ser un agente de programación, pero puede usarse para muchos casos de uso diferentes, no solo los relacionados con la programación.

La empresa desarrolladora de OpenCode proporciona modelos gratuitos para usar, por lo que no necesitas pagar por los modelos, pero también puedes usar tus propias claves de API para proveedores como OpenAI, Azure, etc… y usar los modelos que quieras.

¿Cuáles son las diferencias entre los agentes personalizados de OpenCode y los subagentes de Claude Code?

Ambos se definen de forma similar: un archivo Markdown con frontmatter para la configuración del agente (por ejemplo, el modelo a usar, las herramientas que puede usar, las skills a cargar, etc.) y un cuerpo Markdown con la documentación del agente.

Pero la principal diferencia es que los subagentes de Claude Code necesitan ser invocados desde un agente padre (Build o Plan) o explícitamente por el usuario, mientras que los agentes personalizados de OpenCode pueden ser utilizados directamente por el usuario, sin necesidad de un agente padre (“Usa el subagente test-runner para arreglar los tests que fallan”).

OpenCode te permite crear agentes personalizados de primer nivel que el usuario puede seleccionar con la tecla Tab, como los agentes “Build” o “Plan”. Son agentes de primer nivel, por lo que puedes estar seguro de que solo estás haciendo lo que ese agente está diseñado para hacer, sin el riesgo de que el agente principal “build” o “plan” recupere el control y haga otra cosa, o use otro subagente.

OpenCode también permite crear una configuración a nivel de proyecto para que solo un conjunto de agentes esté disponible para el usuario, de modo que podamos forzarlo a usar solo el agente de gimnasio (en este caso).

¿Cómo creé el agente de gimnasio?

Creé un nuevo proyecto y abrí OpenCode como de costumbre, y como en otros proyectos, comencé con un plan.

Quería un agente que se convirtiera en un entrenador de gimnasio, uno que pudiera usar y analizar datos de Hevy, darme feedback sobre cómo mejorar mi rutina y también sugerir nuevos ejercicios o nuevos pesos para los mismos ejercicios y cambiarlos directamente por sí mismo. También quería que proporcionara objetivos que pudiera usar como motivación y para seguir el progreso. También necesitaba que el agente supiera sobre el usuario (yo): edad, peso, altura, el equipo que tiene el gimnasio, el tiempo que puedo pasar en el gimnasio, lesiones, límites, condiciones físicas previas, etc., para dar mejores sugerencias.

También quería que tuviera memoria sobre mí, los objetivos y las conversaciones anteriores, sin necesidad de usar una base de datos o algo parecido, simplemente usando archivos Markdown.

Y, por supuesto, necesitaba una clave de API para obtener datos de Hevy y actualizar la rutina con las sugerencias, pero quería hacerlo fácil, para que el agente pudiera pedir la clave de API si no estaba presente y guardarla para un uso futuro, sin necesidad de hacerlo manualmente.

Y este es el plan que creamos:

# Gym AI Trainer - Design Document

**Date**: 2026-03-07  
**Status**: Implemented

## Overview

An OpenCode agent that helps users optimize their gym training by:

- Analyzing workout history from Hevy
- Providing personalized recommendations based on user profile
- Setting and tracking measurable goals
- Suggesting progressive overload and recovery strategies

## User Requirements

### Data Access

- **Primary**: Hevy API with user-provided API key
- **Fallback**: CSV export via browser-mcp when no API key available

### User Profile (`data/user.md`)

Agent collects on first interaction:

- Preferred language (asked first, used throughout)
- Personal info: name, age, gender, weight (kg), height (cm)
- Physical background: experience level, previous sports, fitness level
- Health: injuries, medical conditions, mobility limitations
- Schedule: available days, session duration, equipment access

### Goals (`data/goals.md`)

- General training goal (suggested based on profile)
- Measurable monthly goals with targets and deadlines
- Progress tracking with motivation

### Training Intelligence

- Progressive overload suggestions
- Periodization planning
- Recovery recommendations based on days since last workout
- Date-aware session planning

### Constraints

- Read-only access to Hevy data (never modify workouts)
- Full conversation logging in `data/conversation.md`

## Project Structure

ai-trainer/
├── .env # HEVY_API_KEY
├── .env.example # Template for .env
├── .gitignore
├── package.json
├── tsconfig.json
├── opencode.json
├── start.sh # Launch script
├── .opencode/
│ ├── agents/
│ │ └── gym-ai-trainer.md # Primary agent definition
│ └── skills/
│ ├── hevy-api/ # API-based data access
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ │ ├── fetch-workouts.ts
│ │ │ ├── fetch-routines.ts
│ │ │ ├── analyze-progress.ts
│ │ │ ├── check-goal-progress.ts
│ │ │ └── suggest-updates.ts
│ │ └── references/
│ │ └── HEVY-API.md
│ └── hevy-export/ # Browser-based CSV export
│ ├── SKILL.md
│ └── scripts/
│ └── parse-csv.ts
└── data/ # User data (gitignored)
└── .gitkeep

## Agent Behavior Flow

┌─────────────────────────────────────────────────────────────┐
│ SESSION START │
├─────────────────────────────────────────────────────────────┤
│ 0. Check .env for HEVY_API_KEY │
│ ├─ Missing → Ask user for key or offer CSV fallback │
│ └─ Present → Continue │
├─────────────────────────────────────────────────────────────┤
│ 1. Check data/user.md │
│ ├─ Missing → Ask preferred language FIRST │
│ │ Then collect full profile │
│ │ Save to data/user.md │
│ └─ Present → Load profile, use stored language │
├─────────────────────────────────────────────────────────────┤
│ 2. Check data/goals.md │
│ ├─ Missing → Suggest goals based on profile │
│ │ Help set measurable monthly targets │
│ │ Save to data/goals.md │
│ └─ Present → Load goals │
├─────────────────────────────────────────────────────────────┤
│ 3. Regular Session │
│ a. Run `date` for current date context │
│ b. Fetch recent workouts from Hevy │
│ c. Calculate days since last workout │
│ d. Compare performance to goals │
│ e. Recommend: rest, push, or next workout │
│ f. Log conversation to data/conversation.md │
└─────────────────────────────────────────────────────────────┘

## Skills

### hevy-api

Primary skill for API-based access to Hevy data.

**Scripts:**

- `fetch-workouts.ts` - Fetch recent workouts with pagination
- `fetch-routines.ts` - Fetch all user routines
- `analyze-progress.ts` - Calculate trends for specific exercise
- `check-goal-progress.ts` - Compare workouts to goals.md targets
- `suggest-updates.ts` - Generate routine modification suggestions

### hevy-export

Fallback skill for browser-based CSV export when no API key is available.

**Requirements:** browser-mcp installed

**Scripts:**

- `parse-csv.ts` - Convert Hevy CSV export to JSON format

## Key Features

| Feature                   | Implementation                                        |
| ------------------------- | ----------------------------------------------------- |
| User profile collection   | Agent prompts on first run, stores in `user.md`       |
| Language preference       | Asked first, used for all communication               |
| Goal setting              | Suggested based on profile, measurable with deadlines |
| Progress tracking         | Scripts analyze Hevy data vs goals                    |
| Rest/push recommendations | Based on days since last workout + performance        |
| Date awareness            | `date` command for current context                    |
| Conversation memory       | Full log in `conversation.md`                         |
| Read-only for Hevy        | Agent can only fetch, never modify workout data       |
| API key management        | Stored in `.env`, asked if missing                    |
| CSV fallback              | Browser automation when no API key                    |

## Usage

### Quick Start

./start.sh

Or:

npm install
npm start

### First Run

1. Agent checks for API key, asks if missing
2. Agent asks for preferred language
3. Agent collects user profile
4. Agent helps set training goals
5. Regular sessions begin

## Dependencies

{
"devDependencies": {
"typescript": "^5.4.0",
"tsx": "^4.7.0",
"@types/node": "^20.11.0"
},
"dependencies": {
"dotenv": "^16.4.0"
}
}

Utilicé el plan para hacer vibe-coding de la implementación, y el agente de programación creó el agente y las skills, así como los scripts para las skills y la lógica del agente, todo con un simple comando “vibecode” y prompts para la implementación de cada parte y cómo conectarlas entre sí.

También le pedí que creara un script de inicio para lanzar el agente con un comando simple y gestionar las dependencias y la estructura del proyecto, para facilitar su ejecución a usuarios no técnicos.

El resultado

Después de algunas iteraciones y algunos ajustes al plan inicial, puedo compartir este agente con todos vosotros: simple en arquitectura pero realmente potente.

https://github.com/sergiocarracedo/gym-ai-trainer

Solo necesitas clonar el repositorio, instalar las dependencias y ejecutar el script de inicio, o simplemente pedirle a un agente genérico que visite la página e instale el agente por ti.

En la primera ejecución, el agente te pedirá la clave de API y, si no la tienes, te guiará para obtenerla. También te pedirá la información de tu perfil, y luego comenzará a analizar tus entrenamientos y a darte feedback sobre cómo mejorar tu rutina, y sugerir nuevos ejercicios o nuevos pesos para los mismos ejercicios.

Todo se almacenará en la carpeta data/, por lo que puedes consultar tu perfil, tus objetivos y el historial de conversaciones con el agente, y también hacer una copia de seguridad.

Veámoslo en acción:

Conclusión

Este es un ejemplo de cómo puedes aprovechar las características y herramientas que OpenCode ofrece de serie —UI, modelos, proveedores, agentes personalizados, skills, herramientas, gestión de contexto, etc.— para crear un agente potente con una implementación sencilla.

Obviamente, esto no puede ofrecerse como una aplicación final para todo tipo de usuarios, pero puede ayudarte a crear tus propios agentes personalizados para tus necesidades específicas, con un esfuerzo mínimo.

¿Qué casos de uso te imaginas para este tipo de agentes?

¿Tienes alguna idea para un agente que pueda ayudarte en tu vida diaria? ¡Házmelo saber en los comentarios!