session-zoo 0.1.0__tar.gz

session_zoo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q

session_zoo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

session_zoo-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.tox/
+.coverage
+htmlcov/
+.venv/
+venv/
+env/
+.vscode/
+.idea/
+.DS_Store
+*.pem
+*.key
+.env
+.superpowers/

session_zoo-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

session_zoo-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-12
+
+### Added
+
+- CLI tool `zoo` with 14 commands: init, config, import, list, show, search, tag, tags, delete, summarize, sync, clone, reindex, restore
+- Claude Code adapter: discover, parse, and restore sessions from `~/.claude/`
+- Multi-provider AI summarization: Claude Code CLI, Codex CLI, Anthropic API
+- Git-based sync: push raw JSONL + metadata + Markdown summaries to GitHub
+- Cross-device restore: clone repo → reindex → restore sessions to `~/.claude/`
+- SQLite local index with search, filter by project/tool/tag/date
+- Markdown renderer with noise filtering, tool call merging, relative paths
+- Tag management for organizing sessions

session_zoo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to session-zoo
+
+Thanks for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/AndsGo/session-zoo.git
+cd session-zoo
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Code Style
+
+- Python 3.12+ with type hints
+- Keep functions focused and small
+- Follow existing patterns in the codebase
+
+## Adding a New Adapter
+
+To support a new AI tool (e.g., Cursor, Copilot), create a new adapter:
+
+1. Create `src/session_zoo/adapters/your_tool.py`
+2. Implement the adapter class with `discover()`, `parse()`, `get_restore_path()` methods
+3. Register it in `src/session_zoo/adapters/__init__.py`
+4. Add tests in `tests/test_your_tool_adapter.py`
+
+See `adapters/claude_code.py` for reference.
+
+## Pull Request Process
+
+1. Fork the repo and create a branch from `main`
+2. Add tests for any new functionality
+3. Ensure all tests pass (`pytest`)
+4. Submit a PR with a clear description of the changes

session_zoo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AndsGo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

