atomwrite 0.1.36

Atomic file operations CLI for LLM agents — read, write, edit, search, replace with NDJSON output
Documentation

Read in Portuguese / Leia em Portugues

atomwrite

Atomic file operations for LLM agents -- one CLI, zero corruption

docs.rs Crates.io License MSRV Downloads Rust

What Is It

  • A single Rust binary that handles every file operation an LLM agent needs
  • 45 subcommands (SSOT: clap Commands / agent-surface): read, write, edit, search, replace, hash, verify, delete, count, diff, move, copy, list, extract, calc, regex, transform, scope, batch, backup, rollback, apply, set, get, del, case, query, outline, wal-heal, wal-stats, completions, edit-loop, prune-backups, semantic-merge, sparse, recipe, stat, agent-surface, watch, codemod, semantic-search, doctor, locale, commands, scratch
  • Every write is atomic: tempfile, fsync, rename, fsync directory
  • Every response is NDJSON: one JSON object per line, machine-readable by default
  • Every file gets a BLAKE3 checksum: detect drift, verify integrity, enable optimistic locking

What Is New In v0.1.36 (2026-07-31)

  • Agent staging: scratch init + .atomwrite/scratch/ for --old-file/--new-file (jail retained; no /tmp allowlist)
  • Error NDJSON: ok: false + match_count; fuzzy similarity: null on normalized strategies
  • Global --select / --filter / --limit for agent-native NDJSON projection (no jq required)
  • Pin agents to ^0.1.36. 45 subcommands (SSOT). CLI + XDG only (no product ATOMWRITE_* knobs; no product telemetry). Agent-native stdout: --select/--fields, --filter, --limit (no global -n). Error envelopes always emit

What Is New In v0.1.35 (2026-07-19)

  • Residual A-* gaps closed (gaps.md §20): suite green without delete --yes; large overwrite default-deny (--ack-overwrite); watch always emits watch_summary; semantic-merge conflict markers default ON; monólitos include! SRP splits
  • Write large files: existing targets above XDG [write].confirm_large_bytes (default 100 KiB) require --ack-overwrite (agent one-shot; no interactive Y/N). --confirm is a legacy awareness flag; --require-large-ack is independent (no alias collision)
  • Delete: use --plan or --dry-run for plan-only; delete --confirm and delete --yes/-y are rejected (fail-closed). Run again without those flags to delete
  • Watch: final NDJSON type:watch_summary on every exit path; idle default 500 ms (--idle-exit-ms / XDG [watch].idle_exit_ms); debounce via CLI or XDG [watch].debounce_ms
  • Semantic-merge: conflict markers written by default; opt-out --no-conflict-markers
  • Local DoD (no product GitHub Actions): cargo test --lib --tests, cargo clippy --all-targets -- -D warnings, cargo check --target x86_64-pc-windows-gnu, cargo install --path . --force
  • Contract suite: cargo test --test cli_e2e_v0135
  • Pin agents to ^0.1.36 (was 0.1.35). Configuration is CLI + XDG / .atomwrite.toml only (no product ATOMWRITE_* runtime knobs; no product telemetry)

What Is New In v0.1.34 (2026-07-19)

  • CRITICAL one-shot fix: replace --fuzzy no longer hangs when replacement embeds pattern (agent “expand section” footgun — NEW may contain OLD)
  • Fuzzy multi-apply is one-pass on the original content (apply_fuzzy_one_pass); never re-scans text just inserted
  • Default max fuzzy applies = 1 when --max-replacements is omitted; hard ceiling 10_000
  • If replacement contains pattern (fixed-string), forces a single apply even with a huge --max-replacements
  • Global --timeout-secs default is 120 (was 0); pass 0 to disable; exit 124 on deadline (GNU timeout convention)
  • Fuzzy cascade polls cooperative cancel mid-file so the timeout works; resource caps: pattern 64 KiB, lev 8192 chars, windows 4096, growth max(4×, +16 MiB)
  • Docs fully aligned with the runtime contract; ADR-0054; pin agents to ^0.1.34
  • Regression: tests/cli_v0133_oneshot_fuzzy.rs (hang < 2s). Historical (at v0.1.33): 41 subcommands unchanged; no telemetry

What Was New In v0.1.30 (2026-07-13)

  • Fuzzy mandatory: only auto and aggressive; --fuzzy off rejected (exit 65) with migration note. Superseded in v0.1.35: Off = exact-only (G-010).
  • edit --replace-all with uniqueness: multi-match without it fails MATCH_AMBIGUOUS; success NDJSON includes match_count
  • Fuzzy success NDJSON includes indent_adjusted when indent delta realigns the replacement
  • Escape-drift guard blocks spurious escaped quotes; unicode_normalized strategy preserves typography
  • Match failures emit ranked best_candidate, candidates[], and diff_preview
  • search --target content|files|both with --offset / --limit; path typos get similar_paths
  • replace --progress-every reports total, rate_per_s, eta_ms
  • recipe default exclude *.bak.* (including hash step); sparse outline emits real AST outline_item under budget
  • platform.backup_method is honest reflink_or_copy (never hardlink of live file)
  • .atomwrite.toml [fuzzy] is applied to edit/replace/loop/batch; mode = "off" rejected at parse
  • semantic-merge help admits line-based three-way merge (not AST)
  • Contract suite: tests/cli_v0130_agent_contract.rs

