ATF — Agent Thread Format 🤖📦

The Universal Memory & Persistence Layer for AI Coding Agents and the Model Context Protocol (MCP).

---

💡 What is ATF?

Today's AI coding agents — such as OpenAI Codex, Antigravity, and Claude Code — store session logs, tool calls, and workspace file snapshots in proprietary, closed formats. When a coding session ends, the context is locked in an isolated silo with zero multi-agent portability.

ATF (Agent Thread Format) solves this by introducing a universal, open, human-readable, and Git-friendly file standard (.atf). It acts as the persistence and memory storage layer for the Model Context Protocol (MCP), enabling developers to:

• 🔁 Save & Replay Sessions: Archive complete multi-turn coding sessions with standardized tool execution graphs.
• 🔀 Support Branching DAGs: Model agent conversation forks as a Directed Acyclic Graph (DAG) without cycle risks.
• 🛡️ Preserve File Snapshots: Store exact local file copies captured during agent read/write operations with Zip Path Traversal protection.
• ⚡ Cross-Agent Conversion: Convert session histories seamlessly between OpenAI Codex, Antigravity, and Claude Code formats.

---

📦 Anatomy of an .atf Bundle

An .atf file is a portable ZIP bundle structured as follows:

session_record.atf (ZIP Archive)
├── metadata.json       # Agent version, LLM model, workspace root, VCS branch & commit hash
├── thread.jsonl        # DAG of events (messages, tool calls, thinking traces, token usage)
└── snapshots/          # Local file snapshots at the exact moment of read/write
    ├── src/main.py
    └── tests/test_app.py

1. metadata.json

Contains session header, agent origin, model identification, git commit hashes, and workspace state.

2. thread.jsonl

Stores sequential and branched events. Tool operations are mapped to standardized atf.* schemas:

• atf.fs.read / atf.fs.write / atf.fs.search / atf.fs.list
• atf.shell.run
• atf.web.search / atf.web.read
• atf.agent.send / atf.mcp.call

---

🚀 Quick Start & Installation

1. Prerequisites

• Python 3.10 or higher
• Git

2. Setup Virtual Environment & Install

# Clone the repository
git clone https://github.com/marcellopps283/atf.git
cd atf

# Create and activate virtual environment
python -m venv .venv

# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install package in editable mode with viewer dependencies
pip install -e .[viewer]

---

🛠️ CLI Usage

The atf Command Line Tool provides commands for bundle inspection, structural linting, format conversion, and web dashboard visualization.

# View summary statistics of an ATF bundle
atf info test_cli.atf

# Lint bundle structural integrity (verifies DAG cycle-free & tool call parity)
atf lint test_cli.atf

# Convert an agent session log into ATF format
atf convert --from-agent antigravity --session-dir ./logs --output-path session.atf --workspace-root .

# Launch the interactive Streamlit Web Viewer Dashboard
atf view --bundle-path test_cli.atf

---

🖥️ Streamlit Web Explorer

Launch the built-in dark mode dashboard to visually inspect agent execution:

atf view

Key features of the explorer:

• 📊 Metrics Overview: Event counters, fork counts, and prompt/completion token breakdown.
• 💬 Timeline View: Interactive history of user prompts, assistant messages, tool calls, and thinking traces.
• 🗂️ Snapshot File Browser: Inspect local file states captured during the session.
• ⚙️ JSON Inspector: Raw metadata and thread event inspection.

---

🧪 Running Tests

The test suite validates Pydantic v2 schemas, DAG cycle detection, Zip path traversal defense, and adapter conversions:

pytest -o pythonpath=src

---

📄 License & Standards

Licensed under the Apache 2.0 License.

Developed as part of the OpenAI Build Week Hackathon submission.