tilt-dev

name	tilt-dev
description	Manage local development environments with Tilt. Use when working with projects that run services via Tilt (indicated by presence of Tiltfile), including checking service status, viewing logs, troubleshooting connectivity issues, or managing the Tilt stack. Essential for projects using Tiltfile with local_resource for orchestrating backend, frontend, and other services.

Tilt Development Environment Management

Manage and troubleshoot local development stacks orchestrated by Tilt.

Quick Start

Script paths shown as scripts/... assume your current working directory is skills/tilt-dev/. From repo root, use skills/tilt-dev/scripts/....

Check if Services Are Running

Always check before starting Tilt:

# Run status check script
scripts/check_tilt_status.sh [port]

# Or manually
tilt get uiresources --port <PORT>

Check Service Health

# Run health check script
scripts/get_service_health.sh

# Or manually check endpoints
curl http://localhost:3000/health     # Backend
curl http://localhost:3001/           # Frontend
curl http://localhost:4111/swagger-ui # Mastra

Start Tilt

Only if services are not already running:

tilt up --port <PORT>

Common ports: 10102, 10301, 10350

View Logs

tilt logs --port <PORT> <resource>

# Follow logs
tilt logs --port <PORT> <resource> --follow

Stop Tilt

tilt down

Important Principles

Always Check First

Services are likely already running with hot reload. Never blindly run tilt up without checking status first.

Prefer Health Checks Over Restarts

Check health endpoints and logs before restarting services. Tilt hot-reloads changes automatically.

Use the Tilt UI

Access at http://localhost:<PORT> for:

• Real-time resource status
• Build logs
• Service restarts
• Error messages

Common Workflows

Debug Service Not Responding

1. Check Tilt UI resource status
2. View resource logs: tilt logs --port <PORT> <resource>
3. Check health endpoint with curl
4. Review error messages in logs

View Recent Errors

# Tail logs for specific service
tilt logs --port <PORT> <resource> | tail -50

# Follow logs in real-time
tilt logs --port <PORT> <resource> --follow

Diagnose Tilt Issues

tilt doctor

Reference

See references/tilt_commands.md for:

• Complete command reference
• Tiltfile (Starlark) syntax guidelines
• Project-specific examples
• Troubleshooting guide
• Port conventions

Scripts

• scripts/check_tilt_status.sh [port] - Check if Tilt is running and list resources
• scripts/get_service_health.sh - Check health endpoints for common services