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:

{
  "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	`<repo>/.partio/settings.json`	Repo-level config (committed)
4	`<repo>/.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 and 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:

.partio/settings.json

{
  "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.

# 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):

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].
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:

.partio/settings.json

{
  "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:

.partio/settings.json

{
  "strategy_options": {
    "push_sessions": false
  }
}

Enable debug logging for a single command

partio --log-level debug status

Temporarily disable partio

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

.partio/settings.local.json

{
  "log_level": "debug"
}

Getting Started

CLI Reference

App

Extension

Integrations

Configuration

Configuration

Config fields

Default settings.json

File locations

Environment variables

Choosing the agent

Commit linking

Secret redaction

Examples

Disable auto-push of sessions

Enable debug logging for a single command

Temporarily disable partio

Per-machine overrides

​Configuration

​Config fields

​Default settings.json

​File locations

​Environment variables

​Choosing the agent

​Commit linking

​Secret redaction

​Examples

​Disable auto-push of sessions

​Enable debug logging for a single command

​Temporarily disable partio

​Per-machine overrides

Configuration

Config fields

Default settings.json

File locations

Environment variables

Choosing the agent

Commit linking

Secret redaction

Examples

Disable auto-push of sessions

Enable debug logging for a single command

Temporarily disable partio

Per-machine overrides