Configuración de Claude Code

Configuración con un solo comando para el registro automático de tiempo en Claude Code.

Resumen

TeeckIn se integra con Claude Code para registrar automáticamente tu tiempo de desarrollo. La configuración lleva menos de un minuto con nuestro paquete de NPM.

Autenticación en el navegador

Claude Code usa OAuth 2.0 con PKCE, un flujo de autenticación seguro basado en el navegador. Esto significa:

✓Sin claves de API ni secretos que gestionar
✓Sin credenciales guardadas en los archivos del proyecto
✓Te autenticas una vez y funciona en todos tus proyectos

Lo que obtienes:

+Claude te pregunta en qué tema trabajas al iniciar la sesión
+Pídele a Claude que pare el cronómetro cuando termines
+Cambia de tema a mitad de sesión simplemente pidiéndoselo a Claude

Configuración rápida

Un único comando para empezar:

Ejecutar la configuración

bash

# Run in your project directory
npx @teeckin/agent init --claude

¡No hacen falta credenciales! La autenticación ocurre en tu navegador.

Primera conexión

Cuando Claude Code se conecta por primera vez a TeeckIn, tu navegador se abre automáticamente:

1.Inicia sesión en TeeckIn (si aún no lo has hecho)
2.Selecciona un agente existente o crea uno nuevo
3.Haz clic en «Autorizar» para conceder los permisos
4.Vuelve a Claude Code: ¡ya estás conectado!

Distinto de otras herramientas de IA

A diferencia de Cursor, Copilot u otras herramientas de IA que requieren claves de API (Client ID + Secret), Claude Code usa OAuth en el navegador. No necesitas crear secretos en TeeckIn ni guardar credenciales en tu proyecto. Las herramientas de IA que no admitan este método deberán usar el flujo de credenciales de cliente.

Personal frente a organización

Durante la autorización en el navegador puedes elegir cualquier agente al que tengas acceso: agentes personales o de organización.

Qué se crea

El comando de configuración crea estos archivos en tu proyecto:

.mcp.json

URL del servidor MCP (sin credenciales: la autenticación ocurre en el navegador)

.claude/settings.json

Hook de SessionEnd y permisos de las herramientas MCP

CLAUDE.md

Instrucciones para que Claude pregunte por el tema

Seguro de subir al repositorio

El archivo .mcp.json solo contiene la URL del servidor, sin secretos. Puedes subirlo al control de versiones sin riesgo.

Agentes por proyecto

De forma predeterminada, Claude Code se autentica una vez y usa el mismo agente en todos los proyectos. Si quieres agentes distintos para proyectos distintos (por ejemplo, un registro de tiempo separado para el trabajo de clientes), tienes dos opciones.

Opción 1: ámbito local (recomendado)

Usa el ámbito «local» de Claude Code para configurar TeeckIn por proyecto sin modificar el .mcp.json del proyecto. Es ideal cuando trabajas en bases de código de clientes donde no quieres añadir tus propios archivos de configuración.

Añade un parámetro de consulta único para diferenciar la URL en cada proyecto:

bash

# In project A
cd ~/projects/project-a
claude mcp add teeckin -s http -t streamable-http \
  --url "https://api.teeckin.com/api/mcp?project=project-a"

# In project B
cd ~/projects/project-b
claude mcp add teeckin -s http -t streamable-http \
  --url "https://api.teeckin.com/api/mcp?project=project-b"

El parámetro de consulta (?project=...) hace que Claude Code trate cada URL como un servidor MCP independiente, lo que dispara flujos de OAuth separados. El servidor ignora el parámetro: la selección del agente ocurre durante la autorización en el navegador.

Cómo funciona el ámbito local

El ámbito local guarda la configuración en tu archivo personal ~/.claude.json, organizada por ruta de proyecto. No se sube al repositorio del proyecto, así que puedes usarlo en bases de código de clientes sin modificar sus archivos.

Opción 2: configuración a nivel de proyecto

Si controlas el proyecto, ejecuta el comando de configuración con una URL única:

bash

# Creates .mcp.json in the project
TEECKIN_API_URL="https://api.teeckin.com/api/mcp?project=my-project" \
  npx @teeckin/agent init --claude

