dft State Directory¶
dft stores per-user state under ~/.dft/, matching the convention used by
dbt (~/.dbt/),
Claude Code (~/.claude/), Codex CLI (~/.codex/),
the AWS CLI (~/.aws/), and kubectl (~/.kube/).
Location resolution¶
| Env var | Behavior |
|---|---|
DFT_HOME=<path> |
Unconditional override — use this in tests and CI. |
XDG_CONFIG_HOME=<path> |
Maps to <path>/dft. Honored only when explicitly set. |
| (neither set) | ~/.dft/ |
Using the helper¶
from dataface.agent_api._state import dft_home, dft_state_path
# Bare home dir (does not create the directory)
home = dft_home()
# A specific state file — creates the parent chain, returns the leaf Path
history = dft_state_path("agent_history")
session = dft_state_path("sessions", "2026", "04", "28", "abc123.jsonl")
dft_state_path requires at least one component. Call dft_home() directly if
you only need the base path.
Active and planned layout¶
| Path | Purpose |
|---|---|
~/.dft/agent_history |
Terminal agent input history (readline). |
~/.dft/sessions/<yyyy>/<mm>/<dd>/<id>.jsonl |
Agent session transcripts. |
Only paths with a real consumer are listed. Add entries here when a task drives them — do not pre-reserve speculative subpaths.