hoangsonww / hoangsonww/Claude-Code-Agent-Monitor
Feature: Local-first backup, restore, and sync workflow
- Dominant language
- TypeScript
- Stars
- 1k
- Forks
- 234
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 18
Description
## Summary
Add a local-first sync, backup, and restore workflow so users can move dashboard state between machines, recover from database loss, and optionally keep multiple installs up to date without running a central hosted service.
## Problem / Opportunity
The project already supports JSON export, cleanup, import of Claude history, and operational backup guidance. Those are useful primitives, but they do not provide an end-to-end product workflow for preserving dashboard state, restoring it onto a fresh install, or reconciling data collected on multiple developer machines.
Claude Code users often work across laptops, desktops, containers, and remote dev boxes. A monitoring platform is more valuable when sessions, cost history, pricing rules, dashboard runs, and user settings can be backed up and restored predictably while preserving the repository's local-first posture.
## Proposed Feature
Create a guided backup/restore and optional sync workflow built around signed manifest files and idempotent merge semantics. The feature should produce portable bundles, validate them before import, show a dry-run diff, and merge records without duplicating sessions, agents, events, token usage, pricing rules, or dashboard run history.
## Scope
- Add a backup bundle format containing a manifest, schema version, export metadata, database records, and optional compressed payload chunks for large event sets.
- Add restore endpoints that validate a bundle, report compatibility, show a dry-run summary, and then apply an idempotent merge.
- Support conflict handling for mutable records such as model pricing and settings with clear choices: keep local, use incoming, or duplicate as a named profile where appropriate.
- Add a Settings UI flow for creating backups, validating uploads, previewing restore impact, and tracking restore progress over WebSocket.
- Add optional local sync targets such as a user-selected folder, network-mounted directory, or Git-ignored backup folder, with manual and scheduled runs.
- Include MCP/CLI affordances so agents can trigger backup status checks and create backups under explicit configuration gates.
- Document the bundle format, compatibility policy, and recovery procedure.
## Acceptance Criteria
- [ ] Users can create a portable backup bundle from Settings that includes sessions, agents, events, token usage, model pricing, dashboard runs, and relevant non-secret dashboard settings.
- [ ] Users can upload or select a backup bundle and see a dry-run summary before any database mutation occurs.
- [ ] Restore is idempotent: reapplying the same bundle does not duplicate sessions, events, agents, token rows, or dashboard runs.
- [ ] Restore preserves active local data unless the user explicitly chooses a conflict strategy for mutable settings/pricing records.
- [ ] Large backups stream progress over WebSocket and do not block the server event loop for long-running imports.
- [ ] Backup and restore operations are covered by server tests for schema versioning, corrupt manifests, partial bundles, duplicate records, and conflict handling.
- [ ] Documentation explains how this differs from raw JSON export and how to recover a fresh install from a bundle.
## Non-Goals
- Building a hosted cloud sync service.
- Real-time multi-writer replication.
- Syncing raw Claude Code transcript files outside the dashboard's own persisted records.
- Storing secrets or unredacted Claude configuration in backup bundles.
## Dependencies / Risks
- Merge semantics need to respect existing SQLite constraints and future schema migrations.
- Large event tables may require chunked export/import and progress reporting to avoid memory spikes.
- Sync targets must stay explicit and local-first to avoid surprising data exfiltration.
## Open Questions
- Should scheduled backups be disabled by default and gated behind an explicit local path selection?
- Should backup bundles be optionally encrypted with a user-provided passphrase?
- Should restore support selective scopes, such as only pricing/settings or only sessions within a date range?
Contributor guide
Assessment
This issue has not been assessed yet.