Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
import { appendFile, existsSync, mkdirSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import type { DiagOutput } from "./diag-output.js";
import { redactSigningValues } from "./redact.js";
let logFilePath: string | null = null;
let logLevel: "debug" | "info" | "minimal" = "info"; // Default to structured logging
let stderrQuiet = false; // When true, logStderr writes to log file only (no terminal output)
let diagOutput: DiagOutput | null = null; // DiagOutput instance for routing stderr in interactive mode
let logBuffer: string[] = []; // Buffer for async writes
let flushTimer: NodeJS.Timeout | null = null;
const FLUSH_INTERVAL_MS = 100; // Flush every 100ms
const MAX_BUFFER_SIZE = 50; // Flush if buffer exceeds 50 messages
// Tier 1: Always-on structural logging state
let alwaysOnLogPath: string | null = null;
let alwaysOnBuffer: string[] = [];
/**
* Flush log buffer to file (async)
*/
function flushLogBuffer(): void {
if (!logFilePath || logBuffer.length === 0) return;
const toWrite = logBuffer.join("");
logBuffer = [];
// Async write (non-blocking)
appendFile(logFilePath, toWrite, (err) => {
if (err) {
console.error(`[claudish] Warning: Failed to write to log file: ${err.message}`);
}
});
}
/**
* Flush always-on structural log buffer to file (async)
*/
function flushAlwaysOnBuffer(): void {
if (!alwaysOnLogPath || alwaysOnBuffer.length === 0) return;
const toWrite = alwaysOnBuffer.join("");
alwaysOnBuffer = [];
appendFile(alwaysOnLogPath, toWrite, () => {});
}
/**
* Schedule periodic buffer flush
*/
function scheduleFlush(): void {
if (flushTimer) return; // Already scheduled
flushTimer = setInterval(() => {
flushLogBuffer();
flushAlwaysOnBuffer();
}, FLUSH_INTERVAL_MS);
// Cleanup on process exit
process.on("exit", () => {
if (flushTimer) {
clearInterval(flushTimer);
flushTimer = null;
}
// Final flush (must be sync on exit)
if (logFilePath && logBuffer.length > 0) {
writeFileSync(logFilePath, logBuffer.join(""), { flag: "a" });
logBuffer = [];
}
if (alwaysOnLogPath && alwaysOnBuffer.length > 0) {
writeFileSync(alwaysOnLogPath, alwaysOnBuffer.join(""), { flag: "a" });
alwaysOnBuffer = [];
}
});
}
/**
* Keep only the most recent N log files, delete older ones.
*/
function rotateOldLogs(dir: string, keep: number, name = "claudish"): void {
try {
const files = readdirSync(dir)
.filter((f) => f.startsWith(`${name}_`) && f.endsWith(".log"))
.sort()
.reverse();
for (const file of files.slice(keep)) {
try {
unlinkSync(join(dir, file));
} catch {}
}
} catch {}
}
/**
* Strip content from a JSON SSE line, preserving structure.
* Replaces string values longer than 20 chars with "<N chars>".
* Preserves: keys, numbers, booleans, nulls, short strings (model names, event types, finish reasons).
*/
export function structuralRedact(jsonStr: string): string {
try {
const obj = JSON.parse(jsonStr);
return JSON.stringify(redactDeep(obj));
} catch {
// Not valid JSON — redact long strings inline
return jsonStr.replace(/"[^"]{20,}"/g, (m) => `"<${m.length - 2} chars>"`);
}
}
/** Keys that always carry model/user content — redact regardless of length */
const CONTENT_KEYS = new Set([
"content",
"reasoning_content",
"text",
"thinking",
"partial_json",
"arguments",
"input",
]);
function redactDeep(val: any, key?: string): any {
if (val === null || val === undefined) return val;
if (typeof val === "boolean" || typeof val === "number") return val;
if (typeof val === "string") {
// Content keys: always redact (these carry model/user text)
if (key && CONTENT_KEYS.has(key)) {
return `<${val.length} chars>`;
}
// Other strings: keep short ones (model names, event types, tool names, finish reasons)
return val.length <= 20 ? val : `<${val.length} chars>`;
}
if (Array.isArray(val)) return val.map((v) => redactDeep(v));
if (typeof val === "object") {
const result: any = {};
for (const [k, v] of Object.entries(val)) {
result[k] = redactDeep(v, k);
}
return result;
}
return val;
}
/**
* Determine if a log message should be written to the always-on structural log.
* Only structural/diagnostic messages, not verbose debug noise.
*/
function isStructuralLogWorthy(msg: string): boolean {
return (
msg.startsWith("[SSE:") ||
// Output the terminal firewall kept off the TTY. This is the ONLY durable
// record of it: the diag file is unlinked on session cleanup, so without
// this entry a suppressed dependency crash would vanish entirely. Matched
// explicitly rather than relying on the generic "error" substring below —
// a suppressed stdout line need not contain the word.
msg.startsWith("[Suppressed]") ||
msg.startsWith("[Proxy]") ||
// How the spawned Claude Code process ended: its exit code, or the signal
// that killed it. The [Proxy] lines above cannot record a child that died
// before its first request, which is exactly the session whose log looks
// empty and whose failure the user most needs named.
msg.startsWith("[Claude Code]") ||
msg.startsWith("[Fallback]") ||
// The MCP server's own failures: a tool that answered from a fallback (an
// older catalog generation, no recommended list) says why only here.
msg.startsWith("[mcp]") ||
msg.startsWith("[recommended]") ||
msg.startsWith("[catalog]") ||
msg.startsWith("[effort]") ||
msg.startsWith("[team]") ||
// Connection-recovery episodes: which target, which attempt, how long the
// next gap is, and how the episode ended. Without this entry the ladder's
// only trace is behind `-d`, and the one thing a user reports about an
// outage is that the session hung — a report nobody can check against a
// log that was never written.
msg.startsWith("[Recovery]") ||
msg.startsWith("[Streaming] ===") || // HANDLER STARTED
msg.startsWith("[Streaming] Chunk:") ||
msg.startsWith("[Streaming] Received") ||
msg.startsWith("[Streaming] Text-based tool calls") ||
msg.startsWith("[Streaming] Final usage") ||
msg.startsWith("[Streaming] Sending") ||
msg.startsWith("[AnthropicSSE] Stream complete") ||
msg.startsWith("[AnthropicSSE] Tool use:") ||
msg.includes("Response status:") ||
msg.includes("Error") ||
msg.includes("error") ||
msg.includes("[Auto-route]")
);
}
/**
* Redact content from a log line for structural logging.
* SSE lines get JSON structural redaction. Other lines pass through.
*/
function redactLogLine(message: string, timestamp: string): string {
// SSE raw events: redact the JSON payload
if (message.startsWith("[SSE:")) {
const prefixEnd = message.indexOf("] ") + 2;
const prefix = message.substring(0, prefixEnd);
const payload = message.substring(prefixEnd);
return `[${timestamp}] ${prefix}${structuralRedact(payload)}\n`;
}
// Other lines: pass through (they don't contain user content)
return `[${timestamp}] ${message}\n`;
}
/**
* The per-session part of a log filename: a UTC timestamp plus this process id.
*
* The PID is load-bearing, not decoration. The timestamp has one-second
* resolution and the file is opened with `writeFileSync`, which TRUNCATES. Any
* two claudish processes that start in the same second therefore compute the
* same path and each wipes what the other wrote.
*
* That is not a rare race: `team` and `create_session` spawn their
* children together, so a three-model run reliably lands three processes inside
* one second. Measured 2026-09-16 on exactly such a run, the surviving file held
* three interleaved `[Proxy] Server started` lines on three different ports and
* was missing the handler-creation lines for one of the children entirely —
* during an investigation into why that child produced no output.
*
* A concurrent run is precisely when the logs matter most, and it was the case
* that destroyed them.
*/
function logFileStamp(): string {
const timestamp = new Date()
.toISOString()
.replace(/[:.]/g, "-")
.split("T")
.join("_")
.slice(0, -5);
return `${timestamp}_${process.pid}`;
}
/**
* Initialize file logging for this session
*/
export function initLogger(
debugMode: boolean,
level: "debug" | "info" | "minimal" = "info",
noLogs = false,
// The file name prefix of the always-on log, rotated per prefix: the MCP server
// passes "claudish-mcp" so its files never push a session's log out of those kept.
name = "claudish",
// Files kept per prefix. Every Claude Code session and every team or session child
// starts its own MCP server, so a busy run writes dozens of MCP logs in minutes:
// with 20 kept, the files of a failure were gone before anyone read them.
keep = 20
): void {
// Tier 1: Always-on structural logging (unless --log-off)
if (!noLogs) {
// A log exists for diagnostics: an unwritable ~/.claudish/logs (read-only home,
// sandbox, full disk) turns it off instead of failing the process that asked.
try {
const logsDir = join(homedir(), ".claudish", "logs");
if (!existsSync(logsDir)) {
mkdirSync(logsDir, { recursive: true });
}
alwaysOnLogPath = join(logsDir, `${name}_${logFileStamp()}.log`);
writeFileSync(
alwaysOnLogPath,
`Claudish Session Log - ${new Date().toISOString()}\nMode: structural (content redacted)\n${"=".repeat(60)}\n\n`
);
rotateOldLogs(logsDir, keep, name);
// Start flush timer if not already running
scheduleFlush();
} catch {
alwaysOnLogPath = null;
}
}
// Tier 2: Debug verbose logging (existing behavior, only with --debug-claudish)
if (debugMode) {
logLevel = level;
const logsDir = join(process.cwd(), "logs");
if (!existsSync(logsDir)) {
mkdirSync(logsDir, { recursive: true });
}
logFilePath = join(logsDir, `claudish_${logFileStamp()}.log`);
writeFileSync(
logFilePath,
`Claudish Debug Log - ${new Date().toISOString()}\nLog Level: ${level}\n${"=".repeat(80)}\n\n`
);
scheduleFlush();
} else {
logFilePath = null;
// Clear any existing timer only if always-on is also disabled
if (noLogs && flushTimer) {
clearInterval(flushTimer);
flushTimer = null;
}
}
}
/**
* Log a message (to file only in debug mode, silent otherwise)
* Uses async buffered writes to avoid blocking event loop
*/
export function log(rawMessage: string, forceConsole = false): void {
// Before any buffer, file or console write: `log` is the only writer of the
// debug file and of the always-on log, so this one pass covers every line
// either receives (an echoed credential in a queue 429, a parser frame, an
// auth exception). A no-op when no request holds a signing value.
const message = redactSigningValues(rawMessage);
const timestamp = new Date().toISOString();
const logLine = `[${timestamp}] ${message}\n`;
// Tier 2: Debug log (full content, existing behavior)
if (logFilePath) {
// Add to buffer (non-blocking)
logBuffer.push(logLine);
// Flush immediately if buffer is getting large
if (logBuffer.length >= MAX_BUFFER_SIZE) {
flushLogBuffer();
}
}
// Tier 1: Always-on structural log (redacted content)
if (alwaysOnLogPath && isStructuralLogWorthy(message)) {
const redactedLine = redactLogLine(message, timestamp);
alwaysOnBuffer.push(redactedLine);
if (alwaysOnBuffer.length >= MAX_BUFFER_SIZE) {
flushAlwaysOnBuffer();
}
}
// Force console output (for critical messages even when not in debug mode)
if (forceConsole) {
console.log(message);
}
}
/**
* Log a message to stderr and to the debug log file.
* In quiet mode (interactive Claude Code sessions), only writes to log file
* to avoid corrupting Claude Code's TUI display.
* When a DiagOutput is set, stderr messages are routed there instead.
*/
export function logStderr(rawMessage: string): void {
// Same pass as `log`, before stderr or DiagOutput sees the line.
const message = redactSigningValues(rawMessage);
if (diagOutput) {
// Route to DiagOutput (log file) instead of polluting stderr
diagOutput.write(message);
} else if (!stderrQuiet) {
process.stderr.write(`[claudish] ${message}\n`);
}
log(message); // always write to debug log
}
/**
* A network-recovery episode's own account of itself: opened, each attempt,
* each wait, the outcome.
*
* ── WHY THIS IS STRUCTURAL OUTPUT AND NOT A DEBUG AID ───────────────────────
*
* These lines were on `log()`, which writes to two FILES — the `--debug` log
* and the always-on structural log under `~/.claudish/logs/`. That satisfies
* "it is written down" and fails the thing it was written down for. Recovery
* holds an inbound request for up to the derived deadline (~4.5 minutes at the
* default), and in a run with no pane — `-p`, CI, a pipe, any machine without
* magmux, which is EVERY headless run — nothing at all reaches the user while
* it does. A silent multi-minute hold with the reason legible nowhere is the
* state this feature's own design calls "strictly worse than the bug it exists
* to remove"; a file the user does not know to open is not a surface.
*
* The noise objection is real and is already answered by the channel: in an
* interactive session `logStderr` routes to `DiagOutput` (a file) rather than
* to the client's TUI, and in quiet mode it is suppressed. So the lines land on
* a terminal exactly where a terminal is the only surface there is, which is
* the case that needed them.
*
* Fine-grained plumbing — pane connect/disconnect, socket paths, a skipped
* ladder — stays on `log()`. This is for the episode's LIFECYCLE only: the six
* or so lines from which a reader can reconstruct the ladder.
*/
export function logRecovery(message: string): void {
logStderr(message);
}
/**
* Set the DiagOutput instance. When set, logStderr() routes to it
* instead of stderr. This replaces the stderrQuiet mechanism for
* interactive sessions.
*/
export function setDiagOutput(output: DiagOutput | null): void {
diagOutput = output;
}
/**
* Suppress stderr output (for interactive Claude Code sessions where
* stderr corrupts the TUI). Log file output is preserved.
* Kept for backwards compatibility — prefer setDiagOutput() for new code.
*/
export function setStderrQuiet(quiet: boolean): void {
stderrQuiet = quiet;
}
/**
* Get the current log file path
*/
export function getLogFilePath(): string | null {
return logFilePath;
}
/**
* Get the always-on structural log file path
*/
export function getAlwaysOnLogPath(): string | null {
return alwaysOnLogPath;
}
/**
* Check if logging is enabled (useful for optimizing expensive log operations)
*/
export function isLoggingEnabled(): boolean {
return logFilePath !== null || alwaysOnLogPath !== null;
}
/**
* Mask sensitive credentials for logging
* Shows only first 4 and last 4 characters
*/
export function maskCredential(credential: string): string {
if (!credential || credential.length <= 8) {
return "***";
}
return `${credential.substring(0, 4)}...${credential.substring(credential.length - 4)}`;
}
/**
* Set log level (debug, info, minimal)
* - debug: Full verbose logs (everything)
* - info: Structured logs (communication flow, truncated content)
* - minimal: Only critical events
*/
export function setLogLevel(level: "debug" | "info" | "minimal"): void {
logLevel = level;
if (logFilePath) {
log(`[Logger] Log level changed to: ${level}`);
}
}
/**
* Get current log level
*/
export function getLogLevel(): "debug" | "info" | "minimal" {
return logLevel;
}
/**
* Truncate content for logging (keeps first N chars + "...")
*/
export function truncateContent(content: string | any, maxLength = 200): string {
if (content === undefined || content === null) return "[empty]";
const str = typeof content === "string" ? content : (JSON.stringify(content) ?? "[empty]");
if (str.length <= maxLength) {
return str;
}
return `${str.substring(0, maxLength)}... [truncated ${str.length - maxLength} chars]`;
}
/**
* Log structured data (only in info/debug mode)
* Automatically truncates long content based on log level
*/
export function logStructured(label: string, data: Record<string, any>): void {
if (!logFilePath) return;
if (logLevel === "minimal") {
// Minimal: Only show label
log(`[${label}]`);
return;
}
if (logLevel === "info") {
// Info: Show structure with truncated content
const structured: Record<string, any> = {};
for (const [key, value] of Object.entries(data)) {
if (typeof value === "string" || typeof value === "object") {
structured[key] = truncateContent(value, 150);
} else {
structured[key] = value;
}
}
log(`[${label}] ${JSON.stringify(structured, null, 2)}`);
return;
}
// Debug: Show everything
log(`[${label}] ${JSON.stringify(data, null, 2)}`);
}