If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alibaba/transmittable-thread-local shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alibaba/transmittable-thread-local repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alibaba/transmittable-thread-local.

What it runs against: a local clone of alibaba/transmittable-thread-local — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alibaba/transmittable-thread-local | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alibaba/transmittable-thread-local. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alibaba/transmittable-thread-local.git
#   cd transmittable-thread-local
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alibaba/transmittable-thread-local and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alibaba/transmittable-thread-local(\\.git)?\\b" \\
  && ok "origin remote is alibaba/transmittable-thread-local" \\
  || miss "origin remote is not alibaba/transmittable-thread-local (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ttl-core/src/main/java/com/alibaba/ttl3/TransmittableThreadLocal.java" \\
  && ok "ttl-core/src/main/java/com/alibaba/ttl3/TransmittableThreadLocal.java" \\
  || miss "missing critical file: ttl-core/src/main/java/com/alibaba/ttl3/TransmittableThreadLocal.java"
test -f "ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java" \\
  && ok "ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java" \\
  || miss "missing critical file: ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java"
test -f "ttl-agent/src/main/java/com/alibaba/ttl3/agent/TtlTransformer.java" \\
  && ok "ttl-agent/src/main/java/com/alibaba/ttl3/agent/TtlTransformer.java" \\
  || miss "missing critical file: ttl-agent/src/main/java/com/alibaba/ttl3/agent/TtlTransformer.java"
test -f "ttl-core/src/main/java/com/alibaba/crr/Transmittable.java" \\
  && ok "ttl-core/src/main/java/com/alibaba/crr/Transmittable.java" \\
  || miss "missing critical file: ttl-core/src/main/java/com/alibaba/crr/Transmittable.java"
test -f "ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/JdkExecutorTtlTransformlet.java" \\
  && ok "ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/JdkExecutorTtlTransformlet.java" \\
  || miss "missing critical file: ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/JdkExecutorTtlTransformlet.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alibaba/transmittable-thread-local"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

TransmittableThreadLocal (TTL) is an enhanced Java library that extends InheritableThreadLocal to reliably transmit context values between threads even when using thread pooling components (ExecutorService, ForkJoinPool, etc.). Unlike standard InheritableThreadLocal which only copies on thread creation, TTL captures and restores values across task boundaries in pooled threads, solving the framework/middleware problem of losing request context in async/concurrent code. Modular Maven monorepo: ttl3-parent (root pom.xml, version 3.x-SNAPSHOT) with ttl-agent submodule for bytecode instrumentation; core library in src/main/java; scripts/ contains performance tests (memoryleak and TPS benchmarks), CI integration tests, and JAPI compliance checks; docs/ has architecture diagrams (TransmittableThreadLocal.asta, sequence diagram), developer guides, and performance analysis.

Framework and middleware developers (Spring, Dubbo, gRPC integrators) and distributed system engineers who need to propagate user context (request IDs, trace context, authentication) across thread boundaries in thread-pooled applications without manually managing context objects.

Highly mature and production-ready: v2.x is stable and deployed at scale (Alibaba), v3.x (current master branch) is under active development with comprehensive CI (fast + strong workflows in .github/workflows/), high test coverage (codecov badge present), Java 6+ support, and Apache 2.0 licensed. The project is well-maintained with clear versioning and release processes (scripts/release.sh present).

Low risk for v2.x usage (stable), but master branch is v3.x-SNAPSHOT under development per README warning. Risk factors: single primary maintainer (@oldratlee visible in pom.xml), no external dependencies (0-dependency design reduces supply chain risk), but breaking changes may occur on master. Check branch before integrating—use 2.x branch for production stability.

