Metadata-Version: 2.5
Name: zat-man
Version: 2026.8.19
Summary: Zed Agent Thread Manager: view/migrate/export/import/restore Zed agent threads
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: loguru>=0.7.3
Requires-Dist: rich>=15.0.0
Requires-Dist: zstandard>=0.25.0
Description-Content-Type: text/markdown

# Zat
English · [中文](README.zh-CN.md)

## 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

```sh
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.

```sh
$ 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.

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

After quitting Zed, run the command again.

```sh
$ 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.

```sh
$ 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.

```sh
$ 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.

```sh
$ 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. Rendering & Document Export (`zat md`)

The `md` command provides enhanced Markdown formatting, filtering, and privacy sanitization for human reading, sharing, and Obsidian/PKM integration:

```sh
# Export a clean, de-identified markdown file in current directory ({hash}-{title}.md)
$ zat md 3f9a2c81 --preset clean

# Stream prompts-only directly to stdout / clipboard
$ zat md 3f9a2c81 --preset prompts --stdout | clip

# Batch export an entire project to Obsidian notes (collapsible tools, YAML frontmatter, INDEX.md)
$ zat md --project C:\work\project1 --out-dir ~/Documents/Obsidian/Notes --preset collapsed --frontmatter --index
```

### 3. Importing Data

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

```sh
$ 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 & Document Rendering**
    *   `zat export [--from <hash|path>] [--to OUT_FILE] [--markdown]`
    *   `zat md [TARGET] [--preset ...] [--out-dir ...] [-o ...] [--frontmatter] [--sanitize-paths] [--index]`
    *   `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`.

```sh
# 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](https://www.gnu.org/licenses/gpl-3.0.html)