session_zoo-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: session-zoo
+Version: 0.1.0
+Summary: AI development session recorder — save and sync sessions to GitHub
+Project-URL: Homepage, https://github.com/AndsGo/session-zoo
+Project-URL: Repository, https://github.com/AndsGo/session-zoo
+Project-URL: Issues, https://github.com/AndsGo/session-zoo/issues
+Author-email: AndsGo <18702149475@163.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,codex,developer-tools,recorder,session
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.52.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest-tmp-files>=0.0.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# session-zoo
+
+[English](README.md) | [中文](README_zh.md)
+
+Save and sync your AI development sessions to GitHub.
+
+`session-zoo` automatically discovers sessions from AI coding tools (Claude Code, Codex, etc.), generates AI summaries, and syncs everything to a GitHub repo — raw data preserved for cross-device migration, plus readable Markdown for review.
+
+<p align="center">
+  <img src="docs/demo.gif" alt="session-zoo demo" width="700">
+</p>
+
+## Features
+
+- **Auto-discover** sessions from `~/.claude/` (Claude Code adapter built-in)
+- **AI Summarize** using existing Claude/Codex CLI (no API key needed) or Anthropic API
+- **Git Sync** raw JSONL + metadata + Markdown summaries to GitHub
+- **Cross-device restore** — clone on a new machine, restore sessions to `~/.claude/` for `/resume`
+- **Tag & Search** sessions by project, tool, date, or custom tags
+- **Extensible** adapter pattern — easy to add support for new AI tools
+
+## Quick Start
+
+### Install
+
+```bash
+pip install session-zoo
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/AndsGo/session-zoo.git
+cd session-zoo
+pip install -e .
+```
+
+### Setup
+
+```bash
+# Initialize
+zoo init
+
+# Set your GitHub repo for syncing (create an empty repo first)
+zoo config set repo git@github.com:yourname/my-sessions.git
+```
+
+### Basic Workflow
+
+```bash
+# Import sessions from Claude Code
+zoo import
+
+# List all sessions
+zoo list
+
+# View session details
+zoo show <session-id>
+zoo show <session-id> --markdown
+
+# Generate AI summary (uses installed claude/codex CLI automatically)
+zoo summarize <session-id>
+
+# Tag sessions for organization
+zoo tag <session-id> bugfix security
+
+# Sync everything to GitHub
+zoo sync
+```
+
+### Cross-Device Restore
+
+On a new machine:
+
+```bash
+zoo init
+zoo config set repo git@github.com:yourname/my-sessions.git
+zoo clone      # Clone the session repo
+zoo reindex    # Rebuild local index from repo
+zoo restore    # Restore .jsonl files to ~/.claude/ for /resume
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `zoo init` | Initialize configuration |
+| `zoo config show/set` | View or set config (repo, ai-key, ai-model) |
+| `zoo import` | Import new sessions from AI tools |
+| `zoo list` | List sessions (filter by --project, --tool, --tag, --since) |
+| `zoo show <id>` | Show session details (--raw, --markdown) |
+| `zoo search <query>` | Search sessions by summary content |
+| `zoo tag <id> [tags...]` | Add/remove tags |
+| `zoo tags` | List all tags with counts |
+| `zoo delete <id>` | Delete a session from index |
+| `zoo summarize [id]` | Generate AI summaries (--provider auto/claude-code/codex/api) |
+| `zoo sync` | Sync sessions to GitHub (--dry-run) |
+| `zoo clone` | Clone session repo to local |
+| `zoo reindex` | Rebuild SQLite index from repo |
+| `zoo restore` | Restore session files to tool directories |
+
+## Summarization Providers
+
+`zoo summarize` supports multiple providers, auto-detected by priority:
+
+1. **claude-code** — Uses installed `claude -p` CLI (no API key needed)
+2. **codex** — Uses installed `codex -q` CLI (no API key needed)
+3. **api** — Uses Anthropic API directly (requires `zoo config set ai-key <key>`)
+
+```bash
+# Auto-detect (uses whatever is available)
+zoo summarize <id>
+
+# Force a specific provider
+zoo summarize --provider claude-code <id>
+zoo summarize --provider api <id>
+```
+
+## GitHub Repo Structure
+
+```
+your-sessions-repo/
+├── raw/claude-code/my-project/
+│   ├── <session-id>.jsonl          # Raw session data (preserved as-is)
+│   └── <session-id>.meta.json     # Metadata (tags, summary, cwd)
+└── sessions/my-project/2026-03-10/claude-code/
+    └── <session-id>.md            # Readable Markdown summary
+```
+
+## Adding Adapters
+
+session-zoo uses an adapter pattern to support different AI tools. Currently supported:
+
+- **Claude Code** (`~/.claude/projects/`)
+
+To add a new adapter, implement `discover()`, `parse()`, and `get_restore_path()`. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Requirements
+
+- Python 3.12+
+- Git
+- (Optional) `claude` or `codex` CLI for summarization without API key
+
+## License
+
+[MIT](LICENSE)

session_zoo-0.1.0/README.md

@@ -0,0 +1,146 @@
+# session-zoo
+
+[English](README.md) | [中文](README_zh.md)
+
+Save and sync your AI development sessions to GitHub.
+
+`session-zoo` automatically discovers sessions from AI coding tools (Claude Code, Codex, etc.), generates AI summaries, and syncs everything to a GitHub repo — raw data preserved for cross-device migration, plus readable Markdown for review.
+
+<p align="center">
+  <img src="docs/demo.gif" alt="session-zoo demo" width="700">
+</p>
+
+## Features
+
+- **Auto-discover** sessions from `~/.claude/` (Claude Code adapter built-in)
+- **AI Summarize** using existing Claude/Codex CLI (no API key needed) or Anthropic API
+- **Git Sync** raw JSONL + metadata + Markdown summaries to GitHub
+- **Cross-device restore** — clone on a new machine, restore sessions to `~/.claude/` for `/resume`
+- **Tag & Search** sessions by project, tool, date, or custom tags
+- **Extensible** adapter pattern — easy to add support for new AI tools
+
+## Quick Start
+
+### Install
+
+```bash
+pip install session-zoo
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/AndsGo/session-zoo.git
+cd session-zoo
+pip install -e .
+```
+
+### Setup
+
+```bash
+# Initialize
+zoo init
+
+# Set your GitHub repo for syncing (create an empty repo first)
+zoo config set repo git@github.com:yourname/my-sessions.git
+```
+
+### Basic Workflow
+
+```bash
+# Import sessions from Claude Code
+zoo import
+
+# List all sessions
+zoo list
+
+# View session details
+zoo show <session-id>
+zoo show <session-id> --markdown
+
+# Generate AI summary (uses installed claude/codex CLI automatically)
+zoo summarize <session-id>
+
+# Tag sessions for organization
+zoo tag <session-id> bugfix security
+
+# Sync everything to GitHub
+zoo sync
+```
+
+### Cross-Device Restore
+
+On a new machine:
+
+```bash
+zoo init
+zoo config set repo git@github.com:yourname/my-sessions.git
+zoo clone      # Clone the session repo
+zoo reindex    # Rebuild local index from repo
+zoo restore    # Restore .jsonl files to ~/.claude/ for /resume
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `zoo init` | Initialize configuration |
+| `zoo config show/set` | View or set config (repo, ai-key, ai-model) |
+| `zoo import` | Import new sessions from AI tools |
+| `zoo list` | List sessions (filter by --project, --tool, --tag, --since) |
+| `zoo show <id>` | Show session details (--raw, --markdown) |
+| `zoo search <query>` | Search sessions by summary content |
+| `zoo tag <id> [tags...]` | Add/remove tags |
+| `zoo tags` | List all tags with counts |
+| `zoo delete <id>` | Delete a session from index |
+| `zoo summarize [id]` | Generate AI summaries (--provider auto/claude-code/codex/api) |
+| `zoo sync` | Sync sessions to GitHub (--dry-run) |
+| `zoo clone` | Clone session repo to local |
+| `zoo reindex` | Rebuild SQLite index from repo |
+| `zoo restore` | Restore session files to tool directories |
+
+## Summarization Providers
+
+`zoo summarize` supports multiple providers, auto-detected by priority:
+
+1. **claude-code** — Uses installed `claude -p` CLI (no API key needed)
+2. **codex** — Uses installed `codex -q` CLI (no API key needed)
+3. **api** — Uses Anthropic API directly (requires `zoo config set ai-key <key>`)
+
+```bash
+# Auto-detect (uses whatever is available)
+zoo summarize <id>
+
+# Force a specific provider
+zoo summarize --provider claude-code <id>
+zoo summarize --provider api <id>
+```
+
+## GitHub Repo Structure
+
+```
+your-sessions-repo/
+├── raw/claude-code/my-project/
+│   ├── <session-id>.jsonl          # Raw session data (preserved as-is)
+│   └── <session-id>.meta.json     # Metadata (tags, summary, cwd)
+└── sessions/my-project/2026-03-10/claude-code/
+    └── <session-id>.md            # Readable Markdown summary
+```
+
+## Adding Adapters
+
+session-zoo uses an adapter pattern to support different AI tools. Currently supported:
+
+- **Claude Code** (`~/.claude/projects/`)
+
+To add a new adapter, implement `discover()`, `parse()`, and `get_restore_path()`. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Requirements
+
+- Python 3.12+
+- Git
+- (Optional) `claude` or `codex` CLI for summarization without API key
+
+## License
+
+[MIT](LICENSE)

