Tool: migrate Freebuff CLI chat history into the Desktop app

[AnonBOTpl]

---

Hi! I built a small, dependency-free Python tool that migrates chat history from
the Freebuff CLI era into the Freebuff Desktop database, and I'd like to
offer it to the project.

Repo: https://github.com/AnonBOTpl/freebuff-history-migrator
Status: ✅ Tested and working — 6 projects, 1336 messages, 3399 tool calls imported successfully

What it does

The old CLI stored each conversation as JSON under
~/.config/manicode/projects/<Project>/chats/<timestamp>/chat-messages.json.
The Desktop app stores history in a SQLite DB (.freebuff/desktop-v2.db, tables
projects → threads → messages). This tool converts one into the other:

CLI	Desktop
project folder	projects row (id = resolved root path)
chats/<timestamp>/	threads row (id = deterministic uuid5 of the chat path → re-runs never duplicate)
message variant: "user"	role = user, part {"kind": "text"}
block text (textType: "reasoning")	part {"kind": "reasoning", "collapse": "preview"}
block tool	part {"kind": "tool", id, toolName, input} (output dropped by default, --tool-output-max N keeps a trimmed copy)
mode-divider / unknown blocks	dropped

Safety features

• --dry-run previews everything without writing
• automatic WAL-safe backup via the SQLite backup API before any write
• idempotent (deterministic thread ids) — running it twice imports nothing twice
• foreign-key-safe (project rows created before threads), works under
  PRAGMA foreign_keys = ON
• nothing from the private DB is ever touched unless you run the full import

Quick usage

# Preview mode — see what will be imported without writing
python import_cli_history.py --dry-run

# Full import (automatically backs up the Desktop database)
python import_cli_history.py

# Single project (faster for large CLI histories)
python import_cli_history.py --project anon-chat-mod

# Keep tool outputs trimmed to 2000 chars (default drops them)
python import_cli_history.py --tool-output-max 2000

Requirements: Python 3.8+, standard library only (zero external dependencies).
Full documentation: See README in the repo.

Why it might be worth integrating

With the CLI → Desktop transition, many users will have history stranded in the
old format. This could be shipped as an official migration path, e.g.:

• a freebuff/CLI command or a one-time onboarding step in the Desktop app that
  auto-detects ~/.config/manicode/projects and offers to import,
• or a maintained script under scripts/ in this repo.

Happy to adapt the implementation (port to TypeScript/Bun, follow the internal
schema as it evolves, add tests) — just let me know where it would fit best.

---

Open questions

• Would this be valuable as an official part of the Desktop app (e.g., a "Migrate from CLI" onboarding step)?
• Should it live in scripts/ of the main repo, as a community tool, or integrated directly into Desktop?

@CodebuffAI — Would appreciate your thoughts on where this fits best! 🙏