ACD

ACD protects meaningful working-tree changes as durable local checkpoints, then groups and publishes them as ordinary local Git commits.

Capture every meaningful change durably first. Group and publish commits second. Make protection status and restoration understandable without Git expertise.

ACD is a static Go binary for macOS and Linux on amd64 and arm64. It never pushes, never rewrites normal history, and needs no API key for its default path.

Get protected

From the Git repository you want to protect:

acd setup

The first setup inspects the machine and repository, prints an exact plan, asks once, and applies the plan transactionally. It configures one user-level supervisor, enables the current repository, merges detected optional integrations, and runs an isolated checkpoint/publish/restore self-test. Later compatible upgrades use a bounded binary-and-hooks transaction without rescanning or migrating every repository. On failure either path restores every touched file and prior process/service state.

On macOS, the first ACD mutation starts one shared supervisor for the current user. Other terminals and agent applications reuse its owner-only socket after a same-user peer credential check, so switching applications does not require setup. The process inherits the permissions of the application that started it and does not require Full Disk Access. After logout or restart, the first acd on or supported agent hook starts it again. Linux uses the persistent user systemd service.

After the compatibility contract is installed, a newer compatible ACD build upgrades the managed runtime at a safe checkpoint boundary. ACD also applies state migrations that the new runtime explicitly marks as safe. Breaking protocol, registry, or state changes still require the full reviewed acd setup migration. The first release with this contract may therefore need one final full setup.

Preview without writes or supervisor/service actions:

acd setup --dry-run

Noninteractive setup requires an exact reviewed plan when an installation or v19 repository already exists:

acd setup --dry-run --json
acd setup --yes --non-interactive --expect-plan sha256:...

Fresh installations use the deterministic provider with Intent/Fast, structural verification, repair disabled, and diff egress disabled. Existing repositories retain their effective provider, strategy, preset, verification, and repair settings during the one-shot v19 to v20 cutover.

Daily use

Bare acd and acd status are equivalent and read-only:

State: waiting
ACD protection: on
Current changes protected: yes
Published to Git: no
Action needed: no
Status: Current changes are checkpointed; publication is waiting for a safe boundary.
Next: No action needed.

The five product states are:

State	Meaning
off	This repository is intentionally disabled or not configured.
protected	The latest complete observation is checkpointed and nothing waits for publication.
waiting	Checkpoints are safe; grouping, verification, Git state, or retry is delaying publication.
publishing	A selected checkpoint group is being published as a local Git commit.
needs_action	Protection is incomplete or a safely recoverable condition needs user action.

Current changes protected is reported separately from the overall state. It may remain yes while publication is waiting, publishing, or blocked by an unrelated repair.

Commands

Root help lists ten everyday commands:

Command	Purpose
acd setup	Install or upgrade transactionally and protect the current repository.
acd status	Answer whether changes are enabled, protected, published, and actionable.
acd on	Enable protection, replace the managed worker, and verify a new checkpoint.
acd off	Complete a final checkpoint, disable protection, and wait for the worker to stop.
acd list	Show enabled repositories with protection and publication state.
acd commit-all	Checkpoint now and drain the bounded publication target.
acd history	List retained checkpoints and their Git publication state.
acd restore ID	Preview a full-checkpoint restore; add --yes to apply it.
acd doctor	Explain installation or protection problems and the exact next command.
acd uninstall	Remove managed components while preserving protected data by default.

It also links directly to common tasks:

acd commit-all --dry-run
acd history rewrite --help
acd config edit
acd repo --help
acd support --help

Advanced commands are callable under hidden namespaces:

acd config get|set|edit|reset|credentials
acd support diagnose|logs|repair|recover|prompt|bundle
acd repo list|remove|gc
acd history activity|explain|rewrite

Old command names remain hidden compatibility aliases for two releases. A manual use prints a warning. Optional integrations use hidden local hint APIs without terminal noise. All aliases invoke the checkpoint-first runtime.