session_zoo-0.1.0/README_zh.md

@@ -0,0 +1,146 @@
+# session-zoo
+
+[English](README.md) | [中文](README_zh.md)
+
+将你的 AI 开发会话保存并同步到 GitHub。
+
+`session-zoo` 自动发现 AI 编程工具（Claude Code、Codex 等）的会话记录，生成 AI 摘要，并将所有数据同步到 GitHub 仓库 —— 原始数据完整保留以便跨设备迁移，同时生成可读的 Markdown 方便回顾。
+
+<p align="center">
+  <img src="docs/demo.gif" alt="session-zoo 演示" width="700">
+</p>
+
+## 特性
+
+- **自动发现** `~/.claude/` 下的会话（内置 Claude Code 适配器）
+- **AI 摘要** 直接使用已安装的 Claude/Codex CLI（无需 API key），也支持 Anthropic API
+- **Git 同步** 原始 JSONL + 元数据 + Markdown 摘要同步到 GitHub
+- **跨设备恢复** — 在新设备 clone 后恢复会话到 `~/.claude/`，支持 `/resume`
+- **标签与搜索** 按项目、工具、日期或自定义标签管理会话
+- **可扩展** 适配器模式，轻松添加新工具支持
+
+## 快速开始
+
+### 安装
+
+```bash
+pip install session-zoo
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/AndsGo/session-zoo.git
+cd session-zoo
+pip install -e .
+```
+
+### 初始化
+
+```bash
+# 初始化配置
+zoo init
+
+# 设置 GitHub 仓库（需先创建一个空仓库）
+zoo config set repo git@github.com:yourname/my-sessions.git
+```
+
+### 基本用法
+
+```bash
+# 导入 Claude Code 会话
+zoo import
+
+# 查看所有会话
+zoo list
+
+# 查看会话详情
+zoo show <session-id>
+zoo show <session-id> --markdown
+
+# 生成 AI 摘要（自动使用已安装的 claude/codex CLI）
+zoo summarize <session-id>
+
+# 添加标签
+zoo tag <session-id> bugfix security
+
+# 同步到 GitHub
+zoo sync
+```
+
+### 跨设备恢复
+
+在新设备上：
+
+```bash
+zoo init
+zoo config set repo git@github.com:yourname/my-sessions.git
+zoo clone      # 克隆会话仓库
+zoo reindex    # 从仓库重建本地索引
+zoo restore    # 恢复 .jsonl 文件到 ~/.claude/ 以支持 /resume
+```
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `zoo init` | 初始化配置 |
+| `zoo config show/set` | 查看或设置配置（repo, ai-key, ai-model） |
+| `zoo import` | 从 AI 工具导入新会话 |
+| `zoo list` | 列出会话（支持 --project, --tool, --tag, --since 筛选） |
+| `zoo show <id>` | 查看会话详情（--raw 原始数据, --markdown 渲染） |
+| `zoo search <query>` | 按摘要内容搜索 |
+| `zoo tag <id> [tags...]` | 添加/删除标签 |
+| `zoo tags` | 列出所有标签及数量 |
+| `zoo delete <id>` | 删除会话 |
+| `zoo summarize [id]` | 生成 AI 摘要（--provider auto/claude-code/codex/api） |
+| `zoo sync` | 同步到 GitHub（--dry-run 预览） |
+| `zoo clone` | 克隆会话仓库到本地 |
+| `zoo reindex` | 从仓库重建 SQLite 索引 |
+| `zoo restore` | 恢复会话文件到工具目录 |
+
+## 摘要生成
+
+`zoo summarize` 支持多种方式，按优先级自动检测：
+
+1. **claude-code** — 使用已安装的 `claude -p` CLI（无需 API key）
+2. **codex** — 使用已安装的 `codex -q` CLI（无需 API key）
+3. **api** — 直接调用 Anthropic API（需 `zoo config set ai-key <key>`）
+
+```bash
+# 自动检测
+zoo summarize <id>
+
+# 指定方式
+zoo summarize --provider claude-code <id>
+zoo summarize --provider api <id>
+```
+
+## GitHub 仓库结构
+
+```
+your-sessions-repo/
+├── raw/claude-code/my-project/
+│   ├── <session-id>.jsonl          # 原始会话数据（完整保留）
+│   └── <session-id>.meta.json     # 元数据（标签、摘要、工作目录）
+└── sessions/my-project/2026-03-10/claude-code/
+    └── <session-id>.md            # 可读的 Markdown 摘要
+```
+
+## 添加适配器
+
+session-zoo 使用适配器模式支持不同的 AI 工具。目前支持：
+
+- **Claude Code** (`~/.claude/projects/`)
+
+添加新适配器需实现 `discover()`、`parse()` 和 `get_restore_path()` 方法。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 环境要求
+
+- Python 3.12+
+- Git
+- （可选）`claude` 或 `codex` CLI 用于无 API key 的摘要生成
+
+## 许可证
+
+[MIT](LICENSE)