Core Concepts

Sessions

A session is a single AI agent conversation — from the time you start interacting with an AI coding assistant to when you commit the resulting changes. partio captures:

Full transcript — the complete JSONL conversation log
Context summary — a markdown summary of what was discussed
Initial prompt — the first prompt that started the session
Metadata — agent name, token count, duration

Checkpoints

A checkpoint is the snapshot partio creates when you make a Git commit while an AI agent is active. Each checkpoint contains:

Field	Description
`id`	12-character hex identifier (e.g., `a3f8c2d14e9b`)
`session_id`	UUID of the AI agent session
`commit_hash`	The Git commit SHA this checkpoint is linked to
`branch`	The Git branch at the time of commit
`agent`	The detected agent (e.g., `claude-code`)
`agent_percent`	Percentage of the diff attributed to the AI (0-100)
`created_at`	RFC3339 timestamp

Storage layout

Checkpoint data lives on a Git orphan branch named partio/checkpoints/v1. No files are created in your working directory — everything is stored as Git objects using raw plumbing commands.

partio/checkpoints/v1  (branch)
└── <shard>/           (first 2 hex chars of ID)
    └── <rest>/        (remaining 10 hex chars)
        ├── metadata.json
        └── 0/
            ├── content_hash.txt
            ├── context.md
            ├── full.jsonl
            ├── metadata.json
            └── prompt.txt

The two-level shard structure (e.g., a3/f8c2d14e9b/) mirrors Git’s own object store to limit directory fanout.

Why an orphan branch?

Travels with your code — git push can include it automatically
No working directory clutter — data is stored as Git objects only
Standard Git tooling — you can inspect it with git log, git show, etc.
Easy cleanup — partio reset recreates the branch from scratch

Git hooks

partio installs three Git hooks to capture sessions automatically:

Hook	When it runs	What it does
`pre-commit`	Before a commit is created	Detects if an AI agent is running; saves session state to `.partio/state/`
`post-commit`	After a commit is created	Reads the saved state, captures the session, writes the checkpoint, and adds attribution trailers
`pre-push`	Before a push to remote	Pushes the `partio/checkpoints/v1` branch alongside your code

All hooks are non-blocking — they never prevent your commit or push from completing. If anything goes wrong, partio logs a warning and continues. Existing hooks are backed up as <hook-name>.partio-backup and chained after partio’s logic.

Git commit trailers

After creating a checkpoint, partio amends the commit to add two trailers:

Partio-Checkpoint: a3f8c2d14e9b
Partio-Attribution: 87% agent

These are standard Git trailers and can be parsed by any tool that reads commit messages.

Strategies

A strategy defines when and how partio captures checkpoints. Currently, one strategy is available:

`manual-commit`

Captures a checkpoint on every git commit when an AI agent is detected. This is the default and recommended strategy — it works with your existing workflow without any changes. See Strategies for more details.

Git Worktrees

partio fully supports git worktrees. If you use worktrees to work on multiple branches simultaneously, partio works across all of them without any extra setup.

How it works

Shared hooks — Hooks are installed to the shared git directory (git rev-parse --git-common-dir), not the per-worktree .git file. This means partio enable in any one worktree activates hooks for all worktrees in that repository.
Session discovery — partio walks up from the repository root to parent directories when looking for the active Claude Code session. This handles worktree layouts where Claude Code was launched from a parent workspace directory.
Shared checkpoint storage — All worktrees share the same partio/checkpoints/v1 orphan branch, since it lives in the shared object database.

Setup

Just run partio enable from any worktree — the hooks will be shared across all worktrees automatically:

cd my-project-feature-branch   # a worktree
partio enable
# Hooks are now active in every worktree for this repo

Getting Started

​Core Concepts

​Sessions

​Checkpoints

​Storage layout

​Why an orphan branch?

​Git hooks

​Git commit trailers

​Strategies

​manual-commit

​Git Worktrees

​How it works

​Setup