acd commit-all does not squash the worktree into one commit. It freezes the checkpoint-backed event target and lets the configured event or Intent publication strategy create the same reviewable, atomic local commits it would create during normal operation. Edits made after the barrier are left for the next publication pass.

See the command reference for flags, JSON, exit codes, and the compatibility map.

How protection works

Filesystem watching accelerates detection and a complete poll remains the universal safety path. Optional tool integrations only provide semantic and session-boundary hints; removing every integration does not reduce capture coverage.

Each completed checkpoint is a rootless Git commit containing the entire eligible protected worktree and is retained under:

refs/acd/checkpoints/v1/<worktree-id>/<checkpoint-id>

The ref keeps its Git objects reachable through normal garbage collection. Checkpoint commits are not parented to HEAD or to one another, do not appear as user branches, and never replace ordinary Git history.

Protection continues during provider failures, verification failures, detached HEAD, conflicts, branch transitions, and in-progress Git operations. Publication waits until Git is safe. A checkpoint becomes published only when all of its captured changes map to completed ordinary local commits.

ACD excludes Git-ignored paths and configured sensitive paths. An unreadable, unstable, or oversized eligible path makes protection incomplete; ACD never silently claims the repository is protected after skipping eligible content.

Default retention keeps unpublished checkpoints, restore preimages, unresolved operations, and the newest checkpoint indefinitely. Published checkpoints are retained for 30 days and at least the newest 100, with a soft 5 GiB per-worktree content budget. A budget never silently discards unpublished protection.

See protection and publication for the durable protocol and failure behavior.

Restore

Restore always previews first:

acd history
acd restore cp-...
acd restore cp-... --yes

Before changing files, ACD checkpoints the current state. It restores the selected checkpoint into the working tree as a new change, leaves HEAD and the index byte-for-byte unchanged, checkpoints the result, and returns the pre-restore checkpoint as the undo target.

Restore refuses conflicts, in-progress merge/rebase/cherry-pick/bisect states, and any staged-path overlap. Detached HEAD is allowed because restore does not move it. If a post-restore checkpoint is interrupted, run the previewed repair:

acd support repair
acd support repair --yes

See user workflows for recovery and support steps.

Configuration

Inside a worktree, public configuration defaults to repository scope. Outside a worktree it defaults to global scope. Make scope explicit with --scope repo|profile|global.

acd config get
acd config set commit.preset fast
acd config edit
acd config credentials

Resolution order is:

invocation override
internal experiment
repository
profile
global
environment
preset
default

Credentials stay in the protected existing credential store. The deterministic default requires none. Diff egress remains off unless explicitly approved.

See settings, the generated configuration reference, and AI providers.

Setup, upgrade, and uninstall safety

The v19 to v20 upgrade is one global transaction across every registered repository. A provable unpublished chain is imported as checkpoint or recovery-backed history. Any ambiguous chain aborts the complete cutover and restores all preimages. There is no legacy runtime mode, dual-read period, or automatic downgrade after commit.

Uninstall preserves repository databases, checkpoint/recovery refs, operation history, and backups by default:

acd uninstall --dry-run
acd uninstall

--purge-data inventories every target and requires a second explicit confirmation. Private refs use expected-target CAS, and repository data is staged reversibly until the uninstall transaction commits.

Platform files

Purpose	Location
Managed binary	${XDG_DATA_HOME:-$HOME/.local/share}/acd/bin/acd
Supervisor socket	${XDG_STATE_HOME:-$HOME/.local/state}/acd/run/supervisor.sock
Supervisor log	${XDG_STATE_HOME:-$HOME/.local/state}/acd/supervisor.log
Global operation history	${XDG_DATA_HOME:-$HOME/.local/share}/acd/operations.db
Repository state	<git-dir>/acd/state.db
macOS lifecycle	Session-owned; no installed service file
Linux service	~/.config/systemd/user/acd-supervisor.service

Linux requires a working systemd user manager. ACD does not ship a second Linux lifecycle implementation.

Development

make build
make lint
make test

Repository contribution and verification requirements are in CLAUDE.md. ACD is MIT licensed.