Skip to content

Commit b88f526

Browse files
author
Kimi Claw
committed
docs: fix docs to match actual MVP code
- Remove manifest.json references (not implemented in code) - Soften OpenClaw compatibility claim to 'can be placed for reference' - Rewrite README.ru.md with accurate commands, paths and behaviour - Add Python 3.9 workaround note consistently - Remove obsolete references to ~/.claude/sessions/, --encrypt, cron
1 parent 13968a2 commit b88f526

2 files changed

Lines changed: 129 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ tests/
180180

181181
## OpenClaw users
182182

183-
Exports are compatible with OpenClaw's `memory/` format. Drop exported `.md` files into your `~/.openclaw/workspace/memory/` directory and your new agent retains project context.
183+
Exported `.md` files can be placed in `~/.openclaw/workspace/memory/` for reference. OpenClaw's `memory_search` will index the content, though the frontmatter fields differ from native OpenClaw memory format.
184184

185185
---
186186

‎README.ru.md‎

Lines changed: 128 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@
22

33
> Экспортируй сессии Claude Code, память и настройки в локальные Markdown-файлы — чтобы сохранить работу, даже если Anthropic заблокирует аккаунт.
44
5+
[English](README.md) · Русский
6+
57
---
68

79
## Зачем
810

9-
Claude Code хранит всё в `~/.claude/`. Сессии, контекст проектов, кастомные инструкции, память. Всё это живёт на серверах Anthropic и в локальном кеше, который ты не контролируешь.
11+
Claude Code хранит всё в `~/.claude/`. Сессии, контекст проекта, кастомные инструкции, память. Всё это живёт на серверах Anthropic и в локальном кеше, который вы не контролируете.
1012

11-
**Если аккаунт заблокируют, ограничат или потеряешь OAuth-доступ — вся память о проектах пропадает.**
13+
**Если аккаунт заблокируют, ограничат по rate limit или потеряете доступ к OAuth — память проекта исчезнет.**
1214

1315
> *"Купил подписку Claude Max 5x, прилетела блокировка. Ощущение, как-будто лучшего друга и напарника потерял..."*
1416
> — Реальный пользователь, май 2026
@@ -19,79 +21,172 @@ Claude Code хранит всё в `~/.claude/`. Сессии, контекст
1921

2022
## Реальные истории
2123

22-
Claude нанял стороннюю компанию для верификации пользователей. Они ошиблись и **массово отметили легальные аккаунты** как подозрительные — включая платящих пользователей, которые ничего не нарушали.
24+
Claude нанял стороннюю компанию для верификации. Они ошиблись и **массово отметили легитимные аккаунты** — включая платящих пользователей, которые ничего не нарушали.
2325

2426
> *"Claude нанял специальную компанию для проверки пользователей. Похоже компания ошиблась и массово отметила как левые множество реально нормальных и чистых аккаунтов. Увы, но разбираться будут долго."*
2527
26-
Пользователи, которые платили через нестандартные каналы или использовали VPN, пострадали больше всего. Апелляции занимают месяцы. А тем временем **месяцы проектного контекста исчезают**.
28+
Пользователи, оплатившие через нестандартные каналы или использовавшие VPN, пострадали больше всего. Апелляции занимают месяцы. При этом **месяцы проектного контекста испаряются**.
2729

2830
> *"Я использую клод для бэкенда, в основном. Бесплатная версия с таким объемом задач не справится. Да, оплатил окольными путями — может быть из-за этого + vpn detect."*
2931
3032
**claude-backup не предотвращает баны. Он предотвращает амнезию.**
3133

3234
---
3335

34-
## Что делает
36+
## Быстрый старт
37+
38+
```bash
39+
git clone https://github.com/parallelclaw/claude-backup.git
40+
cd claude-backup
41+
pip install -e .
42+
```
43+
44+
```bash
45+
# Посмотреть, что есть
46+
claude-backup list
47+
48+
# Экспортировать одну сессию
49+
claude-backup export abc-123 --output ~/claude-backups/
3550

36-
- Сканирует `~/.claude/sessions/` и экспортирует каждый разговор в датированный `.md` файл
37-
- Извлекает проектную память и инструкции в формат `memory/`
38-
- Бэкапит метаданные кредов (не секреты — указатели и конфиг)
39-
- Опционально шифрует экспорты через `gpg` перед записью на диск
40-
- Работает по cron: ежедневные автоматические бэкапы, о которых можно забыть
51+
# Экспортировать всё
52+
claude-backup export-all --output ~/claude-backups/
53+
```
54+
55+
Новым пользователям: см. [QUICKSTART.md](./QUICKSTART.md) — полная пошаговая инструкция (macOS, Linux, Windows/WSL).
4156

4257
---
4358

4459
## Установка
4560

61+
Требуется **Python 3.10+** (CI тестирует 3.10, 3.11, 3.12).
62+
4663
```bash
47-
pip install claude-backup
64+
pip install -e .
4865
```
4966

50-
Или клонируй и запусти напрямую:
67+
> **Примечание:** Если у вас Python 3.9, установка возможна с `pip install -e . --ignore-requires-python`. Код использует `from __future__ import annotations` и работает на 3.9, но официальная поддержка — 3.10+.
68+
69+
---
70+
71+
## Использование
72+
73+
### Список сессий
5174

5275
```bash
53-
git clone https://github.com/parallelclaw/claude-backup.git
54-
cd claude-backup
55-
python -m claude_backup --help
76+
claude-backup list
5677
```
5778

