Skip to content

ThinkInAIXYZ/deepchat / .agents/skills/deepchat-data-import

deepchat-data-import

Verified

Help developers build third-party tools that import, inspect, migrate, or analyze DeepChat data. Use when Codex needs to work with DeepChat provider configuration, model configuration, MCP/app settings, sessions, messages, legacy chat data, `agent.db`, `chat.db`, SQLCipher encrypted SQLite, Electron safeStorage wrapped passwords, Tauri importers, or native macOS/Windows/Linux data access.

FileKindSize
SKILL.mdskill md3.0 KB
agents/openai.yamlconfig280 B
references/data-locations.mdmarkdown2.7 KB
references/import-recipes.mdmarkdown4.9 KB
references/schema-reference.mdmarkdown7.7 KB
references/sqlite-access.mdmarkdown5.0 KB

references/import-recipes.md

View on GitHub
# Import Recipes

Use this reference when turning DeepChat data into an importer or migration tool.

## Native Sessions

For a readable transcript, use DeepChat's session export. For an import that needs raw events,
attachments, or restorable history, keep the version 3 backup with its native payload. Restore
with DeepChat, then read through the app's export or native history interfaces. A copied
`agent.db` alone may only contain a projection for sessions with a `dim_session_bindings` row.

## Read-Only App Data And Legacy Transcript Export

1. Locate and snapshot `agent.db`.
2. Open it with the flow in `sqlite-access.md`.
3. Read provider config from `providers`, `provider_models`, `model_status`, and `model_configs`.
4. Read sessions with:

```sql
SELECT ns.*, ds.*
FROM new_sessions ns
LEFT JOIN deepchat_sessions ds ON ds.id = ns.id
WHERE ns.session_kind = 'regular'
ORDER BY ns.updated_at DESC, ns.id DESC;
```

5. Read messages per session:

```sql
SELECT *
FROM deepchat_messages
WHERE session_id = ?
ORDER BY order_seq ASC, id ASC;
```

6. Hydrate user messages from `deepchat_user_messages`, `deepchat_user_message_files`, and
   `deepchat_user_message_links`.
7. Hydrate assistant messages from `deepchat_assistant_blocks`; fall back to parsing
   `deepchat_messages.content`.
8. Export to the target app's format, redacting secrets unless the user explicitly chooses to
   include them.

## Provider Config Import

When importing providers into another tool, preserve:

- provider id, name, API type, base URL, enabled flag, custom flag.
- API key and OAuth token only with explicit user consent.
- capability provider id for model capability lookup.
- model rows from `provider_models`, split by `source`.
- enabled/disabled state from `model_status`.
- model config from `model_configs.config_json`.

Do not rely only on `provider_json`; DeepChat deliberately stores common scalar fields in columns
for queryability and migration.

## Session And Message Import

Recommended target shape:

```json
{
  "session": {
    "id": "session-id",
    "title": "Session title",
    "agentId": "deepchat",
    "projectDir": "/path/to/project",
    "providerId": "openai",
    "modelId": "gpt-4.1",
    "createdAt": 1770000000000,
    "updatedAt": 1770000000000
  },
  "messages": [
    {
      "id": "message-id",
      "orderSeq": 1,
      "role": "user",
      "status": "sent",
      "content": {
        "text": "hello",
        "files": [],
        "links": [],
        "search": false,
        "think": false
      },
      "metadata": {},
      "createdAt": 1770000000000,
      "updatedAt": 1770000000000
    }
  ]
}
```

For assistant messages, keep the assistant block array when possible instead of flattening to text.
Tool calls, tool responses, reasoning blocks, image data, action prompts, and error blocks may all
be represented as assistant blocks.

## Handling Partial Or Old Rows

- If structured user rows are missing, parse `deepchat_messages.content`.
- If structured assistant blocks are missing, parse `deepchat_messages.content`.
- If `new_sessions` is missing but `conversations` exists, import through the legacy path.
- If `agent.db` is missing and `chat.db` exists, open `chat.db` as legacy data.
- If a column is missing, check `schema_versions` and use the nearest fallback rather than failing
  the whole import.

## Writing Back Into DeepChat

Avoid third-party direct writes to a user's live DeepChat database.

If a tool must generate data for DeepChat:

- Prefer creating an export file or backup package that DeepChat can import through its own code.
- If implementing inside DeepChat, use the owning session and provider services.
- For a controlled legacy migration fixture, use one transaction per session and keep table
  groups consistent:
  - `new_sessions`
  - `deepchat_sessions`
  - `deepchat_messages`
  - structured user or assistant tables
  - optional search, trace, usage, pending input, and tape rows
- Keep `deepchat_messages.content` compatible even when structured tables are populated, because it
  remains the fallback path.
- Do not update `database-security.json` manually after rekeying; use DeepChat's migration flow.

## Secret Handling Checklist

Redact or require explicit opt-in for:

- `providers.api_key`
- OAuth tokens in `providers.provider_json`
- MCP server `env` and custom headers
- `app_settings` rows marked `sensitive = 1`
- `deepchat_message_traces.headers_json` and `body_json`
- file paths in user message files
- chat content, system prompts, summaries, and project paths

## Useful Consistency Checks

Run these after import from a copied database:

```sql
PRAGMA quick_check;

SELECT COUNT(*) FROM new_sessions;
SELECT COUNT(*) FROM deepchat_sessions;
SELECT COUNT(*) FROM deepchat_messages;

SELECT m.session_id
FROM deepchat_messages m
LEFT JOIN new_sessions s ON s.id = m.session_id
WHERE s.id IS NULL
LIMIT 20;
```

For encrypted databases, validate the password before any import work:

```sql
SELECT name FROM sqlite_master LIMIT 1;
```
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall