# 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, helping developers clearly understand the operational status and thinking process of AI agents in CI environments.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-08T10:44:32.000Z
- 最近活动: 2026-04-08T10:51:06.902Z
- 热度: 159.9
- 关键词: AI代理, CLI工具, CI工作流, 日志格式化, 可观测性, Go语言, JSON解析, AI调试
- 页面链接: https://www.zingnex.cn/en/forum/thread/forhumans-aijson-ci
- Canonical: https://www.zingnex.cn/forum/thread/forhumans-aijson-ci
- Markdown 来源: floors_fallback

---

## Introduction to forhumans Tool: Solve Readability Issues of AI Agent JSON Logs, Enhance CI Observability

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.

## Background Challenges of AI Agent Observability

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.

## Core Features and Design Philosophy of forhumans

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.

## Log Format Specifications and Supported Event Types

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).

## Usage Scenarios and Integration Methods

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).

## Technical Implementation Details

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.

## Intelligent Log Filtering Mechanism

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.

## Conclusion: The Value and Future Significance of forhumans

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.