aibackup-skill
JeffShanCha/aibackup-skill
用于claude、codex、chatgpt等多端数据备份的 skill ,防止多年账号数据丢失做备份处理。
Instalação
npx convez-ai JeffShanCha/aibackup-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
AIBackup Skill
Automatically back up your AI conversations — ChatGPT, Claude, Codex, Claude Code —
into a local AI_Backup repository you own. Markdown + HTML + JSON, searchable,
with secrets redacted before anything is written to disk.
Core principle: Archive First, Knowledge Later. The full conversation is always saved first. Summaries and knowledge extraction are optional layers that can fail without ever losing the original session.
Contents
- What it backs up
- Quick Start
- Let an AI assistant install it
- How it works
- Storage layout
- Browser extension (Web backup)
- CLI backup (Codex / Claude Code)
- Desktop backup (ChatGPT / Claude / Codex apps)
- MCP server
- Command reference
- Security
- Project structure
- Troubleshooting
- Requirements
What it backs up
| Surface | Sources | How |
|---|---|---|
| Web | ChatGPT Web, Claude Web | Chrome/Edge extension → local service |
| CLI | Codex CLI, Claude Code CLI | Wrapper, transparent hooks, or passive transcript monitor |
| Desktop | ChatGPT / Claude / Codex desktop apps | Background monitor with non-intrusive window capture |
| Anything | Any text / Markdown / HTML | aibackup import, aibackup capture, or the MCP archive_text tool |
Every capture becomes a self-contained archive folder with session-full.md,
session-full.html, and metadata.json.
Quick Start
macOS / Linux / WSL
git clone https://github.com/YOUR_USERNAME/aibackup-skill-v1
cd aibackup-skill-v1
bash installers/install.sh
aibackup setup
Windows PowerShell
git clone https://github.com/YOUR_USERNAME/aibackup-skill-v1
cd aibackup-skill-v1
powershell -ExecutionPolicy Bypass -File installers\install.ps1
aibackup setup
aibackup setup is the guided one-command onboarding. It:
- Asks where to store
AI_Backup(required — you must choose a path; there is no silent default, and an empty answer re-prompts until you enter one). - Asks which clients to back up:
web,cli,desktop, orall. - Initializes storage and starts the matching capture layers.
- If you chose
web, prints the one-time browser-extension install + verification steps.
Non-interactive form (used by scripts and AI assistants):
aibackup setup --path ~/Documents/AI_Backup --sources all --yes
Verify any time:
aibackup status
aibackup storage
Let an AI assistant install it
In Claude Code or Codex, just say:
请帮我安装 skill: https://github.com/YOUR_USERNAME/aibackup-skill-v1
The assistant clones the repo, runs the installer, and confirms aibackup --version.
Then say:
AI 备份
It asks for your storage path and which clients to back up, runs
aibackup setup, and walks you through the browser extension if needed.
The exact behavior the assistant follows is defined in the
AI Invocation Convention section of SKILL.md.
How it works
V1 automatic backup is delivered by four capture layers plus an MCP layer for AI-assisted installation and tool use:
Browser Extension ─┐
CLI Wrapper/Monitor ─┤
Desktop Monitor ─────┼──► Local Service (127.0.0.1:8765) ──► AI_Backup/
MCP / direct CLI ────┘ (md + html + json)
SKILL.md carries installation guidance and the AI invocation rules; it does not
capture data by itself.
Storage layout
You choose the storage root during aibackup setup. Suggested paths:
- macOS / Linux / WSL:
~/Documents/AI_Backup - Windows:
D:\AI_Backup(if a D: drive exists), otherwise~/Documents/AI_Backup
AI_Backup/
Projects/ Sources/ Archives/ Assets/
Metadata/ Config/ Logs/ _index/
Each archive:
Archives/YYYY/MM/YYYYMMDD-HHMMSS-title/
session-full.md # always written
session-full.html # always written
metadata.json # always written
session-summary.md # optional knowledge layer
knowledge.md # optional knowledge layer
outputs/ changes/ assets/
The same conversation updates the same archive folder when a conversation_id is
provided, so continuing a chat does not create scattered duplicates.
Browser extension (Web backup)
- Make sure the local service is running (started for you by
aibackup setup, or manually withaibackup auto start). - Open
chrome://extensions(oredge://extensions). - Enable Developer mode (top-right).
- Click Load unpacked and select the extension folder:
- From a clone:
<repo>/browser-extension - After install:
~/.aibackup-skill/browser-extension
- From a clone:
- Open the extension popup and confirm it shows
AIBackup Service: Connected. - Open ChatGPT or Claude and send a test message, then run
aibackup storageto confirm the archive count increased.
The extension supports ChatGPT Web and Claude Web, saves incrementally after each turn, and keeps a local retry queue if the service is temporarily offline. Configure ChatGPT/Claude enablement, default project, account label, and service address in the extension's options page.
CLI backup (Codex / Claude Code)
Wrapper — launch through aibackup and capture the whole session:
aibackup run codex
aibackup run claude
aibackup run --cwd /path/to/project codex
Transparent hooks — keep typing codex / claude as usual:
aibackup hook install
aibackup hook status
aibackup hook uninstall
Passive monitor — no wrappers, no hooks; just import local transcripts as they change:
aibackup auto start # local service + passive codex/claude transcript monitor
aibackup sync # one-off import of existing transcripts
aibackup codex import-latest
aibackup claude import-latest
The passive monitor is read-only: it does not wrap, modify, or download codex
/ claude, and it does not touch your PATH or packages. It stores a dialogue-only
view (user/assistant text) and omits token, cache, cost, and model accounting fields.
Wrapper archives additionally include:
command-history.md
errors.md # when stderr or a non-zero exit is captured
changes/diff.patch # git diff, or a created/modified/deleted summary for non-git dirs
changes/files.json
Desktop backup (ChatGPT / Claude / Codex apps)
The desktop apps store conversations in encrypted/binary formats (ChatGPT: encrypted
.data; Claude & Codex: LevelDB) that cannot be read directly. AIBackup instead
watches their activity-indicator files and captures the visible window when a new
conversation is detected.
aibackup desktop scan # detect apps, data format, activity files
aibackup desktop monitor start # passive background auto-backup (default)
aibackup desktop monitor status
aibackup desktop monitor stop
Capture modes (non-intrusive by design)
passive(default) — captures only while the app is already in the foreground. If you switch to another app, capture is deferred and resumes when you return — it will never pull you back to the AI client.active(aibackup desktop monitor start --mode active) — briefly switches to the app to capture, then restores focus to whatever you were using.
After each capture the select-all highlight is collapsed and your clipboard is
restored by default (--no-restore-clipboard to opt out).
One-shot fallbacks:
aibackup desktop capture-window --app chatgpt # macOS/Windows window automation
aibackup desktop capture-clipboard --app chatgpt # archive copied text, any platform
macOS requires Accessibility permission for your terminal: System Settings → Privacy & Security → Accessibility → add Terminal. Windows: run from a standard (non-elevated) prompt.
MCP server
Expose AIBackup to Claude Code as MCP tools:
claude mcp add aibackup -- python3 ~/.aibackup-skill/mcp-server/server.py
Restart your Claude Code session, then the assistant can call:
| Tool | Purpose |
|---|---|
aibackup_init | Initialize storage and config (path optional). |
aibackup_status | Report OS, storage path, and config status. |
aibackup_storage | Report archive count and total size. |
aibackup_search | Search archived conversations by keyword. |
aibackup_archive_text | Archive any text/conversation content directly. |
aibackup_service_status | Check whether the local service is running. |
aibackup_desktop_scan | Detect installed desktop AI clients. |
The MCP SDK (mcp) is installed automatically by the installer; to add it manually:
pip install -r ~/.aibackup-skill/mcp-server/requirements.txt.
Command reference
aibackup --version
aibackup setup # guided onboarding (recommended)
aibackup init # initialize storage only
aibackup status
aibackup storage
aibackup storage-report
aibackup service start|status|stop
aibackup auto start|status|stop|install|uninstall
aibackup import <file> --source chatgpt-web --project Demo
aibackup capture --source claude-desktop --title "Copied conversation"
aibackup search "keyword"
aibackup run codex
aibackup run claude
aibackup hook install|status|uninstall
aibackup sync
aibackup monitor start|status|stop|install|uninstall
aibackup codex scan|import-latest|import-all
aibackup claude scan|import-latest|import-all
aibackup desktop scan
aibackup desktop monitor start|status|stop
aibackup desktop capture-window --app <chatgpt|claude|codex>
aibackup desktop capture-clipboard --app <chatgpt|claude|codex>
ai-archive remains as a compatibility alias for aibackup.
Local service API
Base URL http://127.0.0.1:8765 (localhost only):
GET /statusGET /storageGET /search?q=keywordPOST /archive
{
"source": "chatgpt-web",
"account": "personal",
"project": "auto",
"title": "auto",
"messages": [
{ "role": "user", "content": "Hello" },
{ "role": "assistant", "content": "Hi" }
],
"conversation_id": "chatgpt-web:https://chatgpt.com/c/...",
"incremental": true
}
Security
Before anything is written to disk, sensitive values are replaced with
[REDACTED_SECRET]. Covered patterns include API keys (sk-…, ghp_…,
github_pat_…, AWS AKIA…), bearer tokens, JWTs, SSH private key blocks, and
key: value style passwords / tokens / cookies / secrets. Redaction is applied to
conversation text, command output, command history, error logs, and change diffs.
All backups stay on your machine. The local service binds to 127.0.0.1 and accepts
local connections only.
Project structure
aibackup-skill-v1/
bin/ai_archive.py # the entire CLI + local service (single file)
browser-extension/ # Chrome/Edge Manifest V3 extension
mcp-server/ # MCP server + requirements.txt
desktop-adapters/ # desktop client adapter notes
installers/ # install.sh / install.ps1
scripts/ # package-release.sh and helpers
templates/ docs/ examples/
SKILL.md SPEC.md README.md
The installer copies bin/ai_archive.py, browser-extension/, and mcp-server/
into ~/.aibackup-skill/ so the install is self-contained.
Troubleshooting
aibackup: command not found— add the bin dir to PATH:export PATH="$HOME/.local/bin:$PATH"(macOS/Linux) or restart PowerShell (Windows).- Extension shows "Disconnected" — start the service (
aibackup auto start) and confirmcurl http://127.0.0.1:8765/statusreturns"status": "ok". - Desktop capture does nothing / Accessibility error (macOS) — grant Accessibility
permission to your terminal, then
aibackup desktop monitor stop && aibackup desktop monitor start. - MCP tools don't appear in Claude Code — restart the session after
claude mcp add; verify withclaude mcp list(should showaibackup ✓ Connected). - Edited
bin/ai_archive.pybutaibackupis unchanged — re-sync the installed copy:cp bin/ai_archive.py ~/.aibackup-skill/aibackup.py.
Requirements
- Python 3.8+
- macOS, Linux, WSL, or Windows
- Chrome or Edge (for Web backup)
- Claude Code (optional, for the MCP integration)