Introduction

Overview

ContextSubstrate (ctx) is an execution substrate designed to bring developer-native rigor to AI agent workflows. It provides the tooling necessary to make agentic execution reproducible, debuggable, and contestable.

As AI agents move from simple chat interfaces to complex, multi-step autonomous systems, the "black box" nature of their execution creates trust and reliability gaps. ctx bridges these gaps by treating agent runs as immutable, content-addressed snapshots—effectively acting as a "Git for AI Agent state."

Using primitives like files, hashes, and diffs, ctx allows you to capture the complete context of an agent's work, compare different runs to identify drift, and replay executions step-by-step to verify logic.

Core Concepts

Context Packs

The fundamental unit of ctx is the Context Pack. A pack is an immutable, content-addressed manifest that captures the entire state of an agent's execution:

Inputs: The exact files, prompts, and configurations the agent received.
Steps: The chronological sequence of tool calls, reasoning, and actions.
Outputs: The resulting artifacts and data produced.
Environment: Metadata about the OS, runtime, and tool versions used.

Content Addressing

Similar to Git, every object in a context store is identified by a unique cryptographic hash. This ensures that if a prompt, input file, or tool output changes by even a single character, the resulting Context Pack hash will change, providing a built-in integrity check for AI provenance.

Why use ContextSubstrate?

Reproducibility: Capture every variable of a run so it can be recreated exactly in any environment.
Drift Detection: Use ctx diff to compare two execution packs. Identify exactly where an agent's reasoning or tool usage diverged between model versions or prompt iterations.
Step-by-Step Debugging: Replay a captured run to inspect the specific tool inputs and outputs at any point in the agent's lifecycle.
Artifact Provenance: Verify that a specific file or piece of data was actually produced by a specific agent run using the ctx verify command.
Drafting & Forking: Take an existing execution, fork it into a mutable draft, modify the inputs, and test how changes affect the outcome.

Quick Start

ctx is designed to fit into existing developer workflows via its CLI.

1. Initialize a Store

Initialize a .ctx/ directory in your project to start tracking executions.

ctx init

2. Capture an Execution

Convert an agent's raw JSON execution log into an immutable, content-addressed Context Pack.

ctx pack execution_log.json

3. Compare Runs

Identify "Drift" between two different agent executions (e.g., comparing GPT-4 vs. a fine-tuned local model).

ctx diff <hash-a> <hash-b> --human

4. Verify Provenance

Ensure a generated artifact matches the records in your context store.

ctx verify ./generated_report.pdf

Architecture

ContextSubstrate operates as a layer between your Agent Framework (like LangChain, AutoGPT, or custom loops) and your storage. By consuming standardized logs, it creates a permanent record of what the agent "thought," what it "did," and what it "produced."