| name | zcl |
| description | Add colored terminal output to Java applications using zcl (Zero-dependency Colour Logger). Use when adding colored console output, terminal logging with colors, ANSI color support, or integrating zcl into a Java project. Triggers on "zcl", "colored output", "colored logging", "terminal colors", "ANSI colors", "console colors", or requests to add color-coded log output to a Java application. |
Add colored terminal output to a Java application using $ARGUMENTS. Apply all rules below.
What is zcl
zcl is a zero-dependency, single-enum Java logging utility using ANSI 24-bit true-colour escape sequences from the Solarized Dark accent palette. zcl is designed as a source-reuse project — the Log.java file is copied directly into your source tree, not consumed as a Maven/Gradle dependency or JAR. This keeps the project free of external dependencies.
Integration
Copy the Log.java enum below into the application's source tree. Adjust the package declaration to match the target package.
import java.io.PrintStream;
public enum Log {
ERROR(Color.RED, System.err),
USER(Color.CYAN, System.out),
INFO(Color.GREEN, System.out),
SYSTEM(Color.BLUE, System.out),
WARNING(Color.YELLOW, System.out),
DEBUG(Color.VIOLET, System.out),
SUCCESS(Color.MAGENTA, System.out);
private PrintStream out;
enum Color {
YELLOW("\033[38;2;181;137;0m"),
ORANGE("\033[38;2;203;75;22m"),
RED("\033[38;2;220;50;47m"),
MAGENTA("\033[38;2;211;54;130m"),
VIOLET("\033[38;2;108;113;196m"),
BLUE("\033[38;2;38;139;210m"),
CYAN("\033[38;2;42;161;152m"),
GREEN("\033[38;2;133;153;0m");
String code;
Color(String code) {
this.code = code;
}
}
private final String value;
private final static String RESET = "\u001B[0m";
private Log(Color color, PrintStream out) {
this.value = (color.code + "%s" + RESET);
this.out = out;
}
String formatted(String raw) {
return this.value.formatted(raw);
}
void out(String message) {
var colored = formatted(message);
this.out.println(colored);
}
public static void debug(String message) {
Log.DEBUG.out(message);
}
public static void error(String message) {
Log.ERROR.out(message);
}
public static void error(String message, Exception e) {
Log.ERROR.out(message + ": " + e.getMessage());
e.printStackTrace(System.err);
}
public static void user(String message){
Log.USER.out(message);
}
public static void info(String message){
Log.INFO.out(message);
}
public static void system(String message){
Log.SYSTEM.out(message);
}
public static void clearScreen(){
IO.println("\033c");
}
public static void warning(String message){
Log.WARNING.out(message);
}
public static void success(String message){
Log.SUCCESS.out(message);
}
public static void stop(String message){
error(message);
System.exit(0);
}
}
Log Levels
| Level | Solarized Color | Stream | Static Method | Purpose |
|---|
ERROR | Red | System.err | Log.error(msg) | Critical failures |
USER | Cyan | System.out | Log.user(msg) | User messages and interactive elements |
INFO | Green | System.out | Log.info(msg) | General information |
SYSTEM | Blue | System.out | Log.system(msg) | System-level messages |
WARNING | Yellow | System.out | Log.warning(msg) | Warning conditions |
DEBUG | Violet | System.out | Log.debug(msg) | Debug information for developers |
SUCCESS | Magenta | System.out | Log.success(msg) | Success messages and completions |
Usage
All interaction uses the public static convenience methods. The instance methods out() and formatted() are package-private.
Log.error("Database connection failed");
Log.error("Connection failed", exception);
Log.user("Welcome to the application");
Log.info("Operation completed");
Log.system("Server started on port 8080");
Log.warning("Cache miss detected");
Log.debug("Processing item #42");
Log.success("Build completed successfully");
Log.clearScreen();
Log.stop("Fatal error — shutting down");
Integration Rules
- Copy
Log.java into the project source tree — do not add it as a Maven/Gradle dependency. Only include the enum constants, Color entries, and static methods that the target project actually uses. Remove unused log levels and their corresponding colors and convenience methods.
- Add a
package declaration matching the target package at the top of the copied file
- Use the static methods (
Log.error(), Log.info(), Log.system(), etc.) — never call the package-private instance methods out() or formatted() from outside the enum
- Replace
System.out.println calls with the appropriate Log level
- Use
Log.error(message, exception) for exception logging — it prints the message and full stack trace to System.err
- Use
Log.stop(message) only for unrecoverable errors that require immediate process termination
- Add domain-specific log levels for the application. If the project has a clear domain concept that deserves its own color (e.g.,
PROMPT, RESPONSE, QUERY, METRIC), add a new enum constant with an appropriate Solarized Color and a corresponding public static void convenience method. Domain-specific levels make log output immediately scannable by category.
- After integration, evaluate whether domain-specific loggers should be introduced. Review the
System.out.println and Log.* call sites across the codebase and identify recurring domain categories (e.g., HTTP requests, AI prompts, pipeline stages, business events). If a category appears in three or more locations and would benefit from distinct color-coding for scannability, propose a dedicated enum constant and convenience method. Do not introduce domain-specific loggers speculatively — only when actual usage patterns justify them.