What Was New In v0.1.29 (2026-07-13)

  • Historical (at v0.1.29): 41 subcommands (was 33): added semantic-merge, sparse, recipe, stat, agent-surface, watch, codemod, semantic-search
  • Shared fuzzy module: 9-strategy cascade for edit, replace, batch, edit-loop — replace --fuzzy auto|aggressive and --fuzzy-threshold
  • best_candidate structured diagnostics on match failure (near-miss scores no longer discarded)
  • Cargo features: core, ast, lang-*, watch, semantic, full — slim core build without AST crates (stubs exit 78)
  • Cooperative cancel during stdin read and chunked atomic write
  • semantic-merge three-way merge with shutdown checks (line-based; not AST)
  • sparse list|read budgeted monorepo surface
  • replace --progress-every and batch progress heartbeats
  • recipe list|run with real dispatch search→replace→hash (no longer plan-only stub); versioned recipes under recipes/*.yaml
  • write --durability full|fast|auto with NDJSON platform.durability; Linux renameat2 in atomic_rename with ENOSYS fallback
  • Backup uses reflink_or_copy (never hardlink of the live file)
  • stat alias for read --stat; agent-surface clap-derived inventory (anti-MCP, no MCP server)
  • watch debounce coalesce + optional --checksum + gitignore (feature watch)
  • semantic-search --index-dir offline Jaccard inverted index (feature semantic)
  • codemod campaign codemod_summary.by_rule_id
  • Local size-gate (manual): slim core release ≤ 15 MiB; measured slim ~7.7 MiB; default/full AST ~52 MB — PRD 5–8 MB applies to core only
  • Default fixed-string replace uses fuzzy=auto after exact multi-match misses (breaking vs 0.1.28 exact-only exit 1)

What Was New In v0.1.28 (2026-07-06)

  • BREAKING: delete now creates a backup by default (was opt-in) — pass --no-backup to disable; --keep-backup on delete is redundant (deletion backups are always preserved) and now surfaces a warnings field in the NDJSON envelope
  • BREAKING: move/copy overwriting an existing destination now require --force OR an explicit --backup
  • GAP-CLI-SURFACE-DRIFT closed — single BackupOpts struct (--backup, --no-backup, --keep-backup, --retention <N>) via #[command(flatten)] unifies the backup contract across 15 mutating subcommands: write, edit, edit-loop, replace, transform, scope, apply, set, del, case, batch, delete, move, copy, rollback. replace --retention and delete --no-backup now work (previously exit 2)
  • --backup and --no-backup are now mutually exclusive (exit 2) instead of the last flag silently winning
  • rollback keeps its pre-rollback safety snapshot opt-in via explicit --backup — the one documented exception to the unified default-true contract
  • GAP-CONFIG-DEFAULTS-DEAD closed — .atomwrite.toml [defaults] backup/retention keys are now effective; precedence is ATOMWRITE_BACKUP env > CLI flags > [defaults] config > built-in default (true/5)
  • edit's stdin-consuming modes (--after-line, --before-line, --range, --after-match, --before-match, --between, --multi) now fail fast with exit 65 and an actionable suggestion when stdin is a terminal, instead of hanging indefinitely
  • batch --retention <N> and batch --backup were accepted but silently ignored — both are now effective end-to-end, including the batch transactional pre-backup and the delete operation
  • 661 tests passing, zero clippy warnings, zero fmt diffs

What Was New In v0.1.27 (2026-06-24)

  • 10 bugs fixed across 3 rounds of security and scope audit
  • CRITICAL security fix: symlink-directory escape from workspace jail (BUG-SEC-001) — all write/read paths now resolve symlinks via canonicalize_existing_prefix before jail check
  • CRITICAL scope fix: scope --query comments --delete no longer destroys code on lines with inline comments (BUG-SCOPE-004)
  • scope Rust queries now match pub items for all query types (fn, struct, enum, trait, const, static, type-alias, mod, use)
  • Go scope --query var now handles type-inferred declarations (var x = 0)
  • edit-loop hardened: empty stdin and invalid JSON now return proper NDJSON error envelopes
  • edit-loop pair_results now includes old and new fields for traceability
  • 3 known limitations documented: GAP-01 (test-fn), GAP-02 (doc-comment), GAP-03 (JS export)
  • 631+ tests passing, zero clippy warnings, zero fmt diffs

What Was New In v0.1.25 (2026-06-22)

  • 49 bugs fixed across 6 rounds of e2e audit (GAP-071 through GAP-134)
  • .atomwrite.toml configuration file with hierarchy: CLI > env > local > XDG global > defaults
  • New verify subcommand for BLAKE3 checksum verification
  • Jaro-Winkler fuzzy matching + configurable --fuzzy-threshold for edit
  • copy --preserve now copies permissions AND timestamps from source
  • All --backup flows now retain .bak files on disk (copy, replace, write --require-backup)
  • scope --query comments captures block comments in addition to line comments
  • 3 critical fixes: phantom backup_path, TOML scalar misroute, case silent no-op
  • I/O errors via anyhow now emit proper NDJSON envelopes (7 subcommands fixed)
  • 631 tests passing, ~505 e2e scenarios across 6 audit rounds

What Was New In v0.1.24 (2026-06-21)

  • 52 bugs fixed in comprehensive end-to-end audit (GAP-019 through GAP-070)
  • ALL user-facing errors now emit typed JSON on stdout (20 bail! converted to AtomwriteError)
  • delete --recursive, hash --recursive, search --multiline now actually work
  • replace rejects empty pattern (was a silent data-destruction bug)
  • Backup timestamp resolution improved to milliseconds (prevents collision)
  • scope/count/transform/diff now resolve paths against --workspace
  • get/set/del values no longer doubly-quoted
  • batch --transaction properly reverts move/copy on rollback
  • 3 new ADRs (0045-0047)
  • 621 tests passing, 12 new for v0.1.24

What Was New In v0.1.23 (2026-06-19)

  • GAP-2026-015 closed — allow_hyphen_values added to 15 CLI text-accepting fields across 8 structs; values starting with - (Markdown bullets, negative numbers, YAML, diffs) no longer cause exit 2
  • GAP-2026-016 closed — backup enabled by default in 9 content-mutating structs (write, edit, edit-loop, replace, transform, apply, set, del, case); use --no-backup or ATOMWRITE_BACKUP=0 to opt out
  • GAP-2026-017 closed — shrink guard blocks writes that reduce file size by >50% when --expect-checksum is active; pass --allow-shrink to override
  • GAP-2026-018 closed — edit --old-file <PATH> --new-file <PATH> reads match/replacement content from files inside the atomwrite process, bypassing shell expansion and kernel ARG_MAX (~131 KB limit); cross-mixing validation rejects --old + --new-file (exit 65); trailing newline stripping ensures argv parity
  • 631+ tests passing (see v0.1.25 for latest count)
  • 4 new ADRs: 0041 (allow-hyphen-values), 0042 (backup-by-default), 0043 (shrink-guard), 0044 (edit-old-file-new-file)

What Was New In v0.1.22 (2026-06-17)

  • 2 new subcommands: edit-loop and prune-backups
  • edit-loop <PATH> — apply N {old, new} substitution pairs via NDJSON on stdin in 1 invocation (reduces 5x subprocess overhead for batch edits). ADR-0039
  • prune-backups [PATHS]... — manual cleanup of legacy .bak.YYYYMMDD_HHMMSS siblings with --max-age, --max-count, --dry-run (default true for safety). ADR-0040
  • 2 new NDJSON schemas: edit-loop-output.schema.json, prune-backups-output.schema.json
  • 575+ tests passing in 56+ integration suites, 0 failures, 0 clippy warnings

What Was New In v0.1.21 (2026-06-17)

  • 3 GAP-2026 closed in v0.1.21
  • --allow-sequential-drift on edit — opt-in flag for sequential edit pipelines. ADR-0038
  • --backup parity 4/4 — edit and rollback now accept --backup (were hardcoded false)
  • --keep-backup on 6 subcommands (write, edit, replace, rollback, apply, batch) — opt-in flag to preserve the backup after success
  • Default behavior change — backups are DELETED after successful --backup operations; add --keep-backup to preserve the previous behavior
  • 555+ tests passing, 1 new ADR (0038), 3 Windows cross-compile targets green

What Was New In v0.1.20 (2026-06-15)

  • 542 tests passing in 47 test suites (502 in v0.1.18 + 21 v0.1.19 + 19 v0.1.20), 0 failures, 0 clippy warnings
  • 11 GAP-2026 closed in v0.1.20
  • Intention guards — a new OPT-IN safety layer of 5 flags: --require-backup N, --confirm, --auto-rotate N, --risk-threshold LOW|MEDIUM|HIGH, and --locale en|pt-BR. They intercept destructive mutations before they touch disk. ADR-0032
  • --locale rename from --lang to disambiguate from the tree-sitter --lang used by scope and transform. The old --lang is kept as a hidden alias for one minor version. ADR-0034
  • count --by-size — list the largest files in the tree with sizes and line counts. ADR-0035
  • read --mode raw|envelope — select between byte-stream output and structured NDJSON envelope. ADR-0036
  • search --no-begin-end — disable the implicit ^ and $ anchor decoration in regex output. ADR-0037
  • scope --lang rust — explicit alias accepted for ergonomic symmetry with transform --lang. ADR-0033
  • write --preserve-timestamps — keep the source file mtime when overwriting
  • 19 ADRs in docs/decisions/ (0019-0037). 3 Windows cross-compile targets green (x86_64-gnu, i686-gnu, x86_64-msvc)

What Was New In v0.1.19 (2026-06-14)

  • G121 path resolution helper that unifies jail resolution across all write subcommands. Single source of truth for the workspace boundary check
  • Real S-expression query mode via tree-sitter — agents can now run structured AST queries against source files
  • 7 exit code documentation drifts consolidated to match the canonical list in docs/exit-codes.md (ADR-0031)
  • 21 new tests across 3 integration suites. Cross-compile targets remain green

What Was New In v0.1.17 (2026-06-13)

  • L3 startup auto-heal: atomwrite runs an autonomous wal-heal pass on startup with a 3600s threshold and 100ms budget. The pass is opt-out via --skip-startup-wal-heal (see src/cli.rs). The explicit wal-heal subcommand landed in v0.1.15; v0.1.17 wires the same logic into lib.rs::run before any subcommand dispatch

What Was New In v0.1.16 (2026-06-13)

  • L1 WalPolicy: enum WalPolicy { Auto, Always, Never } in src/wal.rs, exposed via --wal-policy flag on write and edit. Default Auto skips the WAL sidecar for trivial writes (size under 1 MiB, not Edit/Replace, directory under Git, write under 4 KiB)
  • L4 HeuristicsEngine: crate::wal::heuristics submodule with 5 composable functions (h1_ttl, h2_lru_within_cap, h3_rate_limit, h4_sentinel, h5_archive). Env vars: ATOMWRITE_WAL_KEEP_SECS, ATOMWRITE_WAL_MAX_COUNT, ATOMWRITE_WAL_RATE_LIMIT, ATOMWRITE_WAL_ARCHIVE_DAYS. Telemetry field wal_policy on WriteOutput NDJSON

What Was New In v0.1.15 (2026-06-11)

  • G117 fixed — multi-pair edit reaches fuzzy parity with the single-pair path: repeated --old/--new pairs now run the full 9-strategy fuzzy cascade per pair instead of exact-only matching
  • Per-pair reporting: success envelopes gain pairs_total and pair_results (1-based index, matched, strategy, similarity); error envelopes gain failed_pair_index, pairs_total, and pair_results — no more manual bisection of failed batches
  • New --partial flag (opt-in): applies the matching pairs and reports the rest with matched: false; zero applied pairs exits 1 (NO_MATCHES) without writing; the default stays all-or-nothing
  • Anti-masking recipe: edit ... | jaq '.edits' hides exit 65 as {"edits": null} — always use jaq -e '.edits' or check ${PIPESTATUS[0]}
  • G118 fixed — write resolves the target against the workspace before every pre-step: with a CWD outside the workspace, --append/--prepend truncated the file, --expect-checksum was silently skipped, and --line-ending auto lost detection (CWE-367 double path identity); checksum drift now exits 82 (STATE_DRIFT) and out-of-jail targets fail early with exit 126 (ADR-0027)
  • GAP 18 fixed — Windows snapshot tests are platform-stable again: the write snapshot now redacts dir_fsync as [platform_dir_fsync] (Windows reports best_effort, Unix sync_all)
  • MSRV aligned: local checks now use the documented MSRV 1.88 (the pin was previously to 1.85)
  • 461 tests passing (445 in v0.1.12 + 2 in v0.1.14 + 8 G117 + 6 G118). 43 test suites, 0 failures

What Was New In v0.1.12 (2026-06-07)

  • 6 new subcommands (v14 Tier 3): set, get, del, case, query, outline for structured config editing and AST analysis
  • G72 REAL syntax check -- atomwrite write --syntax-check invokes the real tree-sitter parser (24 languages covered) instead of the bracket-balance heuristic. Exit code 88 on the first syntax error
  • G114 WAL sidecar for crash recovery -- atomic_write writes .atomwrite.journal.<target>.atomwrite.journal.json with Started and Committed entries. recover_orphan_journals(dir) is consultative: reports orphans without auto-replay
  • 5 new error variants: LockTimeout (83), SyntaxError (88), ExdevFallbackDisabled (91), CopyBackBlake3Failed (92), OrphanJournal (93). All bilingual EN/PT-BR with actionable ErrorContext suggestions
  • Dependency added: tree-sitter-language-pack = "1.8" with download + dynamic-loading features. Parsers download on first use, install footprint stays around 5-10 MB instead of 1+ GB
  • 445 tests passing (was 320 baseline in v0.1.10, +125 new across v0.1.11 and v0.1.12). 43 integration test suites, 0 failures
  • 7 ADRs in docs/decisions/ documenting all architectural decisions for v0.1.12 (tree-sitter-language-pack choice, WAL sidecar design, query/outline kind-name only, etc.)
  • 7 new JSON Schemas in docs/schemas/ (set, get, del, case, query, outline, wal-recovery)

See docs/HOW_TO_USE.md for the full v0.1.12 quickstart and docs/MIGRATION.md for the v0.1.11 → v0.1.12 upgrade path. v0.1.11 is the previous release.

What Was New In v0.1.11 (2026-06-05)

  • signal_test::shutdown_message_on_stderr no longer fails on Windows when stderr is a pipe — libc::write(STDERR_FILENO, ...) was moved from src/main.rs to src/signal.rs and gated by #[cfg(unix)]. The Windows ctrlc path was kept as-is. Also added an EAGAIN and EINTR retry loop to make the write robust against interrupted syscalls and tight pipe buffer limits under redirected stderr
  • Race-free readiness detection in signal_test — The test now sets ATOMWRITE_READY_FILE to a path under the tempdir, and atomwrite writes its PID there as soon as install_handlers_early returns. The test polls the file with a 10 s deadline before sending SIGINT, eliminating the microsecond window where SIGINT could race with posix_spawn and arrive before the kernel's sigaction is configured
  • Idempotent signal-handler installation — install_handlers_early and install_handlers now share a single Arc<ShutdownSignal> via OnceCell. Previously each function created its own instance, and only the first instance was flipped by the signal-hook chain, so the main thread's is_shutdown() check stayed false and the banner was never written

What Was New In v0.1.10 (2026-06-05)

  • GAP 20 follow-up: signal_test::shutdown_message_on_stderr flushes the shutdown message via io::stderr().lock(). The v0.1.8 fix moved eprintln! from the signal handler to the main thread but used writeln!(io::stderr(), ...) which is fully buffered when stderr is redirected to a pipe. The fix uses the StderrLock guard that flushes on Drop

What Was New In v0.1.8 (2026-06-05)

  • signal_test::shutdown_message_on_stderr no longer fails when stderr is redirected on Linux — eprintln! removed from SIGINT/SIGTERM signal handlers per POSIX.1-2017 signal-safety(7). Message now emitted by main thread in src/main.rs after atomwrite::run returns
  • atomic::tests::create_backup_and_retention no longer fails on Windows under restricted fsync — platform::fsync_file_best_effort logs a warning and continues on ERROR_ACCESS_DENIED

What Was New In v0.1.7 (2026-06-05)

  • MSRV bumped to 1.88 — Required to allow time 0.3.47 which resolves RUSTSEC-2026-0009
  • Cross-compile Windows validated locally on macOS — Both x86_64-pc-windows-gnu and i686-pc-windows-gnu pass cargo check, cargo build, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --no-run

What Was New In v0.1.4

  • cargo install atomwrite works on Windows 10/11 — Three compilation errors in #[cfg(windows)] blocks are fixed (E0433, E0507, E0308)
  • Context-aware error suggestions — WorkspaceJail suggestion adapts when --workspace is already provided
  • Cross-compile gate — tests/cross_compile_check.rs fails on any E0433, E0308, or E0507 regression in cfg(windows) blocks

What Was New In v0.1.3

  • --preserve-timestamps flag on edit and replace to control file mtime (default: mtime is updated to reflect the change)
  • mtime_preserved field in EditOutput and ReplaceResult NDJSON responses
  • BREAKING: atomic write no longer preserves the original file mtime by default. Fixes a silent no-op in cargo build / make / cmake / gradle

Why

  • LLM agents juggle dozens of shell commands to manipulate files
  • A single power failure or crash mid-write corrupts the file
  • Parsing unstructured CLI output wastes tokens and causes hallucinations
  • Agents need checksums to detect concurrent edits but rarely compute them
  • atomwrite solves all four problems with one cargo install

Superpowers

Atomic Writes

  • Uses tempfile + fsync + rename + directory fsync on every write
  • Guarantees all-or-nothing: the file is never left half-written
  • Survives power loss, OOM kills, and SIGKILL
  • Optional G72 REAL syntax check via tree-sitter (--syntax-check flag on write)
  • Optional G114 WAL sidecar for crash recovery (.atomwrite.journal.<target>.atomwrite.journal.json)

NDJSON Output

  • stdout is ALWAYS structured JSON, one object per line
  • Every object carries a "type" discriminator field
  • Agents parse output without regex or brittle text scraping
  • Errors also emit JSON with error: true on stdout

BLAKE3 Checksums

  • Every read and write response includes a BLAKE3 hash
  • Use --expect-checksum for optimistic locking on concurrent edits
  • Detect state drift before applying changes

Parallel Search

  • Built on the ripgrep engine for file content search
  • Respects .gitignore automatically
  • Returns structured matches with file, line, column, and context

AST-Aware Transforms

  • Structural search and rewrite powered by ast-grep
  • Covers 306 programming languages
  • Refactor code by syntax tree, not fragile regex
  • New query and outline subcommands walk tree-sitter ASTs (305 languages) via tree-sitter-language-pack

Grammatical Scoping

  • Select AST categories like comments, functions, classes, and strings
  • Apply actions: delete, uppercase, lowercase, titlecase, squeeze, or replace
  • Covers Rust, Python, JavaScript, TypeScript, and Go with prepared queries
  • Use --pattern for custom AST patterns beyond the built-in queries

Batch Operations

  • Execute write, replace, delete, edit, hash, move, and copy operations from an NDJSON manifest
  • Use --transaction for all-or-nothing execution with automatic rollback
  • All operations in a batch share the same atomic guarantees

Structured Config Editing (v0.1.12)

  • set writes a value at a dotted path in TOML or JSON files (preserves comments via toml_edit)
  • get reads a value at a dotted path with auto-detected format
  • del removes a key (with --force-missing to treat missing keys as no-op success)
  • case renames identifiers across multiple files via heck (snake, camel, pascal, kebab, screaming-snake)

Quick Start

cargo install atomwrite

# Write a file atomically from stdin
echo "hello world" | atomwrite --workspace . write src/hello.txt

# Read it back with checksum
atomwrite --workspace . read src/hello.txt

# Search across a directory
atomwrite --workspace . search 'hello' src/

# Replace text with atomic writes
atomwrite --workspace . replace 'hello' 'world' src/

# Evaluate math and unit conversions
atomwrite calc "2 hours + 30 minutes to seconds"

# v0.1.12: set a value in a TOML file (preserves comments)
atomwrite --workspace . set Cargo.toml package.version 0.2.0

# v0.1.12: walk the AST of a Rust file
atomwrite --workspace . query src/main.rs --kinds

# v0.1.12: extract the outline of a Python file
atomwrite --workspace . outline src/app.py

# v0.1.12: REAL tree-sitter syntax check before committing
echo "fn broken(" | atomwrite --workspace . write --syntax-check src/x.rs

# v0.1.15: report stale sidecars and estimate reclaim
atomwrite --workspace . wal-stats

# v0.1.15: reap journals older than the threshold
atomwrite --workspace . wal-heal --threshold-secs 3600

Install (slim vs full)

  • Features: core, ast, lang-*, watch, semantic, full (default includes AST)
  • Slim (core only, ~7.7 MiB, local size-gate ≤ 15 MiB): cargo install --path . --locked --force --no-default-features --features core
  • Full/default (AST languages, ~52 MB): cargo install --path . --locked --force
  • PRD 5–8 MB target applies to the core profile, not the default AST build
  • Durability: write --durability full|fast|auto (default auto)
  • Recipe: atomwrite recipe run --name search-replace-verify --pattern OLD --replacement NEW --path src/

Installation

From crates.io

cargo install atomwrite

From source

git clone https://github.com/danilo-aguiar-br/atomwrite.git
cd atomwrite
cargo build --release

Shell Completions

# Bash
atomwrite completions bash > ~/.local/share/bash-completion/completions/atomwrite

# Zsh
atomwrite completions zsh > ~/.zfunc/_atomwrite

# Fish
atomwrite completions fish > ~/.config/fish/completions/atomwrite.fish

Usage

  • All output goes to stdout as NDJSON
  • All logs go to stderr (only with --verbose)
  • Always pass --workspace <DIR> to restrict operations to a project root
  • Use --dry-run before destructive operations
  • Use --expect-checksum <HASH> for optimistic locking
  • Use --locale <TAG> or atomwrite locale --set / locale --clear for UI locale (en, pt-BR); NDJSON codes stay English
  • Configuration is CLI flags + XDG / .atomwrite.toml only — no product ATOMWRITE_* runtime knobs (v0.1.35+)
  • Pipe stdin for write and batch commands
  • Agent-native stdout globals (all subcommands): --select / --fields (CSV top-level keys), --filter KEY=VAL (repeatable AND), --limit N (long-only — no global -n; replace owns short -n)
  • Error NDJSON always has ok: false and usually match_count — parse exit / code first; success shaping via --filter/--limit never drops error envelopes

Commands (45 total — SSOT)

Core I/O

  • read — read files with metadata, checksum, optional content
  • write — create or overwrite files atomically via stdin (large existing targets need --ack-overwrite)
  • edit — surgically edit by line number, text marker, or exact match
  • edit-loop — apply N old/new pairs from NDJSON stdin in one atomic write
  • delete — delete files with optional backup (--plan plan-only; --confirm/--yes rejected)
  • copy — copy files with checksum verification
  • move — move or rename files atomically (EXDEV copy-fallback)
  • apply — apply patches from stdin (unified diff, search/replace, full, markdown)
  • scratch — create agent staging dir under workspace (never OS /tmp)
  • verify — verify file integrity by comparing BLAKE3 checksum

Search and replace

  • search — search file contents in parallel (ripgrep engine)
  • replace — replace text across files with atomic writes
  • transform — AST refactoring via ast-grep (306 languages)
  • codemod — multi-rule codemod campaign (YAML rules, delegates to transform)
  • semantic-search — offline token Jaccard search (no network, no embeddings API)
  • semantic-merge — three-way line-based merge (not AST/embedding) for multi-agent writes

Inspection

  • hash — calculate BLAKE3 checksums
  • stat — metadata alias for read --stat (size, mode, checksum; no body)
  • count — count lines, files by extension
  • diff — compare two files (unified, stat, or changes)
  • list — list files in a directory tree
  • sparse — budgeted sparse list/read (cap files and bytes for agent context)
  • extract — extract fields from NDJSON input via pipe (positional fields or local --field; never local extract --select — global --select only projects output keys)
  • scope — grammatical scoping (delete all comments, etc.)
  • regex — generate regex from examples
  • calc — math and unit conversions
  • doctor — diagnose environment and dependencies
  • locale — show resolved UI locale / persist preference (XDG)
  • commands — emit full command tree as JSON for agent discovery
  • agent-surface — agent tool surface manifesto without MCP
  • watch — watch filesystem events (feature watch)
  • completions — generate shell completions (bash, zsh, fish, elvish, powershell)

Backup and recovery

  • backup — create timestamped backups with BLAKE3 checksums
  • rollback — restore from a previous backup
  • prune-backups — prune .bak.YYYYMMDD_HHMMSS backups by age or count
  • batch — NDJSON-driven batch operations (transactional)
  • recipe — named multi-step recipes (list / run)

Structured config editors (v0.1.12, v14 Tier 3)

  • set <PATH> <KEY_PATH> <VALUE> — write a value at a dotted path in a TOML or JSON file. Preserves comments and key order via toml_edit. Auto-coerces int/bool/float/string.
  • get <PATH> <KEY_PATH> — read a value at a dotted path. NDJSON: {"type":"get","key_path","value","found","format"}.
  • del <PATH> <KEY_PATH> — remove a key. --force-missing flag treats missing keys as a no-op success.
  • case <PATHS...> --subvert OLD NEW --to <style> — rename identifiers across multiple files via heck. Styles: snake, camel, pascal, kebab, screaming-snake.

AST tools (v0.1.12, v14 Tier 3 + G72, via tree-sitter-language-pack)

  • query <PATH> [--kinds|--query <KIND>|-Q <KIND>|--tree] [--positions] — walk a tree-sitter AST and emit nodes as NDJSON. 305 languages supported.
  • outline <PATH> [--kind <KIND>] [--positions] — extract high-level structure (functions, classes, structs, enums, traits, modules) as NDJSON.
  • write --syntax-check — G72 REAL syntax check via tree-sitter. 24 languages covered. Exit 88 with first error line/column/kind/message.

WAL cleanup (v0.1.15, G119)

  • wal-stats — telemetry snapshot: total journals, by-state breakdown, oldest age, total size, by-directory breakdown, auto-heal recommendation, estimated reclaim bytes
  • wal-heal [--threshold-secs N] [--budget-ms N] — reap stale terminal journals older than the threshold. Safe and idempotent

Common patterns for each subcommand

# read
atomwrite --workspace . read src/main.rs

# write
echo "fn main() {}" | atomwrite --workspace . write src/main.rs

# edit
atomwrite --workspace . edit src/main.rs --old "old text" --new "new text"

# edit-loop (N old/new pairs, one atomic write)
printf '%s\n' '{"old":"foo","new":"bar"}' '{"old":"baz","new":"qux"}' \
  | atomwrite --workspace . edit-loop src/version.rs

# scratch — stage under .atomwrite/scratch/; never OS /tmp outside --workspace for --old-file/--new-file
atomwrite --workspace . scratch init
atomwrite --workspace . edit src/main.rs \
  --old-file .atomwrite/scratch/old.txt \
  --new-file .atomwrite/scratch/new.txt

# verify
atomwrite --workspace . verify src/main.rs abc123def456

# search
atomwrite --workspace . search 'TODO' src/ --include '*.rs'

# replace
atomwrite --workspace . replace 'old_name' 'new_name' src/ --include '*.rs'

# hash
atomwrite --workspace . hash src/main.rs src/lib.rs

# delete
atomwrite --workspace . delete src/temp.rs --backup

# count
atomwrite --workspace . count src/ --by-extension

# diff
atomwrite --workspace . diff src/old.rs src/new.rs --unified

# move
atomwrite --workspace . move src/old.rs src/new.rs

# copy
atomwrite --workspace . copy src/template.rs src/new_module.rs

# list
atomwrite --workspace . list src/ --depth 2

# extract — positional fields or local --field; NEVER local extract --select
atomwrite --workspace . search 'TODO' src/ | atomwrite extract path line
atomwrite --workspace . search 'TODO' src/ | atomwrite extract --field path --field line
# thin agent shape (global --select projects output keys only):
atomwrite --workspace . search 'TODO' src/ --select path,line --limit 20

# calc
atomwrite calc "2 GiB to bytes"
atomwrite calc "sqrt(144) + 3^2"

# regex
atomwrite regex "2024-01-15" "2025-12-31" "2026-06-01"

# transform
atomwrite --workspace . transform -p 'println!($$$ARGS)' -r 'tracing::info!($$$ARGS)' -l rust src/

# scope
atomwrite --workspace . scope src/ --lang rust --query comments --delete

# batch
cat manifest.ndjson | atomwrite --workspace . batch --transaction

# backup
atomwrite --workspace . backup src/config.toml

# rollback
atomwrite --workspace . rollback src/config.toml

# prune-backups
atomwrite --workspace . prune-backups --max-age-secs 86400 src/config.toml
atomwrite --workspace . prune-backups --max-count 3 --dry-run src/config.toml

# apply
echo "new content" | atomwrite --workspace . apply src/file.txt --format full

# set (v0.1.12)
atomwrite --workspace . set Cargo.toml package.version 0.2.0

# get (v0.1.12)
atomwrite --workspace . get Cargo.toml package.version

# del (v0.1.12)
atomwrite --workspace . del Cargo.toml package.metadata.boring

# case (v0.1.12)
atomwrite --workspace . case src/ --subvert user_id UserId --to pascal

# query (v0.1.12)
atomwrite --workspace . query src/main.rs --kinds
atomwrite --workspace . query src/main.rs -Q function_item --positions

# outline (v0.1.12)
atomwrite --workspace . outline src/app.py

# wal-stats (v0.1.15)
atomwrite --workspace . wal-stats

# wal-heal (v0.1.15)
atomwrite --workspace . wal-heal --threshold-secs 3600 --budget-ms 100

# stat
atomwrite --workspace . stat src/lib.rs

# sparse
atomwrite --workspace . sparse list --max-files 100 --max-bytes 1048576 src/

# semantic-merge (line-based, not AST)
atomwrite --workspace . semantic-merge \
  --base base.rs --ours ours.rs --theirs theirs.rs --output src/merged.rs

# recipe
atomwrite --workspace . recipe list
atomwrite --workspace . recipe run --name search-replace-verify \
  --path src --pattern OLD_TOKEN --replacement NEW_TOKEN --fuzzy auto

# agent-surface
atomwrite --workspace . agent-surface

# watch (requires feature watch)
atomwrite --workspace . watch . --debounce-ms 200 --max-events 20

# codemod
atomwrite --workspace . codemod --rules rules.yaml --dry-run src/

# semantic-search
atomwrite --workspace . semantic-search "atomic rename tempfile" src/ --k 10

# doctor
atomwrite --workspace . doctor
atomwrite --workspace . doctor --strict

# locale
atomwrite locale
atomwrite locale --set pt-BR
atomwrite locale --clear

# commands (full clap tree for agent discovery)
atomwrite commands
atomwrite commands --include-globals

# completions
atomwrite completions bash

Environment Variables

  • v0.1.35 product policy: atomwrite does not use product environment variables for runtime knobs (workspace, backup, locale, log filter, home override, WAL, etc.).
  • Configure via CLI flags and XDG storage / .atomwrite.toml (and optional --config).
  • doctor may observe host environment variables (for example CI indicators) for diagnostics only — that is not a configuration API.
  • Shell-level variables used by your agent harness (PATH, etc.) are outside atomwrite product config.

Exit Codes

  • Error envelopes on stdout are always NDJSON with ok: false (and usually match_count); read exit / code before treating a line as success
  • 0: success
  • 1: no matches found (search, not an error)
  • 4: file not found
  • 13: permission denied
  • 28: disk full (no space left on device)
  • 30: quota exceeded
  • 65: invalid input (bad arguments or malformed data, including empty stdin without --allow-empty-stdin since v0.1.16)
  • 73: cross-device rename (filesystem boundary)
  • 74: I/O error
  • 78: configuration invalid
  • 81: checksum verify failed
  • 82: state drift (checksum mismatch, optimistic lock failed)
  • 83: lock timeout (v0.1.12+)
  • 85: FIFO detected (named pipe cannot be atomically written)
  • 86: device file detected (block or character device)
  • 88: syntax error detected (v0.1.12+, --syntax-check failed)
  • 91: EXDEV fallback disabled (v0.1.12+, --strict-atomic forbids cross-device copy-fallback)
  • 92: copy-back BLAKE3 verification failed (v0.1.12+)
  • 93: orphan journal detected (v0.1.12+, G114 consultive recovery)
  • 126: workspace jail violated (path escapes workspace)
  • 127: symlink blocked (symlink target outside workspace)
  • 128: file immutable (cannot modify)
  • 124: global --timeout-secs deadline exceeded (default 120; pass 0 to disable)
  • 130: interrupted by SIGINT
  • 141: broken pipe (SIGPIPE)
  • 143: terminated by SIGTERM
  • 255: internal error

Signal Handling

  • Unix: SIGINT (Ctrl+C) and SIGTERM intercepted for graceful shutdown
  • Unix: SIGPIPE reset to SIG_DFL for standard pipe behavior (exit 141)
  • Windows: Ctrl+C intercepted via console handler
  • First signal: sets shutdown flag, prints "shutting down..." to stderr
  • Second signal: immediate process termination via _exit (Unix) or exit (Windows)
  • Walker threads (search, replace, transform, scope) stop between files
  • Batch operations stop between operations

Error Handling

  • All errors emit a JSON object on stdout with error: true
  • Error fields: code, exit, message, path, error_class, retryable, suggestion, workspace
  • Error classes: permanent, transient, conflict, precondition_failed
  • 25 error variants total (20 baseline from v0.1.4 + 5 added in v0.1.12)
  • Transient and conflict errors set retryable: true
  • The suggestion field provides actionable recovery guidance for agents
  • See docs/schemas/error-output.schema.json for the full contract

Performance

  • Single static binary with zero runtime dependencies
  • Release builds use LTO, single codegen unit, and symbol stripping
  • Memory-mapped file reads via memmap2 for large files
  • Parallel multi-file work is the default modus operandi: ignore::WalkParallel / collect_files_parallel (search content + --target files, replace, count, transform, scope, recursive discovery) + rayon (hash, backup, multi-path + recursive delete/copy, case multi-path, semantic-search scoring, non-txn batch, prune multi-target, sparse read, diff dual-read)
  • Worker bound: --threads / -j / --max-concurrency (default = all logical CPUs, RAM-capped; see src/concurrency.rs)
  • Typical file operation latency: under 5 ms for small files

Troubleshooting FAQ

atomwrite write hangs with no output

  • Ensure you are piping content to stdin
  • write reads from stdin and waits for EOF
  • Example: echo "content" | atomwrite --workspace . write file.txt

search returns exit code 1

  • Exit code 1 means zero matches were found
  • This is expected behavior, not an error
  • Check the pattern and target path

cross-device rename fails with exit 73

  • The source and destination are on different filesystems
  • atomwrite falls back to copy+delete for move across devices
  • Use copy followed by delete as an alternative

checksum mismatch with exit 82

  • Another process modified the file between read and write
  • Re-read the file to get the current checksum
  • Retry the operation with the updated --expect-checksum

workspace jail violated with exit 126

  • The target path resolves outside the --workspace boundary
  • Verify the path does not contain .. traversals or symlinks escaping the workspace

syntax check failed with exit 88 (v0.1.12+)

  • The G72 REAL tree-sitter syntax check found a syntax error in the file
  • Inspect the first error line/column/kind/message in the JSON error envelope
  • Fix the syntax and retry, or remove --syntax-check to bypass

empty stdin rejected with exit 65 (v0.1.16+)

  • The G120 L1 guard rejected 0 bytes from stdin as a likely upstream-pipeline failure
  • Pass --allow-empty-stdin to confirm the empty input is intentional
  • Or pipe real content: echo "x" | atomwrite --workspace . write file

edit hangs (or fails with exit 65) on --after-line/--after-match/--between/--multi (v0.1.28+)

  • These modes read replacement content from stdin, same as write
  • Since v0.1.28 a terminal stdin fails FAST with exit 65 INVALID_INPUT instead of blocking forever
  • Pipe content: echo "new text" | atomwrite --workspace . edit file.rs --after-line 10
  • Or use --new-file <PATH> where the mode accepts it
  • --after-match/--before-match/--between/--after-line/--before-line/--range/--delete-range reject --old/--new/--old-file/--new-file at parse time (exit 2) — these modes only take content from stdin

Architecture

  • See ARCHITECTURE.md for module map, data flow, and design decisions
  • See docs/decisions/ for 12 ADRs covering v0.1.12 onward architecture (G72, G114, v14 Tier 3, G117, G118, G119, G120, v0.1.18 trio)
  • See docs/schemas/ for 22 stable JSON Schema contracts for all NDJSON output

Contributing

Security

  • See SECURITY.md for vulnerability reporting
  • See SECURITY.md section "Known Security Advisories" for resolved and active advisories

Changelog

License