58-
---
79+
Выводит таблицу:
5980

60-
## Быстрый старт
81+
```
82+
Project Session ID First Prompt Msg Count Created Git Branch
83+
───────── ────────────────────── ─────────────────── ───────── ─────────────────── ──────────
84+
my-webapp abc-123 fix auth bug 42 2026-05-07T10:42:00Z main
85+
my-webapp def-456 add unicode support 18 2026-05-06T14:00:00Z feature/unicode
86+
```
87+
88+
### Экспорт одной сессии
89+
90+
```bash
91+
claude-backup export abc-123 --output ./backups/
92+
```
93+
94+
Создаёт `./backups/2026-05-07--abc-123.md`.
95+
96+
### Экспорт всего
97+
98+
```bash
99+
claude-backup export-all --output ./backups/
100+
```
101+
102+
Каждый проект получает свою поддиректорию в `--output`.
103+
104+
### Кастомный путь к Claude
105+
106+
Переопределить стандартный `~/.claude/projects/`:
61107

62108
```bash
63-
# Одноразовый экспорт
64-
claude-backup export ~/claude-backups/
109+
claude-backup --claude-home /path/to/projects list
110+
```
111+
112+
---
113+
114+
## Формат вывода
115+
116+
Каждая сессия сохраняется как Markdown с YAML frontmatter:
117+
118+
```markdown
119+
---
120+
project: my-webapp
121+
session_id: abc-123
122+
branch: main
123+
model: claude-sonnet-4
124+
messages: 42
125+
exported_at: 2026-05-07T15:30:00Z
126+
---
127+
128+
# my-webapp / main / abc-123
65129

66-
# С шифрованием
67-
claude-backup export ~/claude-backups/ --encrypt --gpg-key your@email.com
130+
## User (10:42:46)
131+
fix auth bug
68132

69-
# Настроить ежедневный cron
70-
claude-backup cron --daily ~/claude-backups/
133+
## Assistant (10:42:50)
134+
Here's the fix...
71135
```
72136

73137
---
74138

75-
## Что экспортируется
139+
## Поведение
140+
141+
- **Graceful degradation** — пустые или повреждённые `.jsonl` пропускаются с warning'ом. Утилита никогда не падает на битых данных.
142+
- **Orphan-сессии** — сессии, найденные через `.jsonl`, но отсутствующие в `sessions-index.json`, всё равно экспортируются (с минимальными метаданными).
143+
- **Ghost-записи** — сессии в индексе без файла `.jsonl` на диске отображаются в списке, но не экспортируются.
144+
- **Отсутствующий `~/.claude/`** — выход с кодом 1 и понятным сообщением об ошибке.
145+
- **Unicode** — корректно обрабатывает русский, emoji и спецсимволы.
146+
- **Tool-aware** — сохраняет блоки `tool_use` / `tool_result` в читаемом Markdown.
147+
148+
---
149+
150+
## Разработка
151+
152+
```bash
153+
pip install -e ".[dev]"
154+
pytest -v --cov=claude_backup
155+
```
156+
157+
CI запускается на Python 3.10, 3.11 и 3.12 — см. [.github/workflows/test.yml](.github/workflows/test.yml).
158+
159+
**Покрытие тестами: 93%** (42/42 тестов проходят).
76160

77-
| Источник | Куда | Содержимое |
78-
|----------|------|------------|
79-
| `~/.claude/sessions/` | `YYYY-MM-DD/session-{id}.md` | Полная история разговоров |
80-
| `~/.claude/.credentials.json` | `credentials-meta.json` | Указатели на аккаунт (не ключи) |
81-
| `~/.claude/settings.json` | `settings-backup.json` | Кастомные инструкции и настройки |
82-
| `~/.claude/memory/` | `memory/` | Долгосрочный проектный контекст |
161+
### Структура проекта
162+
163+
```
164+
claude_backup/
165+
├── __init__.py
166+
├── cli.py # Точка входа Click
167+
├── scanner.py # Обнаружение проектов и сессий
168+
├── parser.py # Чтение .jsonl
169+
└── exporter.py # Рендеринг Markdown
170+
171+
tests/
172+
├── fixtures/ # Фейковые данные — реальные ~/.claude/ не читаются в тестах
173+
├── test_scanner.py
174+
├── test_parser.py
175+
├── test_exporter.py
176+
└── test_cli.py
177+
```
83178

84179
---
85180

86-
## Для пользователей OpenClaw
181+
## Пользователям OpenClaw
87182

88-
Экспорты совместимы с форматом `memory/` OpenClaw. Перенеси `claude-backup/memory/` в `~/.openclaw/workspace/memory/` — и новый агент сохранит весь проектный контекст.
183+
Экспортированные `.md` файлы можно разместить в `~/.openclaw/workspace/memory/` для справки. `memory_search` OpenClaw проиндексирует содержимое, хотя поля frontmatter отличаются от нативного формата OpenClaw.
89184

90185
---
91186

92187
## Предупреждение
93188

94-
Этот инструмент читает директорию данных Claude Code. Он **ничего не отправляет на внешние серверы**. Всё остаётся локально. Если используешь `--encrypt`, даже бэкапы на диске защищены.
189+
Этот инструмент читает директорию данных Claude Code. Он **не отправляет ничего на внешние серверы**. Всё остаётся локально.
95190

96191
---
97192

0 commit comments

Comments
 (0)