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, Cursor, Codex, Aider) 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

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

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

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

Seven event types capture everything that happened:

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

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 | |-----------|--------| | Claude Code JSONL | Available | | Watchtower DB | Available | | Aider | Planned | | OpenAI Codex | Planned | | Cursor | Planned |

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.