hoangsonww / hoangsonww/Claude-Code-Agent-Monitor

Feature: Local-first backup, restore, and sync workflow

Open
#149 1 comment 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation enhancement good first issue help wanted question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.