Zat

English · 中文

What's Zat?

Zat (Zed Agent Thread Manager) is a standalone command-line tool for managing Zed Agent threads. It provides functionality to view, migrate, export, import, and restore threads from the agent's database.

Installation

pip install zat-man

Back up before use

⚠️ WARNING: zat reads and writes Zed's thread database directly. Although all write operations are protected by transactions and automatic snapshots, mistakes, bugs, or unexpected failures can still cause data loss. Complete a backup before your first write operation, and make sure you know how to restore it.

Manual backup:

1. Quit Zed completely.

2. Copy the entire Zed data directory:

   • {data_dir}/threads — full thread contents
   • {data_dir}/db — sidebar metadata

   Platform data_dir: Windows %LOCALAPPDATA%\Zed; macOS ~/Library/Application Support/Zed; Linux ~/.local/share/zed

Manual restore:

1. Quit Zed completely.
2. Copy the backup directory back to its original location.

Core Workflow

This section demonstrates the core capabilities of zat through a common workflow.

1. Checking the Status

Use the list (or ls) command to inspect the current state of all threads. It groups threads by project and highlights any anomalies.

$ zat ls
Project: C:\Users\foo\Desktop\project1    3 thread(s)
┏━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Status ┃ Hash     ┃ Title                                   ┃ Updated    ┃
┡━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ 💬     │ 3f9a2c81 │ Fix login crash logic                   │ 2026-08-09 │
│ 💬     │ 7b1e04d2 │ Refactor cache layer                    │ 2026-08-09 │
│ 💬     │ d4e8b9f0 │ Add dark mode support                   │ 2026-08-09 │
└────────┴──────────┴─────────────────────────────────────────┴────────────┘

Orphaned threads (path does not exist; recover with move):
  ⚠️  a7c21e9d  ...from ['C:\\Users\\foo\\Desktop\\legacy-project']

The output reveals an "orphaned" thread, marked with ⚠️. This indicates that its associated project path, C:\Users\foo\Desktop\legacy-project, no longer exists on the file system, likely because the project directory was moved or renamed.

2. Correcting the Path

We can use the move (or mv) command to fix this orphaned thread by associating it with the new project path. move can target threads by their unique hash prefix or by their old project path.

Before performing any write operation, zat checks if the Zed process is running to ensure database consistency.

$ zat mv a7c21e9d C:\Users\foo\Desktop\project1
[ERROR] Please quit Zed first

After quitting Zed, run the command again.

$ zat mv a7c21e9d C:\Users\foo\Desktop\project1
[SUCCESS] Moved 1 thread(s).

Running zat ls again will show that the thread has been successfully moved to the new project, and its orphaned status is resolved.

3. Auditing and Restoring Operations

All write operations (like move, import, and restore) automatically create a checkpoint before execution. We can list these checkpoints at any time.

$ zat chkpt list
ID  chkpt-20260809T120000.123456Z-save-3c84
    created    2026-08-09 20:00:00.123 +08:00
    source     manual (save)
    channel    stable
    command    chkpt save
    ---------------------------
ID  chkpt-20260809T120500.123456Z-move-a7c2
    created    2026-08-09 20:05:00.123 +08:00
    source     auto (move)
    channel    stable
    command    mv a7c21e9d C:\Users\foo\Desktop\project1

If you are not satisfied with the move operation, you can use the checkpoint ID to restore the database to its state before the operation was performed.

$ zat chkpt restore chkpt-20260809T120500.123456Z-move-a7c2

This checkpoint system provides a reliable rollback mechanism for all critical operations. It is also recommended to manually run zat chkpt save to create an explicit baseline before performing complex tasks.

Migration and Archiving

zat also supports data migration across devices or projects.

1. Exporting Data

The export command packages specified threads (or all threads) into a self-contained .zth file. This file contains the full thread content and metadata but excludes any local file paths, making it highly portable.

$ zat export --to threads-archive.zth --markdown
[SUCCESS] Exported 12 thread(s) to threads-archive.zth
[SUCCESS] Markdown written to threads-archive-markdown.zip (12 file(s))

The --markdown option generates an additional ZIP archive containing human-readable Markdown files for each thread, suitable for offline browsing and archiving.

2. Importing Data

On another machine or system, use the import command to inject threads from a .zth file into a specified project path.

$ zat import --from threads-archive.zth --to C:\work\new-project
[SUCCESS] Imported 12 thread(s) into C:\work\new-project

The import process includes strict data validation and conflict detection to ensure the integrity of the target database is not compromised.

Command Reference

• Query & Diagnostics

  • zat list [--project PATH] [--all] [--json] (alias: ls)
  • zat doctor

• Data Modification

  • zat move --from <hash|path> --to NEW_PATH (alias: mv <src> <dst>)
  • zat delete <ID>... (alias: rm)

• Import & Export

  • zat export [--from <hash|path>] [--to OUT_FILE] [--markdown]
  • zat import --from FILE --to DIR

• Checkpoint Management

  • zat chkpt list (alias: ls)
  • zat chkpt save [--dir PATH]
  • zat chkpt restore [ID_OR_PATH]
  • zat chkpt delete <ID>... (alias: rm)

Development

The environment and dependencies are managed with uv.

# Install dependencies
uv sync

# Run the test suite
uv run pytest

# Run the CLI from source
uv run zat --help

For details on the testing strategy and coverage, see docs/TESTING.md.

License

GPL-3.0-or-later