multi-agent-archiver 0.1.5__tar.gz

multi_agent_archiver-0.1.5/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # https://github.com/astral-sh/setup-uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Run ruff
+        run: uv run ruff check .

multi_agent_archiver-0.1.5/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+      attestations: write
+
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # https://github.com/astral-sh/setup-uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

multi_agent_archiver-0.1.5/.gitignore

@@ -0,0 +1,10 @@
+.venv
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.gemini
+.logs/
+archiver.log

multi_agent_archiver-0.1.5/.python-version

@@ -0,0 +1 @@
+3.12

multi_agent_archiver-0.1.5/GEMINI.md

@@ -0,0 +1,66 @@
+# GEMINI.md - ChatArch Project Context
+
+## Project Overview
+**ChatArch** is a Python-based utility designed to manage and archive AI conversation histories from various local platforms (Gemini CLI, Roo Code/Cline, and Aider) to AWS S3. Its primary goal is to reclaim local disk space while preserving conversations in a summarized, searchable Markdown format.
+
+### Key Technologies
+- **Python 3.12+**: Core logic.
+- **uv**: Dependency management and environment isolation.
+- **AWS SDK (boto3)**: For S3 uploads.
+- **Google Gemini API (google-genai)**: For conversation summarization using `gemini-2.5-flash`.
+- **1Password CLI (`op`)**: Secure retrieval of API keys.
+- **Ruff**: Linting and code formatting.
+
+### Architecture
+- `archiver.py`: Contains the core `ChatArchiver` class which handles file discovery, filtering (e.g., "commit-only" chats), Markdown conversion, summarization, and S3 uploading. Each conversation is archived as three separate files in S3:
+  - `<name>.md`: Human-readable Markdown with the summary at the top.
+  - `<name>.summary.txt`: A standalone text file containing the AI-generated summary.
+  - `<name>.json`: The original raw conversation data.
+- `config.yaml`: Centralized configuration for S3 settings, summarization parameters, local search paths, and filtering rules.
+- `Makefile`: Provides a simplified CLI interface for common tasks.
+- `archiver.log`: Detailed execution logs.
+
+## Building and Running
+
+### Prerequisites
+1.  **uv**: Install via `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+2.  **AWS CLI**: Configured with appropriate S3 permissions.
+3.  **1Password CLI (`op`)**: Installed and signed in (`op signin`).
+4.  **Gemini API Key**: Should be stored in 1Password at `op://Private/GEMINI_API_KEY/credential`.
+
+### Common Commands
+- **Dry Run**: Preview changes without affecting local files or S3.
+  ```bash
+  make dry-run
+  ```
+- **Run Archive**: Perform full linting, summarization, upload, and deletion.
+  ```bash
+  make archive
+  ```
+- **Limited Run**: Process only a specific number of files (useful for testing).
+  ```bash
+  make archive ARGS="--limit 5"
+  ```
+- **Linting**:
+  ```bash
+  make lint
+  ```
+
+## Development Conventions
+
+### Code Style
+- Follows PEP 8 via **Ruff**.
+- Ensure all changes are linted using `make lint` before execution.
+
+### Configuration
+- Paths for different chat platforms are defined in `config.yaml`.
+- When adding support for a new platform, update the `paths` section in `config.yaml` and implement the corresponding parsing logic in `archiver.py`.
+
+### Safety & Verification
+- **Retention Policy**: By default, only files older than 20 days are archived (configurable/logic-driven in `archiver.py`).
+- **Atomic Operations**: Files are only deleted locally if the S3 upload is confirmed successful.
+- **Logging**: All operations should be logged to `archiver.log` using the `logger` instance.
+
+### Error Handling
+- Use exponential backoff for API calls (handled in `archiver.py`).
+- Critical errors are mirrored to `stderr` via the console handler, while detailed info stays in the log file.

multi_agent_archiver-0.1.5/Makefile

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+.PHONY: help
+help: ## Display this help screen
+	@echo "Available commands:"
+	@awk 'BEGIN {FS = ":.*?## "}; /^[a-zA-Z_-]+:.*?## / {printf "  \033[32m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+# ==============================================================================
+# Application Tasks
+# ==============================================================================
+
+lint: ## Run linting and auto-fix with Ruff
+	uv run ruff check --fix .
+
+dry-run: lint ## Perform a dry run of the archiver (e.g. make dry-run ARGS="--limit 5")
+	uv run cax dry-run $(ARGS)
+
+archive: lint ## Archive chats to S3 and remove local files
+	uv run cax archive $(ARGS)
+
+cleanup: lint ## Delete commit-only chats locally (no S3 upload)
+	uv run cax cleanup $(ARGS)

