agented

agented (binary: ae)

ae is a stateful editor controlled by command-line verbs. State persists across sessions in a SQLite-backed workspace (.agented/state.db). Every edit is versioned in an undo tree — you can branch, jump to any past state, and never lose work.

ae not on PATH? npx -y agented <verb> ... runs the identical binary — the npm launcher downloads the platform build from GitHub releases on first use (sha256-verified) and caches it, so later calls are instant and offline. Every command in this document works verbatim with npx -y agented in place of ae. Prefer a real install for daily use (brew install frane/tap/agented or npm i -g agented).

Use this tool when

• You need to edit one or more files in a repo across multiple steps and want a durable history.
• You want to leave notes for your future self or other agents (annotations) attached to specific files.
• You want safe multi-file refactors with all-or-nothing semantics (transactions).

Don't use this tool for

• Reading repo overview / architecture (use plain cat/grep).
• Single one-shot edits where you don't care about history (use the platform's built-in editor).
• Anything that isn't text (no binary file support).

How the editor enforces correctness for you

Every read returns a state_token. Pass it to your next write with --expect. If the file changed under you, the write is rejected (exit code 3) and the response includes the new content and the new token. Retry with the new token.

You don't need to "view before write" — the editor will tell you if your assumption is stale. You don't need to "branches before undo" — undo's error includes the branches if there's ambiguity. You don't need to "status before edit" — every operation's response carries the state you'd want to check.

The default is concurrency.require_expect: warn: writes without --expect succeed and emit a stderr warning. For multi-agent setups, set require_expect: writes in .agented/config.json to enforce strict pre-write checks. In either mode, an actual conflict (a stale --expect value) is rejected with exit 3 and the recovery payload — the tree never silently loses work.