TLC

Test Led Coding for Claude Code. Tests before code. Automatically.

npx tlc-claude-code   # or just: tlc (after global install)

Why TLC?

You tell Claude to build something. It builds it. You test it manually. It's broken. You debug. Repeat.

That's backwards.

TLC writes tests before code exists. Every feature has a spec. Every spec is executable. When the code works, you know — because the tests pass.

You describe → Tests written → Code implemented → Tests pass → Done

No manual testing. No "does this work?" No vibes.

Start Here

Quick Start

New Project

/tlc:new-project

Existing Project

/tlc:init

Then Just Run

/tlc:next

Shows what's next, asks "Proceed? [Y/n]", then executes. That's it.

Or use /tlc for the full dashboard.

Features

For Solo Developers

• Test-first by default — Claude writes tests before code
• Auto-parallelization — Up to 10 agents run independent tasks simultaneously
• /tlc:next — One command to progress. No decisions needed.
• Smart dashboard — See progress, run actions
• Coverage gaps — Find and fix untested code
• Auto-fix — Automatically repair failing tests

For Teams

• Task claiming — Prevent duplicate work across engineers
• Bug tracking — QA submits bugs, engineers fix them
• Dev server — Mini-Replit with live preview and logs
• Issue sync — GitHub, Jira, Linear integration

📄 Team Workflow Guide — How 3 engineers + PO + QA collaborate with TLC

For Enterprise

• CI/CD pipelines — GitHub Actions, GitLab, Azure, CircleCI
• Dev server — Branch previews with auth & Slack webhooks
• Multi-tool export — Works with Cursor, Copilot, Continue, Cody

Commands

Team Commands

Integration Commands

See all commands →

Team Collaboration

TLC supports distributed teams with git-based coordination.

### Task 1: Create schema [x@alice]     ← completed by alice
### Task 2: Add validation [>@bob]      ← bob is working
### Task 3: Write tests [ ]             ← available

/tlc:claim 2                  # Reserve task 2
/tlc:who                      # See team status
tlc init      # Add dev server launcher
# Then double-click tlc-start.bat

📄 Full Team Workflow Guide →

Dev Server

Launch a mini-Replit for your team with Docker:

# Add launcher to your project (one-time)
tlc init

# Windows: double-click tlc-start.bat
# Mac/Linux: ./tlc-start.sh

What you get:

Features:

• Live preview — Your app embedded in dashboard
• Real-time logs — App, tests, git activity
• Bug submission — Web form for QA
• Task board — Who's working on what
• Multi-project — Containers named tlc-{project}-* for simultaneous projects
• Hot reload — Code changes apply instantly (no restart needed)

Rebuild when needed:

tlc rebuild      # After package.json changes or to get a clean slate

Requirements: Docker Desktop

Test Quality

Quality Scoring

/tlc:quality

• Coverage (lines, branches, functions)
• Edge case detection
• Mutation testing score

Edge Case Generation

/tlc:edge-cases src/auth/login.ts

AI-generated tests for null, boundaries, unicode, security.

Auto-Fix

/tlc:autofix

Automatically repair failing tests with retry loop.

Test Framework

TLC defaults to mocha + chai + sinon + proxyquire.

Configure in .tlc.json:

{
  "testFrameworks": {
    "primary": "mocha",
    "installed": ["mocha", "chai", "sinon", "proxyquire"],
    "run": ["mocha"]
  }
}

Also supports Jest, Vitest, and others via /tlc:config.

Architecture

PROJECT.md                    Project overview
.planning/
  ROADMAP.md                  Phases and progress
  BUGS.md                     Bug tracker
  phases/
    1-PLAN.md                 Phase 1 tasks
    2-PLAN.md                 Phase 2 tasks
.tlc.json                     Configuration
tlc-start.bat                 Docker dev launcher (Windows, gitignored)

TLC Installation Files

C:\Code\TLC\                  (or your install location)
  start-dev.ps1               PowerShell launcher
  docker-compose.dev.yml      Container orchestration
  server/                     Dashboard server

Works With

Install

# Install globally (recommended)
npm install -g tlc-claude-code

# Then use anywhere:
tlc              # Install slash commands to Claude Code
tlc init         # Add Docker launcher to project (creates tlc-start.bat)
tlc rebuild      # Full Docker rebuild (after package.json changes)
tlc --help       # See all options

Or use without installing:

npx tlc-claude-code            # Interactive install
npx tlc-claude-code --global   # Global install
npx tlc-claude-code --local    # Local install only

Commands install to .claude/commands/tlc/

TLC Dev Server

Deploy TLC dev server for your team on any Linux server.

Quick Setup (Ubuntu)

curl -fsSL https://raw.githubusercontent.com/jurgencalleja/TLC/main/scripts/vps-setup.sh | bash

What You Get

Requirements

• Ubuntu 22.04+ server (2GB+ RAM)
• Domain with wildcard DNS (*.project.com → SERVER_IP)
• GitHub/GitLab repo access

Manual Setup

1. Install dependencies

   apt install docker.io nginx certbot nodejs npm postgresql

2. Clone and configure

   git clone https://github.com/jurgencalleja/TLC.git /opt/tlc
   cd /opt/tlc && npm install
   cp .env.example .env  # Edit with your settings

3. Setup nginx + SSL

   certbot --nginx -d "*.project.com" -d "dashboard.project.com"

4. Start server

   systemctl enable tlc && systemctl start tlc

5. Configure webhook in GitHub/GitLab repo settings

Full Dev Server Guide →

Kubernetes Deployment

For teams using Kubernetes:

# Add Helm repo
helm repo add tlc https://jurgencalleja.github.io/TLC/charts

# Install
helm install tlc tlc/tlc-server \
  --set domain=project.example.com \
  --set slack.webhookUrl=https://hooks.slack.com/...

Kubernetes Features

• Auto-scaling branch deployments per namespace
• Ingress with wildcard TLS
• Persistent volumes for deployment state
• ConfigMaps for environment config

Full K8s Guide →

Documentation

Getting Started

• Noob Guide — Never coded before? Complete setup from zero
• Skip Manual - Start — Know how to code? 30-second setup

Reference

• Help / All Commands — Complete command reference
• Configuration — .tlc.json options
• Troubleshooting — Common issues and fixes

Guides

• Team Workflow — Guide for teams (engineers + PO + QA)
• Dev Server — Deploy on Ubuntu server
• Kubernetes Deployment — Deploy on K8s

Philosophy

Tests define behavior. Code makes tests pass.

• Tests written BEFORE code
• Untested code gets flagged
• Coverage gaps get prioritized
• Human verification still happens

License

MIT

_{Built for Claude Code}