AgentLog
Open standard for AI agent session interchange

---

AgentLog defines a portable JSON format for recording what happens during AI agent sessions. One format for every tool, every workflow, every platform.

{
  "specVersion": "0.2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "agent": { "name": "Claude Code", "model": "claude-sonnet-4-6" },
  "events": [
    { "type": "message", "role": "user", "content": "Fix the auth bug" },
    { "type": "fileOperation", "operation": "edit", "path": "src/auth.ts", "linesAdded": 4 },
    { "type": "terminalCommand", "command": "npm test", "exitCode": 0 }
  ]
}

The Problem

Every AI coding tool (Claude Code, Grok, Codex, Cursor, OpenCode, Kulti) produces session logs in its own proprietary format. There's no way to:

• Search across sessions from different tools
• Measure AI coding impact across your engineering org
• Feed session data into observability platforms
• Understand how code was written, not just what was written

The Solution

AgentLog is a single, vendor-neutral format that captures the complete record: conversation, tool calls, file operations with diffs, terminal commands, reasoning traces, costs, and relationships to commits, PRs, and issues.

Specification

Document	Version	Status
Core Specification	0.2.0	Draft
JSON Schema	Draft 2020-12	Draft
TypeScript Types	0.2.0	Draft

Install

npm install @braintied/agentlog

Usage

Validate a session document

import { validateAgentLog, SPEC_VERSION } from '@braintied/agentlog';

const result = validateAgentLog(sessionData);
if (result.success) {
  console.log(`Valid AgentLog v${SPEC_VERSION}`);
}

Convert from Claude Code

import { convertClaudeCodeSession } from '@braintied/agentlog/convert/claude-code';

const session = await convertClaudeCodeSession('~/.claude/projects/myproject/session-uuid');
console.log(session.events.length, 'events captured');

Export from Watchtower 5.x

Watchtower is the capture product. AgentLog is the interchange format. Hooks and disk adapters already emit a SessionPayload. Convert that:

import { exportFromPayload } from '@braintied/agentlog/convert/payload';

const agentLog = exportFromPayload(webhookBody);

Or a coding_sessions row, with live session_messages when you have them (they win over the old metadata.raw_content reconstruction):

import { exportWatchtowerSession } from '@braintied/agentlog/convert/watchtower';

const agentLog = exportWatchtowerSession(dbRow, {
  projectName: 'my-app',
  messages: sessionMessages,
});

Convert a Grok history file

import { convertGrokHistory } from '@braintied/agentlog/convert/grok';

const session = await convertGrokHistory(
  '~/.grok/sessions/.../chat_history.jsonl',
);

Schema

An AgentLog document has three layers:

Layer 1 — Session Envelope

The required context: who, when, where, what tool.

Field	Type	Required	Description
specVersion	string	Yes	Always "0.2.0"
id	string	Yes	Session UUID
startTime	string	Yes	ISO 8601 start time
endTime	string/null	No	ISO 8601 end time
status	enum	Yes	active, completed, failed, cancelled
agent	object	Yes	Agent name, model, provider
project	object	No	Repo, branch, working directory
developer	object	No	Who ran the session

Layer 2 — Event Timeline

Twelve event types (spec 0.2.0). Capture produces message and toolCall first; the rest are for producers that have them.

Type	What it captures	Key fields
message	Conversation turns	role, content, tokenUsage
toolCall	Tool invocations	name, input, output, status
fileOperation	File changes	operation, path, diff, linesAdded
terminalCommand	Shell commands	command, stdout, exitCode
search	Code/web search	tool, query, resultCount
reasoning	AI decision-making	intent, alternatives, rationale
error	Errors + recovery	message, code, recovery, resolved
handoff	Agent-to-agent	fromAgent, toAgent, reason
approval	Human gates	action, approver, decision
plan	Planned steps	title, steps
checkpoint	Save points	checkpointType, label
contextLoad	Injected context	source, query

All events share: id, timestamp, parentId (for nesting), durationMs, properties (extensibility).

Layer 3 — Relationships

Links to the engineering graph: commits, pullRequests, issues, errors, deployments, parentSession, childSessions.

Extensibility

Every object has a properties bag for vendor-specific data (SARIF pattern):

{
  "agent": {
    "name": "Claude Code",
    "properties": {
      "claude-code:thinkingBudget": 32000,
      "claude-code:permissionMode": "auto"
    }
  }
}

Who It's For

Workflow	What AgentLog Records
Developer + AI	Claude Code sessions, Cursor chats — what you built and why
Agent + Agent	Multi-agent orchestration — delegation chains, sub-agent results
Teams	Fleet visibility — which agents ran, on what, at what cost

SDKs & Converters

Language	Package	Status
TypeScript/Node	@braintied/agentlog	Available
Python	—	Planned
Go	—	Planned

Converter	Status
Watchtower SessionPayload (5.x wire)	Available (convert/payload)
Watchtower coding_sessions + session_messages	Available (convert/watchtower)
Claude Code JSONL	Available
Grok chat_history.jsonl	Available (convert/grok)
Codex / Cursor / OpenCode disk	Capture is Watchtower's job. Feed the payload.
Aider	Not started

Sources named in AGENT_SOURCES: claude_code, grok, codex, cursor, opencode, gemini, kulti_meet. A missing source is not silently remapped.

Examples

Example	Events	Demonstrates
minimal-session.json	6	Basic edit + test flow
debugging-session.json	8	Error investigation with Sentry link
multi-agent-session.json	5	Parallel sub-agent orchestration

Complements Agent Trace

Agent Trace tracks attribution — which lines AI wrote. AgentLog tracks activity — what happened during the session.

Together: "what did AI write?" + "how did it get there?"

Design Influences

Pattern	Source
Minimal required fields	CloudEvents
Property bags	SARIF
JSON Schema as normative	CycloneDX
Discriminated event union	OTel GenAI
Profile modularity	SPDX 3.0

Community

• GitHub Issues — bugs, feature requests, spec proposals
• Contributing Guide — how to add converters, propose spec changes
• Security Policy — reporting vulnerabilities

License

Apache-2.0 — spec and code. The explicit patent grant (Section 3) protects implementers.

---

_{Built by Braintied · Reference implementation: Watchtower}