multi_agent_archiver-0.1.5/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: multi-agent-archiver
+Version: 0.1.5
+Summary: Archive local AI chat histories to S3, freeing up disk space while keeping conversations searchable
+Author-email: Mark Stouffer <1802850+InTEGr8or@users.noreply.github.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.42.17
+Requires-Dist: google-genai>=1.56.0
+Requires-Dist: multi-agent-registry>=0.2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=13.9.4
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: verkit>=0.1.4
+Description-Content-Type: text/markdown
+
+# ChatArch: AI Conversation Archiver
+
+ChatArch is a utility designed to migrate local AI chat histories to AWS S3, freeing up local disk space while preserving conversations in a human-readable, summarized, and searchable format.
+
+## Features
+
+- **Multi-Platform Support:** Automatically discovers chats from Gemini CLI, Roo Code (Cline), and Aider.
+- **Smart Cleanup:** Identifies and deletes "commit-only" chats (short messages used solely for git commits) before archiving.
+- **Markdown Conversion:** Converts complex JSON chat schemas into clean, readable Markdown files within the archive.
+- **AI-Powered Summarization:** Uses Gemini 2.5 Flash to generate 1-2 sentence summaries for every archived conversation.
+- **Safe Archival:**
+  - **Retention Policy:** Only archives chats older than 20 days.
+  - **Verification:** Local files are only deleted after a successful S3 upload.
+  - **Rate Limit Handling:** Includes configurable delays and exponential backoff for API calls.
+- **Space Reporting:** Reports the total disk space reclaimed at the end of each run.
+
+## Prerequisites
+
+- **Python & uv:** Managed via `uv`.
+- **AWS CLI:** Must be configured with credentials that have `s3:PutObject` permissions.
+- **1Password CLI (`op`):** Used to securely retrieve the Gemini API key.
+- **Google Gemini API Key:** Stored in 1Password at `op://Private/GEMINI_API_KEY/credential`.
+
+## Usage
+
+Commands are managed via the `Makefile` for convenience.
+
+### 1. Dry Run (Recommended)
+Verify which files will be deleted or archived without actually performing any actions:
+```bash
+make dry-run
+```
+
+### 2. Actual Archive
+Perform the cleanup and migration:
+```bash
+make archive
+```
+
+### 3. Using Limits
+To test the full process on a small sample (e.g., 5 files):
+```bash
+make archive ARGS="--limit 5"
+```
+
+### 4. Maintenance
+Run linting and auto-fixes:
+```bash
+make lint
+```
+
+## Configuration
+
+Settings like S3 bucket names, local search paths, and API delays are managed in `config.yaml`.
+
+## Logging
+
+All detailed operations and API responses are logged to `.logs/archiver.log`, rotated daily and kept for 180 days. Progress is displayed in the terminal via a status bar.
+
+## Development
+
+The package publishes three equivalent commands: `chatarch`, and its short aliases `cax` and `maa` (`pip install multi-agent-archiver` / `uv tool install multi-agent-archiver`).
+
+Inside this repo, `bin/` (added to `PATH` via `mise.toml`'s `[env]` when you `cd` in, since this repo's dev environment is managed with [mise](https://mise.jdx.dev/)) shadows the globally installed commands with a shim that runs this repo's live source via `uv run`. Outside the repo, `chatarch`/`cax`/`maa` resolve back to whatever version is installed globally. Run `mise trust` once after cloning to enable it.

multi_agent_archiver-0.1.5/README.md

@@ -0,0 +1,64 @@
+# ChatArch: AI Conversation Archiver
+
+ChatArch is a utility designed to migrate local AI chat histories to AWS S3, freeing up local disk space while preserving conversations in a human-readable, summarized, and searchable format.
+
+## Features
+
+- **Multi-Platform Support:** Automatically discovers chats from Gemini CLI, Roo Code (Cline), and Aider.
+- **Smart Cleanup:** Identifies and deletes "commit-only" chats (short messages used solely for git commits) before archiving.
+- **Markdown Conversion:** Converts complex JSON chat schemas into clean, readable Markdown files within the archive.
+- **AI-Powered Summarization:** Uses Gemini 2.5 Flash to generate 1-2 sentence summaries for every archived conversation.
+- **Safe Archival:**
+  - **Retention Policy:** Only archives chats older than 20 days.
+  - **Verification:** Local files are only deleted after a successful S3 upload.
+  - **Rate Limit Handling:** Includes configurable delays and exponential backoff for API calls.
+- **Space Reporting:** Reports the total disk space reclaimed at the end of each run.
+
+## Prerequisites
+
+- **Python & uv:** Managed via `uv`.
+- **AWS CLI:** Must be configured with credentials that have `s3:PutObject` permissions.
+- **1Password CLI (`op`):** Used to securely retrieve the Gemini API key.
+- **Google Gemini API Key:** Stored in 1Password at `op://Private/GEMINI_API_KEY/credential`.
+
+## Usage
+
+Commands are managed via the `Makefile` for convenience.
+
+### 1. Dry Run (Recommended)
+Verify which files will be deleted or archived without actually performing any actions:
+```bash
+make dry-run
+```
+
+### 2. Actual Archive
+Perform the cleanup and migration:
+```bash
+make archive
+```
+
+### 3. Using Limits
+To test the full process on a small sample (e.g., 5 files):
+```bash
+make archive ARGS="--limit 5"
+```
+
+### 4. Maintenance
+Run linting and auto-fixes:
+```bash
+make lint
+```
+
+## Configuration
+
+Settings like S3 bucket names, local search paths, and API delays are managed in `config.yaml`.
+
+## Logging
+
+All detailed operations and API responses are logged to `.logs/archiver.log`, rotated daily and kept for 180 days. Progress is displayed in the terminal via a status bar.
+
+## Development
+
+The package publishes three equivalent commands: `chatarch`, and its short aliases `cax` and `maa` (`pip install multi-agent-archiver` / `uv tool install multi-agent-archiver`).
+
+Inside this repo, `bin/` (added to `PATH` via `mise.toml`'s `[env]` when you `cd` in, since this repo's dev environment is managed with [mise](https://mise.jdx.dev/)) shadows the globally installed commands with a shim that runs this repo's live source via `uv run`. Outside the repo, `chatarch`/`cax`/`maa` resolve back to whatever version is installed globally. Run `mise trust` once after cloning to enable it.

multi_agent_archiver-0.1.5/bin/cax

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Dev shim: runs this repo's live source via `uv run` instead of the
+# globally uv-tool-installed agent-chat-archiver. Only on PATH while inside
+# this repo (see mise.toml's [env]._.path) -- outside it, the `cax`/
+# `chatarch` on PATH are the globally installed, published version.
+set -euo pipefail
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec uv run --project "$repo_root" "$(basename "${BASH_SOURCE[0]}")" "$@"

multi_agent_archiver-0.1.5/bin/chatarch

@@ -0,0 +1 @@
+cax

multi_agent_archiver-0.1.5/bin/maa

@@ -0,0 +1 @@
+cax

multi_agent_archiver-0.1.5/config.yaml

@@ -0,0 +1,29 @@
+s3:
+  bucket: chatarch
+  prefix: chats/
+
+retention:
+  days: 20          # Only archive chats older than this
+  keep_recent: 5    # Always keep the N most recent chats per workspace
+
+summarization:
+  model: "gemini-2.5-flash-lite"
+  delay: 20 # Seconds to wait between API calls
+
+paths:
+  gemini:
+    - "~/.gemini/tmp/**/chats/session-*.json"
+  roo:
+    - "~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/*/ui_messages.json"
+    - "~/.vscode-server-insiders/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/*/ui_messages.json"
+    - "~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/*/ui_messages.json"
+    - "~/.config/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/tasks/*/ui_messages.json"
+  # aider and claude are now discovered via agent-cli-registry, not globs here.
+
+filters:
+  gemini_commit_only:
+    keywords:
+      - "git diff --cached"
+      - "create a git commit"
+      - "perform the commit without asking"
+    max_messages: 2