forhumans: Make JSON Logs of AI Agents Readable, Enhance Observability in CI Workflows

forhumans is a lightweight CLI tool designed specifically to convert structured JSONL event streams output by the pi.dev AI agent tool into human-readable log formats. It helps developers clearly understand the operational status and thinking process of AI agents in CI environments, solving the problem of cumbersome reading of raw JSON logs. This tool is written in Go, has no external dependencies, and features simple deployment and excellent performance.

With the widespread application of AI agents in software development workflows, developers face challenges in monitoring and understanding their behaviors. In non-interactive CI environments, the JSON-formatted event streams output by AI agents are convenient for program processing, but reading and understanding these raw logs is very cumbersome for humans. The forhumans project was born precisely to solve this problem.

The design philosophy of forhumans is to keep it simple and focus on a single responsibility. As a tool written purely in Go, it does not rely on external libraries and uses only the Go standard library to implement all functions, bringing the advantages of simple deployment and excellent performance. Its core workflow follows the Unix filter pattern: read JSONL event streams from standard input, parse event types and content, and output human-readable log lines.

The log format defined by forhumans is HH:MM:SS [TAG] content, which includes a timestamp, event type TAG, and specific content. Supported event types include: session events (metadata such as session ID, working directory), agent lifecycle events (START/END), conversation turn events (START/END), user messages, thinking processes (truncated to 200 characters by default), agent responses (multi-line indented), and tool call events (full process recording).

The typical usage scenario of forhumans is CI/CD pipelines. Developers can pipe the standard output of AI agents to the tool to obtain readable logs in real time. Basic usage examples are cat output.jsonl | ./forhumans-cli or ./agent-harness | ./forhumans-cli. The tool provides the --lifecycle option to display full lifecycle events (hidden by default to keep logs concise).

The code structure of forhumans is clear: the internal/events package is responsible for event type definition, JSON deserialization, timestamp parsing, and text extraction; the internal/formatter package handles formatting logic (text truncation, output generation); cmd/main.go serves as the CLI entry point, responsible for JSONL reading and parameter parsing. The project includes 40 unit tests covering all event types, boundary cases, etc., to ensure stability.

forhumans automatically skips redundant intermediate events: *_delta events (e.g., thinking_delta), _start/_update events except tool_execution_start/end, and message_start events of non-user types. For unknown type events, they are marked as [UNKNOWN] and the original JSON is retained to ensure forward compatibility and visibility of new events.

forhumans is a small but beautiful tool that solves practical problems in AI agent workflows, bridging the gap between AI agents and human developers. As the role of AI agents in software development becomes more important, such observability tools will be more critical, helping to debug and understand AI behaviors, and improving the transparency and interpretability of AI systems.