v3 development is ongoing per README (issue #432 tracks workitems). Master branch targets Java with enhanced capabilities over v2. CI workflows (.github/workflows/ci.yaml and strong_ci.yaml) run on commits, and dependabot.yml manages dependencies. Strong CI appears to include integration tests (scripts/integration-test.sh) and performance validation, indicating active quality focus.

git clone https://github.com/alibaba/transmittable-thread-local.git && cd transmittable-thread-local && git checkout 2.x (for stable) or stay on master (for v3 dev) && ./mvnw clean install

Daily commands: Build: ./mvnw clean install (mvnw wrapper in root). Run tests: ./mvnw test. Run perf benchmarks: scripts/perf-test/tps-TransmittableThreadLocal.sh or memoryleak variants. Run agent demo: scripts/run-agent-demo.sh. Integration tests: scripts/integration-test.sh.

• ttl-core/src/main/java/com/alibaba/ttl3/TransmittableThreadLocal.java — Core class implementing the enhanced InheritableThreadLocal that transmits values across thread boundaries—the foundational abstraction every contributor must understand.
• ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java — Utility class providing wrapper factories for Runnable, Callable, and other concurrent primitives to capture and transmit TTL values—essential for thread pool integration.
• ttl-agent/src/main/java/com/alibaba/ttl3/agent/TtlTransformer.java — Java agent bytecode transformer that instruments thread-related classes to automatically propagate TTL context—critical for automatic integration without manual wrapping.
• ttl-core/src/main/java/com/alibaba/crr/Transmittable.java — Interface defining the contract for transmittable context resources used by the CRR (Capture-Restore-Replay) pattern—abstraction layer for extensibility.
• ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/JdkExecutorTtlTransformlet.java — Specific bytecode transformlet for Java's standard executor framework—illustrates agent-based instrumentation patterns for thread pool support.
• pom.xml — Root Maven POM defining multi-module build structure (ttl-core, ttl-agent, ttl-bom) and dependency management—required for understanding build and release process.
• ttl-core/src/main/java/com/alibaba/ttl3/TtlRunnable.java — Wrapper for Runnable that captures and restores TTL context—demonstrates the manual wrapping approach for frameworks that don't use the agent.

Add Support for a New Executor Type via Agent Instrumentation

1. Create a new transformlet class extending AbstractExecutorTtlTransformlet in ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/ (ttl-agent/src/main/java/com/alibaba/ttl3/agent/transformlet/internal/{YourExecutorName}TtlTransformlet.java)
2. Implement target class matching logic and bytecode transformation to wrap executor submit/execute methods with TTL context capture/restore ({YourExecutorName}TtlTransformlet.java)
3. Register the transformlet in TtlExtensionTransformletManager or TtlTransformer to enable discovery and loading (ttl-agent/src/main/java/com/alibaba/ttl3/agent/TtlExtensionTransformletManager.java)
4. Add test cases verifying TTL values propagate through the executor with and without agent instrumentation (ttl-core/src/test/java/com/alibaba/ttl3/executor/{YourExecutorName}TtlTest.java)

Extend TTL for Custom Context Resources via Transmittable Interface

1. Create a custom class implementing com.alibaba.crr.Transmittable interface with capture(), restore(), and beforeExecute() methods (ttl-core/src/main/java/com/alibaba/crr/custom/MyContextResource.java)
2. Implement capture() to snapshot current context state and restore() to apply captured state in target thread (MyContextResource.java)
3. Register the Transmittable instance with CompositeTransmittable or use directly with TransmittableThreadLocal as a holder (ttl-core/src/main/java/com/alibaba/crr/composite/CompositeTransmittable.java)
4. Verify context is properly captured and restored across thread boundaries in unit tests (ttl-core/src/test/java/com/alibaba/crr/MyContextResourceTest.java)

Create a New Wrapper for Unsupported Task Types

1. Add a new static factory method in TtlWrappers.java following the naming convention wrap{TaskType}() (ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java)
2. Create a new wrapper class (e.g., TtlYourTask.java) implementing the original task interface and storing captured TTL context (ttl-core/src/main/java/com/alibaba/ttl3/TtlYourTask.java)
3. Override task execution methods to restore captured context before delegating to original task, then clear context afterward (TtlYourTask.java)
4. Add integration tests confirming TTL values are transmitted and isolated correctly across wrapped task executions (ttl-core/src/test/java/com/alibaba/ttl3/TtlYourTaskTest.java)

Integrate TTL into a Framework without Using the Agent

1. Add ttl-core as a dependency with scope 'provided' to your framework pom.xml (or build config) (your-framework/pom.xml)
2. Wrap executor submit/execute calls using TtlWrappers.wrap{Type}() at all thread pool entry points (your-framework/src/main/java/YourFrameworkThreadPoolManager.java)
3. Optionally wrap callback methods (success/error handlers) using TtlWrappers.wrap{Type}() to preserve context across async boundaries (your-framework/src/main/java/YourFrameworkAsyncCallback.java)
4. Document which component uses TTL wrapping and list compatible executor types (standard JDK pools tested) (your-framework/docs/ttl-integration.md)

v3 on master is pre-release (SNAPSHOT)—production code should use 2.x branch per README. Bytecode instrumentation (ttl-agent) requires JVM agent flag at startup (not always obvious in containerized deployments). Performance is measured carefully (perf-test scripts)—any change touching thread holder maps or capture logic may regress TPS. JAPI compliance checks are enforced (check-japi-compliance.sh)—renaming/removing public methods will break backward compat. Java 6+ baseline means no modern syntax—maintain compatibility. No external dependencies means all context tracking is manual; study the holder tracking mechanism carefully before modifying.

• InheritableThreadLocal — This is the JDK base class that TTL extends; understanding its limitations (only inherits on thread creation, not in pooled threads) is essential to grasp why TTL exists
• Bytecode Instrumentation / Java Agent — TTL uses the ttl-agent module with bytecode manipulation to intercept thread pool task submissions transparently without requiring source code changes
• WeakHashMap-based Holder Tracking — TTL manages context across threads using weak references to prevent memory leaks when threads are recycled in pools; critical to understand for memory profiling
• Context Capture and Restore Pattern — TTL's core pattern captures parent thread context before task submission and restores it in child thread execution; this is the key innovation over InheritableThreadLocal
• Thread Pool Task Interception — TTL wraps Runnable/Callable in thread pool contexts to inject captured context; understanding Executor and ExecutorService contract is needed to modify or debug this
• Memory Leak in ThreadLocal / Reference Escaping — TTL's design specifically addresses ThreadLocal memory leaks in thread pools; scripts/perf-test/memoryleak-*.sh validate this; knowing the leak mechanism is essential

• alibaba/TThreadPool — Alibaba's thread pool that natively integrates TTL for automatic context propagation in pooled tasks
• alibaba/sentinel — Alibaba's flow control library that uses TTL to propagate request context across thread boundaries in circuit breaking
• spring-projects/spring-core — Spring framework uses TTL internally for propagating thread-local context in async execution and reactive stacks
• openzipkin/brave — Distributed tracing library that relies on ThreadLocal propagation mechanisms similar to TTL for trace context across async threads

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for thread pool scenarios with various executors

The repo focuses on transmitting values between threads in thread pooling scenarios, but the test coverage for real-world executor implementations (ForkJoinPool, ScheduledExecutorService, CustomThreadPoolExecutor) appears minimal. This would validate the core value proposition. The scripts/integration-test.sh exists but lacks documented test cases for edge cases like nested thread submissions and executor decorator patterns.

• [ ] Create src/test/java/com/alibaba/ttl3/integration/executor/ directory structure
• [ ] Add test classes for ForkJoinPool, ScheduledExecutorService, and common framework executors (Spring, etc.)
• [ ] Add tests for nested/cascading thread submissions and TTL value propagation across multiple hops
• [ ] Update scripts/integration-test.sh to document and run these new test suites
• [ ] Document results in docs/integration-test-scenarios.md

Add automated compatibility verification for Java 21+ virtual threads

Java 21+ introduced virtual threads (Project Loom), which fundamentally change thread semantics. The repo targets modern Java but there's no visible GitHub Actions workflow or documentation testing TTL behavior with virtual threads, structured concurrency, and thread-per-request models. This is critical for future-proofing.

• [ ] Create .github/workflows/virtual-threads-test.yaml to run tests on Java 21+ with virtual threads enabled
• [ ] Add src/test/java/com/alibaba/ttl3/integration/VirtualThreadCompatibilityTest.java with tests for virtual thread scenarios
• [ ] Document findings and any limitations in docs/virtual-threads-compatibility.md
• [ ] Add a matrix in the workflow to test both platform and virtual threads across Java 21, 22, 23 (LTS versions)
• [ ] Reference this in CONTRIBUTING.md as a required check for maintainers

Create detailed performance regression test suite with CI benchmarking

Multiple performance test scripts exist (scripts/perf-test/), but they lack automated CI integration and results tracking. The docs/performance-test.md references benchmarking but there's no GitHub Actions workflow that runs these on every PR to catch regressions. This is critical for a performance-sensitive library used in middleware.

• [ ] Create .github/workflows/performance-benchmark.yaml that runs perf-test scripts on PR and main branch
• [ ] Refactor scripts/perf-test/ shell scripts into a JMH-based benchmark suite (src/test/java/com/alibaba/ttl3/perf/)
• [ ] Add benchmark result comparison/regression detection in CI output (e.g., using jmh-gradle-plugin or similar)
• [ ] Document baseline metrics and regression thresholds in docs/performance-baselines.md
• [ ] Add a step to comment benchmark results on PRs automatically

• idea: Add Kotlin documentation examples in docs/ showing TTL usage with coroutines, since repo has 350K Kotlin lines but developer guides show only Java examples
• idea: Create a runnable example under docs/ or examples/ directory showing TTL integration with a real thread pool (ExecutorService) scenario, since sequence diagrams exist but no step-by-step demo code
• idea: Expand scripts/perf-test/ with a new benchmark comparing TTL overhead vs. stdlib InheritableThreadLocal across different pool sizes (small, medium, large) since current scripts test individual scenarios

The TransmittableThreadLocal library demonstrates generally good security practices with proper vulnerability reporting mechanisms via SECURITY.md and Alibaba Security Response Center. No critical vulnerabilities were identified in the static analysis. The main observations are: (1) the project is in development (v3 SNAPSHOT) which is appropriate for a development branch; (2) no hardcoded secrets, credentials, or sensitive information discovered; (3) no obvious injection vulnerabilities visible in file structure; (4) Java agent components require ongoing security vigilance due to their system-level access; (5) well-established security reporting procedures are in place. The codebase follows good practices with Apache 2 licensing, active CI/CD, and proper vulnerability coordination protocols.

• Low · SNAPSHOT Version in Production — pom.xml (version: 3.x-SNAPSHOT). The pom.xml specifies version '3.x-SNAPSHOT', indicating development/unreleased code. SNAPSHOT versions should not be used in production as they can change without warning and lack formal release testing. Fix: Use stable release versions in production. Only use SNAPSHOT versions in development environments with controlled access.
• Low · Incomplete POM Developer Information — pom.xml (developers section). The POM file appears truncated in the developer section, which could indicate incomplete configuration or version control issues. This doesn't directly expose security but suggests incomplete maintenance. Fix: Ensure pom.xml is complete and properly formatted. Validate against Maven schema.
• Low · Agent Component Risk — ttl-agent/ directory, TtlAgent.java, TtlTransformer.java. The project includes a Java agent (ttl-agent) that performs bytecode transformation. Java agents have elevated privileges and can modify application behavior at runtime. While this is intentional for the library's purpose, it requires careful security review. Fix: Ensure agent code undergoes rigorous security review. Validate that bytecode transformations don't introduce security vulnerabilities. Document all transformations clearly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.