Esto crea un archivo .mcp.json que se puede subir al control de versiones. Cada miembro del equipo se autenticará con su propio agente durante el flujo en el navegador.

Cambiar de agente

Para cambiar el agente que usa un proyecto, ejecuta /mcp reconnect teeckin en Claude Code. Tu navegador se abrirá y podrás seleccionar otro agente.

Finalizar sesiones

Cuando termines de trabajar, pídele a Claude que pare el cronómetro:

Pídele a Claude que pare el cronómetro

Simplemente dile a Claude: «Para el cronómetro» o «Por hoy he terminado». Claude llamará a la herramienta teeckin_stop_timer.

Problema conocido: los hooks de SessionEnd no son fiables

Ni /exit ni Ctrl+D disparan de forma fiable los hooks de SessionEnd en Claude Code. Se trata de un problema conocido de Claude Code que esperamos que Anthropic corrija. Mientras tanto, pídele siempre a Claude que pare el cronómetro antes de terminar tu sesión.

¿Te olvidaste de parar?

Si olvidas parar el cronómetro, la siguiente sesión lo detectará y te ofrecerá reanudarlo. Tu tiempo se conserva, no se pierde.

Seguridad

Claude Code usa OAuth PKCE (Proof Key for Code Exchange) para una autenticación segura:

+Sin credenciales guardadas en los archivos del proyecto
+La autenticación ocurre en tu navegador
+Claude Code guarda los tokens de forma segura
+Puedes revocar el acceso en cualquier momento desde Configuración > Agentes

Volver a autorizar

Si necesitas cambiar de agente o volver a autorizar, usa el comando /mcp reconnect teeckin de Claude Code. Tu navegador se abrirá para una nueva autorización.

Comandos de la CLI

El paquete ofrece comandos para la configuración y el control manual del cronómetro:

Comandos de configuración

npx @teeckin/agent initConfiguración inicial (crea los archivos de configuración)

npx @teeckin/agent updateActualiza la configuración con las últimas herramientas y funciones de MCP

Comandos del cronómetro

npx @teeckin/agent exec:statusComprueba si hay un cronómetro en marcha

npx @teeckin/agent exec:update "notes"Actualiza las notas del cronómetro activo

npx @teeckin/agent exec:stopPara manualmente el cronómetro activo

Actualizar tras los lanzamientos de TeeckIn

Cuando TeeckIn añada nuevas herramientas o funciones de MCP, ejecuta npx @teeckin/agent update para actualizar tu configuración sin volver a introducir las credenciales.

Herramientas disponibles

Una vez configurado, Claude tiene acceso a estas herramientas MCP:

Control del cronómetro

teeckin_get_statusComprueba el estado del cronómetro; detecta sesiones recientes para reanudarlas

teeckin_list_topicsLista los temas y categorías disponibles

teeckin_start_timerEmpieza a registrar tiempo en un tema (incluye las tareas de seguimiento)

teeckin_stop_timerPara el cronómetro activo

teeckin_log_timeRegistra una entrada de tiempo completada de forma retroactiva

Seguimiento de la lista de tareas

teeckin_add_checklist_itemAñade una tarea al tema actual (persiste entre sesiones)

teeckin_start_itemEmpieza a trabajar en una tarea (registra tiempo y pausa las demás automáticamente)

teeckin_check_itemMarca una tarea como completada (coincidencia aproximada)

teeckin_uncheck_itemDevuelve a pendiente una tarea completada o descartada

teeckin_dismiss_itemMarca una tarea como innecesaria (conserva el tiempo dedicado)

teeckin_get_followupConsulta las tareas pendientes del tema actual

Notas y etiquetas

teeckin_update_timerActualiza las notas del cronómetro activo (modo texto)

teeckin_list_tagsLista las etiquetas disponibles para clasificar el trabajo

teeckin_add_tagsAñade etiquetas al cronómetro activo (las crea si no existen)

Modo lista de tareas

Las tareas se asocian a los temas, no a entradas de tiempo concretas. Esto significa que las tareas sin terminar persisten entre sesiones hasta que las completas o las descartas. El tiempo dedicado a cada tarea se registra cuando empiezas a trabajar en ella.

You:

