# Checkpoint Detail
Source: https://docs.partio.io/app/checkpoint-detail
Deep dive into a checkpoint's sessions, plan, and file changes
# Checkpoint Detail
The checkpoint detail page (`/:owner/:repo/checkpoints/:id`) is where you explore the full context behind a code change — the conversation, the plan, and the diff.
![Exploring checkpoint sessions, plan, and files]()
## Header
The header shows key metadata at a glance:
| Field | Description |
| ----------------- | ----------------------------------------------------------------- |
| **Title** | First user message from the session (truncated to 100 characters) |
| **Checkpoint ID** | First 8 characters of the checkpoint hash |
| **Commit** | First 8 characters of the associated commit hash |
| **Timestamp** | Relative time since the checkpoint was created |
| **Branch** | The Git branch this checkpoint was captured on |
| **Tokens** | Total tokens consumed during the session (if available) |
| **Agent** | Agent name and AI authorship percentage |
An **Actions** button in the top-right provides:
* Copy checkpoint ID to clipboard
* Download plan (if available)
* Share/export options based on the active tab
## Tabs
### Sessions
The transcript viewer displays the full conversation between the human and the AI agent:
* **Message bubbles** — Each message shows the role (human or assistant), content, and timestamp
* **Token counts** — Per-message token usage when available
* **Tool calls** — Tool names shown as pills/badges on assistant messages
* **Avatars** — User image and agent icon displayed alongside messages
This is the core "why" that partio captures — the reasoning and back-and-forth that produced the code change.
### Plan
If the agent generated a plan during the session, it's rendered as formatted markdown. This tab only appears when plan data exists (`plan_slug` is set on the checkpoint).
The plan typically contains the agent's high-level strategy, step-by-step breakdown, and reasoning for the approach taken.
### Files
A unified diff viewer showing all file changes in this checkpoint:
* File-by-file breakdown with added/removed/modified indicators
* Syntax-highlighted diffs with line numbers
* File count shown in the tab badge
# Dashboard Overview
Source: https://docs.partio.io/app/overview
The partio web dashboard for browsing checkpoints, sessions, and AI-authored code
# Dashboard Overview
The partio dashboard is a Next.js web app that gives you a visual interface for browsing everything partio captures — checkpoints, sessions, commits, pull requests, and code — across all your GitHub repositories.
![Dashboard overview showing stats, heatmap, and recent commits]()
## Accessing the Dashboard
The hosted dashboard is available at [app.partio.io](https://app.partio.io). Sign in with your GitHub account to get started. If you prefer to self-host, see the [Self-Hosting](/app/self-hosting) guide.
## Main Layout
The dashboard has three persistent elements:
* **Sidebar** (left) — Navigation links to Overview, Repositories, and Settings, plus your GitHub avatar and username at the bottom.
* **Topbar** (top) — Feedback link and sign-out button.
* **Content area** — The main content for the current page.
## Overview Page
The overview page (`/`) is your landing page after signing in. It shows:
### Stat Cards
Four key metrics across all your repositories with checkpoint data:
| Metric | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| **Total Checkpoints** | Cumulative count across all active repos |
| **This Week** | Checkpoints created in the last 7 days, with a trend indicator vs. the prior week |
| **Avg AI Authorship** | Average percentage of code authored by AI agents across checkpoints |
| **Active Streak** | Consecutive days with at least one checkpoint |
### Activity Heatmap
A calendar-style heatmap showing your checkpoint activity by day, similar to GitHub's contribution graph.
### Recent Commits
A table of the latest checkpoints across all repositories. Each row shows the repository name, branch, commit hash, agent name, authorship percentage, and relative timestamp. Click any row to jump to the checkpoint detail page.
## Navigation
Use the sidebar to move between sections:
* **Overview** — Stats, heatmap, and recent activity (this page)
* **Repositories** — Browse and search all your GitHub repos
* **Settings** — Customize your dashboard theme
Clicking on any repository name, commit, or checkpoint link takes you into the [Repository Detail](/app/repository-detail) view.
# Repositories
Source: https://docs.partio.io/app/repositories
Browse and search your GitHub repositories in the partio dashboard
# Repositories
The Repositories page (`/repositories`) lists all GitHub repositories accessible to your account. It's the starting point for drilling into any repo's checkpoints, commits, and code.
![Searching and filtering repositories]()
## Repository List
The page displays a table with the following columns:
| Column | Description |
| --------------- | ------------------------------------------------------------------------------------------------- |
| **Name** | Repository name with a colored dot indicating the primary language (TypeScript, Python, Go, etc.) |
| **Issues** | Open issue count |
| **Checkpoints** | Number of partio checkpoints captured for this repo |
| **Updated** | When the repo was last updated |
Click any row to navigate to the [Repository Detail](/app/repository-detail) page.
## Filtering
By default, only repositories **with at least one checkpoint** are shown. This keeps the list focused on repos where partio is actively capturing data.
Toggle the **"See all repositories"** button to show every repo your GitHub account has access to. Repos without checkpoints appear with dimmed styling.
## Search
Use the search input at the top to filter repositories by name. The filter applies instantly as you type.
# Repository Detail
Source: https://docs.partio.io/app/repository-detail
Explore checkpoints, commits, PRs, issues, and code for a single repository
# Repository Detail
When you click into a repository, the dashboard shows a tabbed interface for exploring that repo's data. The URL pattern is `/:owner/:repo`.
![Navigating repository detail tabs]()
## Header
The repo header displays:
* **Owner and repo name** with the owner's avatar
* **Visibility badge** (Public or Private)
* **Tab navigation** with count badges
## Tabs
### Overview
A two-column layout showing the most important information at a glance.
**Sidebar** (left, hidden on mobile):
* Repository description and topics
* "Open on GitHub" link
* Metadata: language, license, default branch, last push date, repo size, homepage
* Checkpoint activity chart (weekly line chart)
* Contributor avatars
**Main content** (right):
* **Recent Checkpoints** — The latest 10 checkpoints as cards showing branch, commit hash, timestamp, agent name, and AI authorship percentage
* **Open Pull Requests** — Currently open PRs with author, labels, and comment count
### Checkpoints
A list of all partio checkpoints for this repository. Each checkpoint card shows:
* Checkpoint ID (full hash)
* Branch name badge
* Relative creation time
* Commit hash (first 8 characters)
* Commit message (first line) or plan title
* Warning icon if the associated commit no longer exists (e.g., after a rebase or squash)
Click any checkpoint to open the [Checkpoint Detail](/app/checkpoint-detail) page.
### Commits
Browse the Git commit history for any branch:
* **Branch selector** dropdown at the top (defaults to the repo's default branch)
* Each commit shows the short SHA, message, author avatar and name, and relative date
* Commits linked to a checkpoint display a link indicator
Click a commit to see its full diff, changed files, and stats.
### PRs
View pull requests with state filtering:
* Filter by **Open**, **Closed**, or **All**
* Each PR shows the number, title, author, state badge (open/closed/draft/merged), labels, dates, and comment count
Click a PR to see its full description, changed files, and related checkpoints.
### Code
A file browser for the repository's source code:
* **Directory view** — Table with file/folder names and sizes, with folder and file icons. Click to navigate deeper.
* **File view** — Syntax-highlighted code display with language auto-detection, copy button, and "See on GitHub" link.
* **Breadcrumb navigation** — Path hierarchy with clickable segments to navigate up.
# Self-Hosting
Source: https://docs.partio.io/app/self-hosting
Run the partio dashboard on your own infrastructure
# Self-Hosting
The partio dashboard can be self-hosted for teams that want full control over their data and deployment.
## Prerequisites
* **Node.js 20+**
* **GitHub OAuth App** — Create one at [github.com/settings/developers](https://github.com/settings/developers)
* Set the callback URL to `http://localhost:3000/api/auth/callback/github` (or your production URL)
## Environment Variables
Create a `.env.local` file in the `app/` directory:
```bash theme={null}
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
AUTH_SECRET=a_random_secret_string # Generate with: openssl rand -base64 32
```
| Variable | Required | Description |
| ---------------------- | -------- | -------------------------------------- |
| `GITHUB_CLIENT_ID` | Yes | From your GitHub OAuth App settings |
| `GITHUB_CLIENT_SECRET` | Yes | From your GitHub OAuth App settings |
| `AUTH_SECRET` | Yes | Random string used to encrypt sessions |
## Install & Run
```bash theme={null}
cd app
npm install
npm run dev
```
The dashboard will be available at `http://localhost:3000`. Sign in with your GitHub account to start browsing checkpoints.
## Production Build
```bash theme={null}
cd app
npm run build
npm start
```
For production deployments:
* Set the GitHub OAuth callback URL to your production domain
* Use a strong `AUTH_SECRET` value
* Deploy behind HTTPS
The dashboard uses NextAuth v5 (beta). The `AUTH_SECRET` must be set in production — NextAuth will not start without it.
## Architecture Notes
* **Auth**: NextAuth v5 with GitHub OAuth provider. Sessions use JWT strategy.
* **Data**: All data is fetched from GitHub via Octokit using the authenticated user's access token. No additional database is required.
* **Themes**: Theme color files are fetched from GitHub and cached with 24-hour revalidation.
# Settings & Themes
Source: https://docs.partio.io/app/settings
Customize your dashboard with 50+ themes from the OMARCHY theme registry
# Settings & Themes
The Settings page (`/settings`) lets you customize the look of your dashboard with themes from the [OMARCHY](https://github.com/basecamp/omarchy) theme registry.
![Browsing and applying dashboard themes]()
## Theme Library
The dashboard ships with **50+ themes** from two sources:
* **Official themes** (14) — Curated themes from the OMARCHY project, including Tokyo Night, Catppuccin, Gruvbox, Nord, Everforest, and more.
* **Community themes** (36+) — Contributed by the community, including Dracula, Synthwave '84, Aura, One Dark Pro, and others.
Each theme is displayed as a card showing:
* Preview color swatches
* Theme name and author
* A checkmark badge on the currently active theme
## Filtering
Use the controls at the top of the page to narrow down themes:
* **Search** — Filter themes by name or author
* **Type tabs** — Switch between **All**, **Dark**, and **Light** themes
## Applying a Theme
Click any theme card to apply it. The dashboard updates instantly — all colors across the interface change to match the selected theme. Your choice is saved to local storage and persists across sessions.
Click **"Reset to default"** to return to the default purple dark theme.
## Wallpaper
Some themes include background wallpaper images. When available, use the **wallpaper toggle** to enable or disable the background image for the current theme.
## How Themes Work
Themes define 12 color variables that control the entire UI:
| Variable | Purpose |
| --------------- | ------------------------------------- |
| `background` | Page background |
| `foreground` | Primary text |
| `muted` | Secondary/dimmed text |
| `accent` | Primary accent (links, active states) |
| `accent-light` | Lighter accent variant |
| `accent-dark` | Darker accent variant |
| `surface` | Card/panel backgrounds |
| `surface-light` | Elevated surface backgrounds |
| `border` | Border colors |
| `success` | Success indicators |
| `warning` | Warning indicators |
| `accent-orange` | Agent/AI indicators |
Theme colors are fetched from their source repository (GitHub raw files), parsed from various formats (TOML, Alacritty, Ghostty), and applied as CSS custom properties.
# Commands
Source: https://docs.partio.io/cli/commands
Complete reference for all partio CLI commands
# CLI Commands
## Global flags
| Flag | Type | Default | Description |
| ------------- | ------ | ----------- | ----------------------------------------------------- |
| `--log-level` | string | From config | Override log level (`debug`, `info`, `warn`, `error`) |
***
## `partio enable`
Enable partio in the current Git repository.
```bash theme={null}
partio enable [--absolute-path]
```
| Flag | Type | Default | Description |
| ----------------- | ---- | ------- | ---------------------------------------------------------- |
| `--absolute-path` | bool | `false` | Install hooks using the absolute path to the partio binary |
**What it does:**
1. Verifies you're inside a Git repository
2. Ensures the `.partio/` config directory exists
3. Writes a default `settings.json` (existing config is preserved)
4. Adds `.partio/settings.local.json` to `.gitignore`
5. Installs Git hooks (`pre-commit`, `post-commit`, `pre-push`)
6. Ensures the `partio/checkpoints/v1` orphan branch exists
`partio enable` is **idempotent** — safe to re-run at any time to repair hooks or restore settings. Re-running preserves your existing configuration (it only flips `enabled` back to `true` if partio was disabled) and never overwrites custom values.
**`--absolute-path`:**
By default, hooks invoke `partio` by name and rely on PATH resolution at hook execution time. Use `--absolute-path` if partio is not on PATH in your hook execution environment — for example, when using nix, asdf, mise, or system-level git hooks.
```bash theme={null}
partio enable --absolute-path
```
This embeds the resolved absolute path of the partio binary into the installed hook scripts.
**Output:**
```
partio enabled successfully!
- Ensured .partio/ config directory exists
- Installed git hooks (pre-commit, post-commit, pre-push)
- Ready to capture AI sessions on commit
```
**External hook managers:**
If partio detects another Git hook manager — [Husky](https://typicode.github.io/husky/), [Lefthook](https://github.com/evilmartians/lefthook), or [Overcommit](https://github.com/sds/overcommit) — `partio enable` prints a warning with integration instructions and continues (it does not abort). partio's hooks must be invoked from within your hook manager's configuration via `partio _hook ` so both run:
```
Warning: Husky detected.
Partio's hooks must be called from within your hook manager's configuration.
Add partio hook calls to your Husky hook scripts. For example, in .husky/pre-commit add:
partio _hook pre-commit
and in .husky/post-commit add:
partio _hook post-commit
```
***
## `partio disable`
Disable partio in the current repository.
```bash theme={null}
partio disable [--remove-data]
```
| Flag | Type | Default | Description |
| --------------- | ---- | ------- | --------------------------------------------------- |
| `--remove-data` | bool | `false` | Also delete the `.partio/` directory and all config |
**What it does:**
1. Removes partio-managed hooks from `.git/hooks/`
2. Restores any backed-up original hooks
3. If `--remove-data`: deletes `.partio/` directory
**Output (default):**
```
partio disabled.
- Removed git hooks (originals restored from backup if present)
- Checkpoint data and config preserved (use --remove-data to delete)
```
***
## `partio status`
Show partio status for the current repository. Also runs automatic stale session cleanup before displaying results.
```bash theme={null}
partio status
```
**Output (enabled):**
```
Repository: /path/to/your-project
Branch: main
Status: enabled
Strategy: manual-commit
Linking: ask
Agent: claude-code
Hooks: installed
Checkpoints: branch exists
```
**Output (not enabled):**
```
Repository: /path/to/your-project
Branch: main
Status: not enabled (run 'partio enable' to set up)
```
***
## `partio rewind`
List or restore checkpoints.
```bash theme={null}
partio rewind --list [--branch ]
partio rewind --to
```
| Flag | Type | Default | Description |
| ---------- | ------ | ------- | --------------------------------------------------------------------- |
| `--list` | bool | `false` | List all stored checkpoints |
| `--to` | string | `""` | Restore to a specific checkpoint ID (12 hex characters) |
| `--branch` | string | `""` | Filter checkpoints by branch name (useful for squash-merged branches) |
**`--list` output:**
```
Checkpoints:
a3f8c2d14e9b branch=main agent=87% created=2026-02-17T14:30:00Z
bb12340092ac branch=feature/auth agent=100% created=2026-02-16T09:15:22Z
```
**`--list --branch` output:**
Filters the list to checkpoints whose branch name exactly matches the given value:
```bash theme={null}
partio rewind --list --branch feature/auth
```
```
Checkpoints:
bb12340092ac branch=feature/auth agent=100% created=2026-02-16T09:15:22Z
```
This is the recommended way to find sessions for a branch that was squash-merged into main.
**`--to` output:**
```
Rewinding to checkpoint a3f8c2d14e9b
Commit: 4f9a2c...
Branch: main
Context:
Created branch: partio/rewind/a3f8c2d14e9b
```
This creates a new branch named `partio/rewind/` checked out at the checkpoint's commit.
If the original commit is no longer reachable (e.g. the branch was squash-merged and the original commits were garbage-collected), partio emits a warning and exits without creating a rewind branch — the session context is still shown:
```
Warning: original commit a3f8c2d is no longer reachable (likely squash-merged or gc'd); session context is still available but branch checkout is skipped.
```
***
## `partio resume`
Resume a session from a checkpoint. Reads checkpoint data from the orphan branch and launches a new Claude Code session with the previous context.
```bash theme={null}
partio resume
partio resume --branch-name
```
| Flag | Type | Default | Description |
| --------------- | ------ | ------- | ----------------------------------------------------------------------------------------- |
| `--print` | bool | `false` | Print the composed context prompt to stdout |
| `--copy` | bool | `false` | Copy the context prompt to clipboard |
| `--branch` | bool | `false` | Create a branch at the checkpoint's commit before launching |
| `--branch-name` | string | `""` | Resume the most recent session from the named branch (recommended for squash-merged work) |
**Default behavior:**
Writes a context file to a temporary directory and launches Claude Code with instructions to read it and continue the previous work. If Claude Code is not found in PATH, the context is printed to stdout instead.
**With `--branch-name`:**
Finds all checkpoints for the named branch, selects the most recent one by creation time, and resumes it. This is the recommended approach for sessions whose branch was squash-merged into main:
```bash theme={null}
partio resume --branch-name feature/my-branch
```
Either a positional `` or `--branch-name` is required; invoking `resume` with neither exits non-zero with a usage error.
**With `--branch`:**
Creates a new branch named `partio/resume/` checked out at the checkpoint's commit before launching.
```
Created branch: partio/resume/a3f8c2d14e9b
Context written to /tmp/partio-resume-a3f8c2d14e9b.md
Launching Claude Code...
```
**With `--print`:**
```bash theme={null}
partio resume a3f8c2d14e9b --print
```
Prints the composed context prompt (including the original request, plan, diff, and session metadata) to stdout without launching Claude Code.
**With `--copy`:**
Copies the context prompt to the system clipboard (macOS and Linux).
***
## `partio doctor`
Check partio installation health.
```bash theme={null}
partio doctor
```
**Checks performed:**
1. `.partio/` directory exists
2. `pre-commit` hook installed, readable, and managed by partio
3. `post-commit` hook installed, readable, and managed by partio
4. `pre-push` hook installed, readable, and managed by partio
5. `partio/checkpoints/v1` branch exists
6. partio binary found in PATH
**Output (healthy):**
```
[OK] .partio/ directory exists
[OK] pre-commit hook installed
[OK] post-commit hook installed
[OK] pre-push hook installed
[OK] checkpoint branch exists
[OK] partio binary found (you're running it!)
All checks passed!
```
**Output (issues found):**
```
[WARN] .partio/ directory missing - run 'partio enable'
[WARN] pre-commit hook missing
[OK] post-commit hook installed
[WARN] post-commit hook exists but not managed by partio
[WARN] post-commit hook unreadable: permission denied
[WARN] checkpoint branch missing
[OK] partio binary found (you're running it!)
5 issue(s) found. Run 'partio enable' to fix.
```
***
## `partio prune`
Delete checkpoints older than a retention window from the `partio/checkpoints/v1` branch.
```bash theme={null}
partio prune [--older-than 90d] [--dry-run]
```
| Flag | Type | Default | Description |
| -------------- | ------ | ------- | --------------------------------------------------------------------------------- |
| `--older-than` | string | `"90d"` | Retention window; removes checkpoints older than this (e.g. `30d`, `90d`, `365d`) |
| `--dry-run` | bool | `false` | Preview what would be deleted without making any changes |
The checkpoint linked to the current `HEAD` is never removed. partio rebuilds the orphan branch's tree with git plumbing to drop the pruned entries.
**Dry-run output:**
```
Dry run — no changes made.
Would remove a3f8c2d14e9b (branch=feature/auth, created=2026-01-04T09:15:22Z)
Would remove bb12340092ac (branch=main, created=2026-01-02T14:30:00Z)
2 checkpoint(s) would be removed, 5 kept.
```
**Real run output:**
```
Removed a3f8c2d14e9b (branch=feature/auth, created=2026-01-04T09:15:22Z)
1 checkpoint(s) removed, 6 kept.
```
If nothing qualifies:
```
No checkpoints to prune.
```
***
## `partio reset`
Reset the checkpoint branch. This deletes all stored checkpoint data and recreates the branch.
```bash theme={null}
partio reset
```
**Output:**
```
Checkpoint branch reset successfully.
```
This permanently deletes all checkpoint data. This cannot be undone.
***
## `partio clean`
Remove orphaned checkpoint data.
```bash theme={null}
partio clean
```
Scans the checkpoint branch for data that no longer corresponds to any commit.
**Output:**
```
Checkpoint data present on partio/checkpoints/v1 branch.
To fully reset, run: partio reset
```
***
## `partio cleanup`
Manually clean up stale session files left behind by crashed or improperly terminated agent processes.
```bash theme={null}
partio cleanup
```
A session is considered stale when:
* It is in `ACTIVE` or `IDLE` state, and
* Its state file has not been updated within the configured threshold (default: 10 minutes), and
* If a process ID is recorded, the agent process is no longer alive.
**Output (stale session found):**
```
Cleaned up stale session: (agent=claude-code)
```
**Output (no stale sessions):**
```
No stale sessions found.
```
`partio status` also runs stale cleanup automatically before displaying results, so manual invocation is usually not necessary. Not to be confused with `partio clean`, which removes orphaned checkpoint data.
***
## `partio version`
Print the partio version.
```bash theme={null}
partio version
```
**Output:**
```
partio v0.1.0
```
# Configuration
Source: https://docs.partio.io/cli/configuration
Configure partio behavior with settings files and environment variables
# Configuration
## Config fields
| Field | Type | Default | Description |
| -------------------------------- | ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | bool | `true` | Whether partio is active |
| `strategy` | string | `"manual-commit"` | Capture strategy |
| `agent` | string | `""` | AI agent to track. Empty auto-detects the running agent (`claude-code` or `codex`) |
| `commit_linking` | string | `"ask"` | When to link commits to an active session: `ask`, `always`, or `never` |
| `log_level` | string | `"info"` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `strategy_options.push_sessions` | bool | `true` | Push checkpoint branch on `git push` |
| `redact.enabled` | bool | `true` | Redact secrets from checkpoint data before it is stored |
| `redact.entropy_threshold` | float | `4.5` | Shannon entropy (bits/char) above which a token is redacted |
| `redact.entropy_min_length` | int | `20` | Minimum token length considered for entropy scanning |
| `stale_session_threshold` | string | `"10m0s"` | How long an ACTIVE/IDLE session file can go without being updated before it is considered stale and cleaned up (e.g. `"10m"`, `"30m"`) |
## Default settings.json
Created by `partio enable`:
```json theme={null}
{
"enabled": true,
"strategy": "manual-commit",
"agent": "",
"commit_linking": "ask",
"log_level": "info",
"strategy_options": {
"push_sessions": true
},
"redact": {
"enabled": true,
"entropy_threshold": 4.5,
"entropy_min_length": 20
},
"stale_session_threshold": "10m0s"
}
```
## File locations
partio loads configuration from multiple sources, merged in order (later sources override earlier ones):
| Priority | Location | Description |
| ----------- | ------------------------------------ | ---------------------------------------- |
| 1 (lowest) | Built-in defaults | Hard-coded in the binary |
| 2 | `~/.config/partio/settings.json` | Global/user-level config |
| 3 | `/.partio/settings.json` | Repo-level config (committed) |
| 4 | `/.partio/settings.local.json` | Repo-level local overrides (git-ignored) |
| 5 (highest) | Environment variables | Runtime overrides |
Only fields actually present in a config file override the accumulated config. Unknown fields are ignored.
## Environment variables
| Variable | Overrides | Accepts |
| -------------------------------- | ------------------------- | ---------------------------------------------------------------------- |
| `PARTIO_ENABLED` | `enabled` | `true`, `1` (case-insensitive) for enabled; anything else for disabled |
| `PARTIO_STRATEGY` | `strategy` | Strategy name (e.g., `manual-commit`) |
| `PARTIO_LOG_LEVEL` | `log_level` | `debug`, `info`, `warn`, `error` |
| `PARTIO_AGENT` | `agent` | Agent name (e.g., `claude-code`, `codex`) |
| `PARTIO_COMMIT_LINKING` | `commit_linking` | `ask`, `always`, `never` |
| `PARTIO_STALE_SESSION_THRESHOLD` | `stale_session_threshold` | Duration string (e.g., `"10m"`, `"30m"`) |
## Choosing the agent
partio supports multiple AI coding agents — currently [Claude Code](/integrations/claude-code) and [Codex](/integrations/codex).
When `agent` is empty (the default), partio **auto-detects** whichever supported agent is running when you commit. Set `agent` (or `PARTIO_AGENT`) only when you want to pin a specific agent — for example, if you run more than one and want partio to prefer a particular one:
```json title=".partio/settings.json" theme={null}
{
"agent": "codex"
}
```
If the pinned agent isn't running at commit time, partio falls back to auto-detection.
## Commit linking
When you commit with an AI session active, partio links that commit to the session and creates a checkpoint. The `commit_linking` setting controls whether it asks first:
| Value | Behavior |
| --------------- | ------------------------------------------------------------------ |
| `ask` (default) | Show a `[Y/n/a]` prompt during the commit when a session is active |
| `always` | Always link, no prompt |
| `never` | Never link — no checkpoint is created |
With `ask`, the prompt accepts:
* **Y** (default) — link this commit to the session
* **n** — skip linking for this commit only
* **a** — always link from now on (persists `commit_linking: always` to `.partio/settings.json`)
In non-interactive environments (no TTY — CI, scripted commits), partio auto-links without prompting.
```bash theme={null}
# Never prompt, and skip session linking entirely
PARTIO_COMMIT_LINKING=never git commit -m "Docs typo"
```
## Secret redaction
Before any session data is written to the checkpoint branch, partio runs a two-layer secret redaction pass over all user-visible text fields (prompt, context, diff, JSONL transcript, and plan):
1. **Pattern-based detection** — gitleaks-compatible regular expressions detect common secret formats including AWS access keys, GitHub personal access tokens, Slack tokens, Stripe keys, Google API keys, npm/PyPI tokens, and generic `api_key=…` / `Bearer …` assignments. Matched secrets are replaced with `[REDACTED]`.
2. **Entropy-based detection** — any whitespace-delimited token that is at least `entropy_min_length` characters long and has a Shannon entropy ≥ `entropy_threshold` bits/char is also replaced with `[REDACTED]`. This catches high-entropy strings that match no known pattern, while leaving short version strings, commit hashes, URLs, and natural-language words intact.
Redaction is enabled by default and tuned via the `redact` block:
```json title=".partio/settings.json" theme={null}
{
"redact": {
"enabled": true,
"entropy_threshold": 4.5,
"entropy_min_length": 20
}
}
```
Redaction is a best-effort safety net, not a substitute for proper secret management (environment variables, secret managers). The git diff captured in a checkpoint may still contain other sensitive data depending on your code.
## Examples
### Disable auto-push of sessions
If you don't want checkpoint data to be pushed automatically:
```json title=".partio/settings.json" theme={null}
{
"strategy_options": {
"push_sessions": false
}
}
```
### Enable debug logging for a single command
```bash theme={null}
partio --log-level debug status
```
### Temporarily disable partio
```bash theme={null}
PARTIO_ENABLED=false git commit -m "Skip partio for this commit"
```
### Per-machine overrides
Use `.partio/settings.local.json` for settings that shouldn't be committed (this file is automatically git-ignored):
```json title=".partio/settings.local.json" theme={null}
{
"log_level": "debug"
}
```
# Installation
Source: https://docs.partio.io/cli/installation
Install partio on macOS, Linux, or from source
# Installation
## Package managers
```bash theme={null}
brew install partio-io/tap/partio
```
```bash theme={null}
brew install partio-io/tap/partio
```
Homebrew on Linux works the same as macOS.
Requires Go 1.25 or later:
```bash theme={null}
go install github.com/partio-io/cli/cmd/partio@latest
```
Make sure `$GOPATH/bin` (usually `~/go/bin`) is in your `PATH`.
```bash theme={null}
git clone https://github.com/partio-io/cli.git
cd cli
go build -o partio ./cmd/partio
sudo mv partio /usr/local/bin/
```
## Verify installation
```bash theme={null}
partio version
```
You should see:
```
partio v0.1.0
```
## Shell completions
partio is built with [Cobra](https://github.com/spf13/cobra) and supports shell completions:
```bash theme={null}
partio completion bash > /etc/bash_completion.d/partio
```
```bash theme={null}
partio completion zsh > "${fpath[1]}/_partio"
```
```bash theme={null}
partio completion fish > ~/.config/fish/completions/partio.fish
```
## Requirements
* **Git** 2.25 or later (for orphan branch support)
* **macOS** or **Linux** (Windows support is planned)
## Upgrading
```bash theme={null}
brew upgrade partio
```
```bash theme={null}
go install github.com/partio-io/cli/cmd/partio@latest
```
After upgrading, run `partio doctor` in your repositories to verify everything is healthy.
## Uninstalling
1. Disable partio in each repository:
```bash theme={null}
partio disable --remove-data
```
2. Remove the binary:
```bash theme={null}
brew uninstall partio
```
```bash theme={null}
rm $(which partio)
```
3. Optionally remove the global config:
```bash theme={null}
rm -rf ~/.config/partio
```
# Overview
Source: https://docs.partio.io/cli/overview
See partio in action
# CLI Overview
partio hooks into Git to capture AI agent sessions alongside your commits. Here's what it looks like in practice:
![partio demo]()
When you commit, partio detects the active AI agent session (Claude Code or Codex), captures the full conversation transcript, and stores it as a checkpoint on an orphan branch — all without leaving your terminal.
Install via Homebrew or Go
Full CLI reference
# Strategies
Source: https://docs.partio.io/cli/strategies
How partio decides when to capture checkpoints
# Strategies
A strategy defines when and how partio creates checkpoints. The strategy is configured via the `strategy` field in your settings.
## `manual-commit`
**This is the default and recommended strategy.**
Captures a checkpoint every time you run `git commit` while an AI agent is detected as active.
### How it works
1. **Pre-commit hook** runs before your commit:
* Checks if an AI agent process (e.g., Claude Code) is running
* If found, locates the active session file
* Saves state to `.partio/state/pre-commit.json`
2. **Post-commit hook** runs after your commit:
* Reads the saved pre-commit state
* If an agent was active, captures the session data
* Writes the checkpoint to the orphan branch
* Amends the commit with attribution trailers
3. **Pre-push hook** runs before `git push`:
* Pushes `partio/checkpoints/v1` to the remote
### When checkpoints are NOT created
* No AI agent process is detected
* partio is disabled (`enabled: false` or `PARTIO_ENABLED=false`)
* The `.partio/` directory doesn't exist
* The pre-commit state file is missing (e.g., hooks weren't installed)
### Configuration
```json title=".partio/settings.json" theme={null}
{
"strategy": "manual-commit",
"strategy_options": {
"push_sessions": true
}
}
```
| Option | Default | Description |
| --------------- | ------- | -------------------------------------------------- |
| `push_sessions` | `true` | Automatically push checkpoint branch on `git push` |
### Non-blocking behavior
Both hooks are designed to never block your Git operations:
* If agent detection fails, the commit proceeds normally (no checkpoint)
* If checkpoint writing fails, a warning is logged but the commit is preserved
* If pushing the checkpoint branch fails, a warning is logged but your push completes
# Core Concepts
Source: https://docs.partio.io/core-concepts
Understand sessions, checkpoints, strategies, and how partio stores data
# 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
* **Diff** — the unified diff for the commit
* **Initial prompt** — the first prompt that started the session
* **Plan file** — the agent's plan file, if one exists (e.g., Claude Code plans)
* **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) |
| `plan_slug` | Slug identifying the agent's plan file, if any |
| `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)
└── / (first 2 hex chars of ID)
└── / (remaining 10 hex chars)
├── metadata.json
└── 0/
├── content_hash.txt
├── context.md
├── diff.patch
├── full.jsonl
├── metadata.json
├── plan.md
└── 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, amends attribution trailers, and writes the checkpoint |
| `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 `.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](https://git-scm.com/docs/git-interpret-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](/cli/strategies) for more details.
## Git Worktrees
partio fully supports [git worktrees](https://git-scm.com/docs/git-worktree). 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 checks the repository root and its immediate parent directory when looking for the active Claude Code session. When both have matching session directories, the one with the most recently modified session file is used.
* **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:
```bash theme={null}
cd my-project-feature-branch # a worktree
partio enable
# Hooks are now active in every worktree for this repo
```
# Features
Source: https://docs.partio.io/extension/features
Checkpoint panels, commit badges, and how the extension discovers checkpoint data
# Features
The extension has two main features: a **checkpoint panel** injected on commit and PR pages, and **commit list badges** that annotate commits with checkpoint data.
## Checkpoint Panel
When the extension finds a checkpoint for the current page, it injects a collapsible panel into the GitHub UI.
![Switching between Transcript and Plan tabs in the checkpoint panel]()
### Header
The panel header is always visible and shows:
* **Partio logo** and title
* **Agent name** — a colored badge showing which agent created the checkpoint (e.g., "claude-code")
* **AI authorship** — the percentage of the commit authored by the AI agent (e.g., "75% AI-authored"), shown when greater than 0%
* **View in Partio** — link to the checkpoint detail page on [app.partio.io](https://app.partio.io)
* **Collapse button** — click the header to expand or collapse the panel body
### Transcript Tab
The transcript tab shows the agent session as a chat-style message list:
* **Messages** are grouped by role (`user` or `assistant`), each in a bordered card
* **Assistant messages** have an accent-colored left border for visual distinction
* **Tool badges** appear inline showing which tools the agent called (e.g., `bash`, `Read`, `Grep`, `Edit`)
* **Long messages** (over 1,000 characters) are truncated with a **Show more** button that toggles between the truncated and full view
* **Resume session** — at the bottom, a copyable command (`partio resume [checkpointId]`) lets you resume the Claude Code session from your terminal
The extension processes raw JSONL session data, deduplicates streaming chunks, strips internal system tags, and renders markdown in message content.
### Plan Tab
The plan tab displays the agent's plan as rendered markdown:
* Full markdown support including headings, lists, code blocks, and inline code
* **Copy Plan** — copies the raw markdown to your clipboard
* **Download** — saves the plan as a `plan.md` file
The plan tab only appears if the checkpoint includes plan data.
## Commit List Badges
![Purple Partio badges on a GitHub commit list]()
On any GitHub page that lists commits, the extension scans for commit links and annotates them with small purple Partio icons when a matching checkpoint exists.
* Badges appear after the commit link text
* **Hover** to see a tooltip with the agent name and AI authorship percentage
* **Click** the badge to open the checkpoint detail page on app.partio.io
The extension fetches all checkpoints for the repository and matches them against commit SHAs on the page, including shortened SHA prefixes.
## Checkpoint Discovery
The extension uses a multi-strategy approach to find the right checkpoint for a page:
### Strategy 1: Commit Trailers
The extension scans the commit message DOM for a `Partio-Checkpoint` trailer:
```
Partio-Checkpoint: a3f8c2d14e9b
```
If found, the checkpoint ID is used directly. This is the fastest path since it requires no API calls beyond fetching the checkpoint data.
### Strategy 2: SHA Matching
When no trailer is present, the extension gathers candidate SHAs from:
* The current commit SHA
* Parent commits
* Merged commits (for merge commits)
* Associated PR commits
It then checks each candidate against known checkpoints. Both exact matches and prefix matches (for shortened SHAs) are supported.
### Strategy 3: Branch Matching
For squash merges and other cases where the original commit SHA is lost, the extension falls back to branch name matching:
* PR head branch names
* Associated branch references
This ensures checkpoints are still discoverable even when the original commits are squashed into a new SHA.
### Discovery Order
The extension evaluates strategies in order — trailer first, then SHA matching, then branch matching — and uses the first checkpoint found. If no strategy produces a match, no panel is shown.
# Extension Overview
Source: https://docs.partio.io/extension/overview
The partio Chrome extension for viewing AI agent sessions directly on GitHub
# Extension Overview
The partio Chrome extension surfaces checkpoint data — agent transcripts, plans, and authorship stats — directly on GitHub commit and pull request pages. Instead of switching to the dashboard, you can review what an AI agent did right where you already review code.
![Checkpoint panel expanding on a GitHub commit page]()
## Installation
Install the extension from the [Chrome Web Store](https://chromewebstore.google.com) and it will be ready to use immediately after connecting your account.
1. Clone the extension repository and build it:
```bash theme={null}
npm install
npm run build
```
2. Open `chrome://extensions` in Chrome
3. Enable **Developer mode** (top right)
4. Click **Load unpacked** and select the `dist/` directory
## Connecting to Partio
The extension needs two things to work: a session with [app.partio.io](https://app.partio.io) and a GitHub token with `repo` scope.
1. Click the Partio icon in your browser toolbar to open the popup
2. Click **Connect** — if you're already signed in to app.partio.io, it connects automatically
3. If you're not signed in, a new tab opens to `app.partio.io/login` — sign in with GitHub, then return to the popup
Once connected, the popup shows your GitHub username and a **Disconnect** button. The extension auto-refreshes your session when cookies change, so you stay connected across browser restarts.
![Extension popup showing connect and disconnect states]()
If you explicitly disconnect via the popup, the extension won't auto-reconnect even if you're still signed in to app.partio.io. Click **Connect** again to re-enable.
## Supported GitHub Pages
The extension activates on four types of GitHub pages:
| Page type | URL pattern | What the extension does |
| ------------------ | -------------------------------- | ------------------------------------------------- |
| **Commit** | `/owner/repo/commit/sha` | Shows checkpoint panel with transcript and plan |
| **Pull request** | `/owner/repo/pull/N` | Shows checkpoint panel for the PR's head commit |
| **PR commit view** | `/owner/repo/pull/N/commits/sha` | Shows checkpoint panel for the specific commit |
| **Commit lists** | Any page with commit links | Adds badge icons to commits that have checkpoints |
The extension listens for GitHub's SPA navigation events (`turbo:load`, `pjax:end`), so panels and badges update as you navigate without full page reloads.
## How It Works
The partio CLI stores checkpoint data on a `partio/checkpoints/v1` orphan branch in your repository. The extension reads this branch via the GitHub API to fetch metadata, session transcripts, and plans — then renders them inline on the page.
No data leaves your browser except API calls to GitHub (to read checkpoint data) and app.partio.io (for authentication). See [Troubleshooting](/extension/troubleshooting) for privacy details.
## Next Steps
* [Features](/extension/features) — detailed walkthrough of the checkpoint panel, commit badges, and discovery logic
* [Troubleshooting](/extension/troubleshooting) — common issues and how to resolve them
# Troubleshooting
Source: https://docs.partio.io/extension/troubleshooting
Common issues with the partio Chrome extension and how to resolve them
# Troubleshooting
## Panel Not Appearing
### No checkpoint exists for this commit
The extension only shows a panel when it finds a matching checkpoint. If the commit was made without partio enabled, or the checkpoint hasn't been pushed yet, no panel will appear.
* Run `partio status` in the repository to confirm checkpoints are being created
* Check that the `partio/checkpoints/v1` orphan branch has been pushed to GitHub
### Not authenticated
The extension requires a valid connection to app.partio.io and a GitHub token with `repo` scope.
1. Click the Partio icon in the toolbar — if it shows "Not connected", click **Connect**
2. If connecting fails, sign in to [app.partio.io](https://app.partio.io) first, then try again
### Page type not supported
The extension only activates on commit pages, pull request pages, and pages with commit links. Other GitHub pages (issues, discussions, repository root) are not supported.
## Authentication Problems
### Session not detected
The extension looks for an AuthJS session cookie from `app.partio.io`. If it can't find one:
1. Open [app.partio.io](https://app.partio.io) and verify you're signed in
2. Click the Partio icon and click **Connect**
3. If you still can't connect, try signing out of app.partio.io and signing back in
### Token expired
GitHub tokens can expire or be revoked. If the extension stops showing data:
1. Click the Partio icon — if it shows your username, click **Disconnect**
2. Click **Connect** to re-authenticate and get a fresh token
### Auto-reconnect not working
If you explicitly disconnected via the popup, the extension sets a flag that prevents auto-reconnection. Click **Connect** to clear this flag and re-enable automatic session syncing.
## Badges Not Showing
### No checkpoints in repository
Commit list badges only appear for commits that have matching checkpoints. If no checkpoints exist in the repository, no badges will appear.
### GitHub SPA navigation
GitHub uses client-side navigation (Turbo/PJAX). The extension listens for these events, but in rare cases the event may not fire. A full page reload (`Cmd+Shift+R` / `Ctrl+Shift+R`) will re-trigger badge injection.
## Data and Privacy
### Where is data stored?
| Data | Location |
| ------------------------ | -------------------------------------------------------------- |
| GitHub token | `chrome.storage.local` (browser-managed encryption at rest) |
| Username and auth status | `chrome.storage.local` |
| Checkpoint cache | `chrome.storage.local` (5-minute TTL, auto-expires) |
| Checkpoint data | Read from the `partio/checkpoints/v1` branch on GitHub via API |
### What network requests does the extension make?
The extension only communicates with two services:
* **GitHub API** (`api.github.com`) — reads checkpoint data from the orphan branch using your token
* **app.partio.io** — checks your authentication session
### Does the extension collect analytics?
No. The extension does not send telemetry, usage data, or any information to third parties.
# Claude Code
Source: https://docs.partio.io/integrations/claude-code
How partio integrates with Claude Code
# Claude Code Integration
partio has first-class support for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's AI coding assistant. When you use Claude Code in a partio-enabled repository, sessions are automatically captured alongside your commits.
partio also supports [Codex](/integrations/codex). By default it auto-detects whichever agent is running — see [Choosing the agent](/cli/configuration#choosing-the-agent).
## Detection
partio detects Claude Code by checking for a running Claude Code process. When the pre-commit hook fires, it:
1. Checks if a Claude Code process is active on the system
2. Locates the latest session file in the repository
If both conditions are met, the session is marked as active and will be captured on commit.
## What gets captured
For each commit made while Claude Code is active, partio captures:
| File | Contents |
| --------------- | -------------------------------------------------------- |
| `full.jsonl` | The complete JSONL transcript of the Claude Code session |
| `context.md` | A summary of the session context |
| `diff.patch` | The unified diff for the commit |
| `prompt.txt` | The initial prompt that started the session |
| `plan.md` | The Claude Code plan file, if the session used a plan |
| `metadata.json` | Session metadata (agent, token count, duration) |
### Session metadata
```json theme={null}
{
"agent": "claude-code",
"total_tokens": 14230,
"duration": "8m42.5s"
}
```
### Plan capture
When a Claude Code session uses a [plan](https://docs.anthropic.com/en/docs/claude-code/plan-mode), partio extracts the plan slug from the session transcript and reads the corresponding plan file from `~/.claude/plans/.md`. The plan is stored as `plan.md` in the checkpoint, providing the high-level intent alongside the transcript and diff.
If no plan was used or the plan file is missing, `plan.md` is empty.
## JSONL format
The `full.jsonl` file contains the raw Claude Code session transcript. Each line is a JSON object representing one turn in the conversation. This is the same format used by Claude Code's internal session logging.
## Attribution
partio calculates what percentage of the commit diff was produced by the AI agent. This is added as a Git trailer:
```
Partio-Attribution: 87% agent
```
When calculation fails (e.g., no diff available), it defaults to `100%` attribution if an agent was active.
## Commit trailers
After each checkpoint, your commit message is amended with:
```
Your commit message here
Partio-Checkpoint: a3f8c2d14e9b
Partio-Attribution: 87% agent
```
## Troubleshooting
### Checkpoints not being created
1. **Run `partio doctor`** to check installation health
2. **Verify Claude Code is running** when you commit — partio only captures when it detects an active process
3. **Check log output** with `partio --log-level debug status`
4. **Verify hooks are installed** — look for `# Installed by partio` in `.git/hooks/post-commit`
### Session file not found
Claude Code stores session files in your home directory. If partio can't find the session:
* Ensure Claude Code has been used in the current repository at least once
* Check that the session file hasn't been cleaned up before the commit
### Attribution shows 100% unexpectedly
If attribution calculation fails, partio defaults to 100% when an agent is active. This can happen if:
* The commit has no parent (initial commit)
* The diff cannot be computed
### Hooks conflict with existing hooks
partio backs up existing hooks as `.partio-backup` and chains to them after its own logic. If you're experiencing conflicts:
1. Check `.git/hooks/` for backup files
2. Run `partio disable` then `partio enable` to reinstall
3. Verify the hook scripts contain the `# Installed by partio` marker
# Codex
Source: https://docs.partio.io/integrations/codex
How partio integrates with OpenAI Codex CLI
# Codex Integration
partio supports [OpenAI Codex CLI](https://openai.com/codex) as a first-class agent alongside Claude Code. When you use Codex in a partio-enabled repository, sessions are captured alongside your commits — the same way they are for Claude Code.
## Detection
partio detects Codex by checking for a running `codex` process. When the pre-commit hook fires, it:
1. Checks if a Codex process is active on the system (`pgrep -f codex`)
2. Locates the latest session file under `~/.codex/sessions/`, matching the session's working directory against the current repository root
If both conditions are met, the session is marked as active and captured on commit.
## Selecting the agent
By default the `agent` setting is empty, and partio **auto-detects** whichever supported agent is currently running (Claude Code or Codex). You usually don't need to configure anything.
To pin partio to Codex explicitly — useful if you run multiple agents — set the `agent` field or the `PARTIO_AGENT` environment variable:
```json title=".partio/settings.json" theme={null}
{
"agent": "codex"
}
```
```bash theme={null}
PARTIO_AGENT=codex git commit -m "..."
```
See [Configuration → Choosing the agent](/cli/configuration#choosing-the-agent) for details.
## What gets captured
For each commit made while Codex is active, partio captures the same checkpoint data as any other agent:
| File | Contents |
| --------------- | -------------------------------------------------- |
| `full.jsonl` | The complete JSONL transcript of the Codex session |
| `context.md` | A summary of the session context |
| `diff.patch` | The unified diff for the commit |
| `prompt.txt` | The initial prompt that started the session |
| `metadata.json` | Session metadata (agent, token count, duration) |
### Session metadata
```json theme={null}
{
"agent": "codex",
"total_tokens": 11840,
"duration": "6m10.2s"
}
```
Plan capture (`plan.md`) is specific to Claude Code's plan mode and is not produced for Codex sessions.
## Attribution & trailers
Attribution and commit trailers work identically for every agent. After each checkpoint, your commit is amended with:
```
Your commit message here
Partio-Checkpoint: a3f8c2d14e9b
Partio-Attribution: 82% agent
```
## Troubleshooting
### Checkpoints not being created
1. **Run `partio doctor`** to check installation health
2. **Verify Codex is running** when you commit — partio only captures when it detects an active process
3. **Check log output** with `partio --log-level debug status` (the `Agent:` line shows which agent partio resolved)
4. **Verify hooks are installed** — look for `# Installed by partio` in `.git/hooks/post-commit`
### Session file not found
Codex stores session files under `~/.codex/sessions/`. If partio can't find the session:
* Ensure Codex has been used in the current repository at least once
* Check that the session file hasn't been cleaned up before the commit
# Introduction
Source: https://docs.partio.io/introduction
Capture the why behind your code changes
# Welcome to partio
**partio** is an open-source CLI that captures AI agent sessions alongside Git commits. It hooks into your existing Git workflow to automatically preserve the reasoning, prompts, and full conversation transcripts that produced each code change.
## The Problem
Git tracks *what* changed. But when AI agents write code, the most valuable context — the reasoning, the prompts, the back-and-forth — lives in ephemeral terminal sessions that vanish when you close your editor.
Months later, you're staring at a function and asking: *why was it written this way?*
## The Solution
partio captures the *why* automatically:
* **Zero friction** — one command to enable, then forget about it
* **Git native** — checkpoint data lives on an orphan branch in your repo
* **Agent detection** — automatically detects Claude Code sessions
* **Attribution** — tracks what percentage of each commit was AI-generated
* **Time travel** — rewind to any checkpoint and explore the full AI conversation
## How it works
1. Run `partio enable` in any Git repository
2. Work with your AI agent as usual
3. When you commit, partio detects the active session and captures everything
4. Checkpoint data pushes alongside your code
Get up and running in under a minute
Understand sessions, checkpoints, and strategies
Full reference for all partio commands
Explore your checkpoints in the web dashboard
How partio works with Claude Code
# Quick Start
Source: https://docs.partio.io/quickstart
Get up and running with partio in under a minute
# Quick Start
## Install
```bash theme={null}
brew install partio-io/tap/partio
```
```bash theme={null}
go install github.com/partio-io/cli/cmd/partio@latest
```
```bash theme={null}
git clone https://github.com/partio-io/cli.git
cd cli
go build -o partio ./cmd/partio
sudo mv partio /usr/local/bin/
```
Verify the installation:
```bash theme={null}
partio version
# partio v0.1.0
```
## Enable in a repository
Navigate to any Git repository and enable partio:
```bash theme={null}
cd your-project
partio enable
```
You'll see:
```
partio enabled successfully!
- Ensured .partio/ config directory exists
- Installed git hooks (pre-commit, post-commit, pre-push)
- Ready to capture AI sessions on commit
```
That's it. No config files to write, no environment variables to set.
## Your first checkpoint
1. Start an AI coding session (e.g., open Claude Code)
2. Make some changes to your code
3. Commit as you normally would:
```bash theme={null}
git commit -m "Add user authentication"
```
partio automatically:
* Detects the running AI agent
* Captures the session transcript, prompts, and context
* Stores everything on the `partio/checkpoints/v1` branch
* Appends attribution trailers to your commit message
Your commit message will include:
```
Add user authentication
Partio-Checkpoint: a3f8c2d14e9b
Partio-Attribution: 87% agent
```
## Explore checkpoints
List all captured checkpoints:
```bash theme={null}
partio rewind --list
```
```
Checkpoints:
a3f8c2d14e9b branch=main agent=87% created=2026-02-17T14:30:00Z
```
Rewind to explore a specific checkpoint:
```bash theme={null}
partio rewind --to a3f8c2d14e9b
```
This creates a new branch at that checkpoint so you can explore the code and AI session in context.
## Verify everything is healthy
```bash theme={null}
partio doctor
```
```
[OK] .partio/ directory exists
[OK] pre-commit hook installed
[OK] post-commit hook installed
[OK] pre-push hook installed
[OK] checkpoint branch exists
[OK] partio binary found (you're running it!)
All checks passed!
```
## Next steps
* Learn about [Core Concepts](/core-concepts) — sessions, checkpoints, and strategies
* See the full [CLI Reference](/cli/commands)
* Set up the [Claude Code integration](/integrations/claude-code)