Skip to content

Configuration

Aesop reads ~/.config/aesop-agentic/config.toml by default. Set AESOP_CONFIG or pass the global option before the command:

aesop --config ~/Aesop/config.toml doctor --json

Archive and Interface Settings

repo_root = "~/Aesop"
data_root = "~/Aesop/data"
state_root = "~/.local/state/aesop-agentic"
interval_hours = 8
check_interval_seconds = 900
notify = true
parse_after_collect = true
ui_mode = "browser"
terminal_app = "Terminal"

[sources]
enabled = ["codex", "claude_code", "chatgpt"]
# Optional additional roots supplement the built-in locations.
pi_session_roots = ["~/Agent Sessions/Pi"]
orca_roots = ["~/Library/Application Support/Orca Development"]

Top-level settings must precede [sources] and [[destinations]] tables. Use one [sources] table and preserve the full list of sources you want enabled when editing it.

Setting Meaning
repo_root Workspace for relative data paths and automatic imports/<source>/ inboxes. It need not be a Git repository.
data_root Raw artifacts, rendered documents, and manifests. The older collection_root spelling remains supported.
state_root Local runtime state, including browser profiles; keep separate from backups.
interval_hours Minimum hours between scheduled collection attempts; default 8.
check_interval_seconds LaunchAgent check interval; default 900, minimum 60.
parse_after_collect Render supported artifacts during the full run pipeline; default true.
notify Allow native notifications; authorization is requested separately.
ui_mode desktop, browser, or terminal. Setup currently defaults to desktop; choose browser for the PyPI-only installation.
terminal_app Terminal, iTerm2, or Warp for launches into another terminal.

Paths expand ~ and environment variables. Relative paths resolve against repo_root. The background service does not inherit your interactive shell environment; prefer explicit paths.

Backup Destinations

No destinations means no backup copies. Setup adds an iCloud destination; review it before your first full run.

[[destinations]]
name = "external"
type = "local"
path = "/Volumes/Backup/Aesop"
required = true
timeout_seconds = 1800
stall_timeout_seconds = 300

[[destinations]]
name = "remote"
type = "rclone"
remote = "myremote:Aesop/data"
timeout_seconds = 1800

Install and authenticate rclone separately. Its configuration is not a conversation archive and should not be copied into data_root.

[[destinations]]
name = "private-lfs"
type = "git_lfs"
path = "~/Backups/Aesop-LFS"
remote = "origin"
branch = "main"

Prepare the destination repository, remote, Git LFS installation, and access separately. Use a private repository for personal archives.

Destinations run in separate workers with bounded transfer and verification time. A worker stops after timeout_seconds overall or stall_timeout_seconds without reported progress (local mirrors report every file; rclone and Git LFS send a heartbeat). Only whole-destination failures are retried, at most twice; timeouts and partial mirrors are recorded and resumed on the next run. Local mirrors keep a small record in state_root/mirrors/ so unchanged files, including iCloud placeholders, are checked without reading them. Use dedicated mirror locations and review permissions before copying sensitive transcripts.