Corrige el error de validación del inicio de sesión y añade pruebas unitarias

Claude:

[añade tareas, empieza a trabajar en la primera]
Voy a hacer seguimiento de estas tareas:
- Corregir el error de validación del inicio de sesión (empezando ahora)
- Añadir pruebas unitarias del módulo de autenticación

Claude (tras corregir el error):

[marca la tarea]
Corregí el problema de validación (12 min). Paso a las pruebas.

Cuando consultas el estado, la lista muestra los estados y el tiempo:

Cronómetro en marcha: Project Alpha (45 minutos)

Trabajando ahora en: Añadir pruebas unitarias (8 min)

Tareas (1/2 completadas):

- [x] Corregir el error de validación del inicio de sesión (12 min)

- [*] Añadir pruebas unitarias del módulo de autenticación (en curso)

Pausa automática

Solo una tarea puede estar «en curso» a la vez. Cuando Claude empieza una nueva tarea, la tarea en curso anterior se pausa automáticamente. Así se garantiza un registro de tiempo preciso por tarea.

Reanudar la sesión

Si borras una conversación o inicias una nueva sesión antes de que pasen 10 minutos desde que paraste, Claude lo detecta y te ofrece reanudar tu sesión anterior.

Claude (nueva sesión, antes de 10 min):

Estabas trabajando en API Development hace 3 minutos.

Tareas sin terminar:
- [ ] Añadir pruebas unitarias del módulo de autenticación

¿Reanudar esa sesión?

You:

Sí

Claude:

[inicia el cronómetro en «API Development», traslada las tareas]
¡Reanudada! Listo para continuar.

Cambio de contexto rápido

Esto evita perder el contexto cuando borras una conversación para empezar de cero pero quieres seguir trabajando en el mismo tema.

Persistencia de las tareas

Las tareas persisten en los temas de forma automática. Cuando inicias una nueva sesión en el mismo tema, las tareas pendientes siguen ahí: no hace falta «trasladarlas» ni aceptar nada.

Claude (nueva sesión):

Cronómetro iniciado en «Project Alpha».

Tareas pendientes (1):
- [ ] Añadir pruebas unitarias del módulo de autenticación

¿Listo para continuar donde lo dejaste?

You:

Sí, hagamos las pruebas

Claude:

[empieza a trabajar en la tarea]
Ahora trabajando en las pruebas unitarias.

Descartar frente a completar

Si una tarea ya no es relevante, pídele a Claude que la descarte. Así desaparece de la lista de pendientes pero se conserva el tiempo que ya hayas dedicado.

Sesión de ejemplo

Claude (inicio de sesión):

Veo que TeeckIn está configurado. ¿En qué tema trabajamos hoy?

Temas disponibles:
- Backend: API Development, Database
- Frontend: React Components, Styling

You:

API Development

Claude:

[inicia el cronómetro en «API Development»]
¡Cronómetro iniciado! ¿En qué te gustaría trabajar?

You:

Añade paginación al endpoint de usuarios

Claude:

[implementa la función]
¡Listo! Añadí paginación con limit/offset y un valor predeterminado de 20 elementos por página.

You:

Genial, por hoy he terminado. Para el cronómetro.

Claude:

[para el cronómetro]
Cronómetro detenido. Hoy trabajaste 23 minutos en API Development.

Resolución de problemas

Claude no pregunta por el tema

Asegúrate de que se creó el archivo CLAUDE.md. Comprueba si la sección de TeeckIn aparece al principio.

El cronómetro no se detiene al terminar la sesión

Los hooks de SessionEnd no son fiables actualmente en Claude Code (problema conocido de Anthropic). Pídele siempre a Claude que pare el cronómetro antes de terminar tu sesión.

El navegador no se abre para autorizar

Prueba a ejecutar /mcp reconnect teeckin en Claude Code. Si falla, revisa la configuración de tu navegador predeterminado.

La página de autorización muestra un error

Asegúrate de haber iniciado sesión en TeeckIn. Si el error persiste, prueba a borrar la caché del navegador para teeckin.com.

Quiero cambiar a otro agente

Ejecuta /mcp reconnect teeckin en Claude Code. Tu navegador se abrirá y podrás seleccionar otro agente para autorizar.