Why I Built Codex Log Viewer: Treating User Intent as a First-Class Audit Trail

Codex Log Viewer

Software teams have spent decades treating source code as the primary artifact of development. It is what we review, test, debug, deploy, and audit. But as more software is built with AI coding agents, source code alone is no longer enough to explain how a system came into existence.

When work is directed through natural language, the prompt becomes part of the engineering record.

The user messages sent to an AI agent capture something code often cannot: intent. They contain the instructions, constraints, corrections, approvals, design preferences, business rules, and changes in direction that shaped the final implementation. They help answer questions that are becoming increasingly important:

• What did the human ask the agent to do?
• What did the agent understand?
• Where did the work change direction?
• Was the final behavior intended, assumed, or accidentally introduced?

That is why I built Codex Log Viewer.

At first, I wanted a clearer way to understand how I was using Codex across my own projects. I wanted to see which repositories were getting the most attention, how often I was using AI assistance, what kinds of requests I was making, which prompts repeated, how token usage was distributed, and where sessions became unusually large or complex.

As AI-assisted development becomes part of everyday coding, the interaction history is now different. The code diff tells us what changed. The commit message tells us what we chose to preserve. The issue or ticket tells us what we thought we were solving at the beginning. But the user messages sent to an AI agent often contain the most direct record of intent during the work.

They show the corrections. They show the constraints. They show the moments where a human clarified a requirement, rejected an approach, narrowed the scope, added a test, changed a design, or approved a direction.

That history is operational evidence.

It can help explain why a program behaves the way it does, why a feature was implemented in a certain direction, why a test was added, why a UI was adjusted, or why a deployment decision was made. In an environment where humans and agents collaborate through natural language, the prompt becomes part of the system history.

Codex Log Viewer started from that belief.

The foundation was a local parser for Codex session logs. I wanted the app to read the files already on my machine, normalize the records, preserve unknown events, and compute trustworthy metrics without sending private development history to a hosted service. Privacy was part of the architecture from the start.

Privacy is important because these logs can contain prompts, code, file paths, command output, screenshots, business context, and other sensitive material. I did not want a dashboard that encouraged uploading private engineering history. I wanted a local-first desktop utility that felt inspectable, private, and controlled by the user.

The early work focused heavily on correctness. Codex logs are event streams, and event streams evolve. Some records describe sessions. Some describe user messages. Some describe assistant responses. Some contain token usage, tool activity, or event shapes that are not fully documented.

A useful viewer cannot assume a perfect schema. It needs to be tolerant, fixture-driven, and honest about what it knows. That meant building parser tests, sanitized fixtures, malformed-line handling, token aggregation rules, and a clear separation between exact values and inferred views.

Once the parser and analytics engine were stable enough, the project became a native macOS app. The app starts a private local engine, protects it with an app-owned token, and keeps the primary workflows on the user’s machine.

The product then evolved through real use.

• Which projects did I work on?
• How many messages did I send?
• How many tokens did I use?
• Which sessions were active?

Then I needed cross-project search. I needed to select a prompt and see the actual Codex interaction that followed it. I needed Browse, Utilization Overview, Search, and Audit views. I needed a way to separate user-authored prompts from generated context wrappers. I needed date filters, project filters, role filters, model filters, session filters, export controls, and a way to inspect warnings and unknown events without pretending the data was cleaner than it was.

One of the most important iterations was the Project Focus view.

Raw message counts are useful, but they do not explain what the work was about. So Codex Log Viewer now classifies submitted user messages into categories such a:

• planning
• implementation
• bug fixes
• testing
• documentation
• code review
• release work
• data analysis
• feedback.

That classifier had to improve through real patterns, not theoretical ones. When too many messages fell into an “other” bucket, that was a signal that the tool was not yet reflecting the work accurately. The goal was not to make a chart for its own sake. The goal was to turn a pile of interactions into a readable picture of how engineering attention was being spent.

The audit worklog became the clearest expression of the broader idea.

Codex Log Viewer can generate a reviewed Markdown worklog for a repository that preserves work-directing user messages, summarizes the response, records what changed, lists verification, and keeps privacy review in the loop.

This is not meant to replace commits, pull requests, tests, or human judgment. It complements them. It gives future reviewers a better answer to a question that will matter more as AI-assisted development becomes normal:

What did the human ask the agent to do, and how did the agent respond?

That question matters for quality. If a bug appears later, the user-intent trail can show whether the agent misunderstood the request, whether the human changed direction, whether verification was skipped, or whether the final code drifted away from the original goal.

It matters for maintainability, because future contributors need to understand not only what exists, but why certain decisions were made.

It matters for governance, because teams using AI agents need more than output logs. They need a responsible way to inspect the human-agent collaboration that produced the output.

Today, Codex Log Viewer can parse local Codex logs, group sessions by project, count messages and unique prompts, track token usage by type and model, search messages across projects, browse submitted user messages, inspect related Codex responses and tool activity, filter operational prompt families, export redacted summaries, and generate audit worklogs for repositories.

It is still intentionally local-first. It favors privacy, transparency, and fixture-backed correctness over polish for its own sake.

I am also open sourcing the code so others can inspect it, use it, improve it, and adapt it to their own workflows. This problem is bigger than one tool or one coding agent. As AI-assisted development matures, we will need better ways to capture, index, catalog, search, and visualize the user messages that shaped software systems.

Git commits will still matter. Source code will still matter. Pull requests, tests, and reviews will still matter.

But the conversation that produced the code may become one of the clearest ways to understand why a system was built the way it was.

For me, the core lesson from building Codex Log Viewer is simple: the user message is not disposable.

It is the closest artifact we have to intent at the moment work is being directed. If we care about software quality, accountability, and long-term maintainability in AI-assisted engineering, we should preserve that intent carefully, review it thoughtfully, and make it usable without forcing people to give up control of their private development history.

---

Repository Details

I’m open sourcing Codex Log Viewer, a local-first native macOS app and parser for Codex session logs.

It helps developers understand how they use Codex across projects: submitted prompts, repeated messages, session history, token usage, model usage, project activity, search, exports, and AI audit trails. The project is privacy-conscious by design: logs stay local by default, fixtures are sanitized, and exports are redacted unless explicitly requested.

Repo: https://github.com/crispierry/codex-log-viewer

The project includes a SwiftUI macOS app, TypeScript parser and analytics engine, CLI tooling, sanitized fixtures, tests, CI, security policy, contributing guide, and MIT license.

---

This writing reflects my personal perspectives on product management, AI, and content discovery. It does not represent the official position of my employer or any affiliated organization.