devin-doctor

Unofficial community project. Not affiliated with, endorsed by, or sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.

Linux · Personal Windows · Corporate Windows

Part of the awesome-devin ecosystem: the curated hub for the devin-* tools.

devin-doctor diagnoses a Devin Desktop installation — one command that checks the local stores, schema versions, config files and disk usage, then prints a health report with concrete fix suggestions. Read-only, always.

The problem

Devin keeps a lot of local state: a versioned sessions.db, one acp-messages/*.db per GUI session, a state.vscdb KV store, credentials.toml and JSONC config files. When any of it breaks or bloats — a schema the tooling doesn't know, a locked database, an unreadable hooks file, a 700 MiB sessions store — nothing warns you. You find out indirectly: missing history, auth errors, disk pressure.

devin-doctor is brew doctor for that installation.

Prior art

• brew doctor / flutter doctor — the genre: one command, many checks, PASS/WARN/FAIL with fix suggestions. This project adapts the pattern; it does not reinvent it.
• devin-internals-spec — provides the schema-version detector, the read-only store parsers and the fixture generator this project builds on.

What makes it Devin-native

It understands Devin's actual on-disk layout — the refinery_schema_history migration ledger, the acp-messages per-session stores, state.vscdb, and the .devin/ hooks/MCP config format — things no generic system check can see. Remove Devin and there is nothing to diagnose.

Install

Python ≥ 3.10 and pipx are required. Windows (PowerShell): install pipx with py -m pip install --user pipx, run py -m pipx ensurepath, then reopen the terminal. Linux (Debian/Ubuntu): run sudo apt install pipx python3-venv and pipx ensurepath; reopen the terminal. Other Linux distributions should install pipx using their package manager.

pipx install "devin-doctor @ git+https://github.com/Icaro0310/devin-doctor.git"

(Not published on PyPI yet; the GitHub install above is the supported route.)

Usage

devin-doctor check                    # diagnose the default data dir
devin-doctor check --data-dir D:\devin-backup
# Use a separate Devin UI config root (e.g. Linux)
devin-doctor check --data-dir ~/.local/share/devin --config-dir ~/.config/Devin
devin-doctor check --json             # machine-readable output
devin-doctor report --md              # markdown, for pasting into issues
devin-doctor capabilities             # machine capability profile, JSON

Each check prints PASS/WARN/FAIL, a one-line finding and a fix: suggestion. Exit code is 0 unless something FAILs (then 1).

The six checks:

check	reports
stores	present/missing, sizes and row counts for sessions.db, acp-messages/*.db, state.vscdb
schema	schema version vs the supported range (15–17); layout recognition for the ledger-less stores
health-of-data	empty sessions, orphan message_nodes, sessions idle > --stale-days, SQLITE_BUSY locks
config	credentials.toml presence + validity (values masked); .devin/ hooks/MCP config sanity
hooks-windows	hooks/MCP commands that would pop a visible console window on Windows (cmd /c without a hidden wrapper, powershell without -WindowStyle Hidden, direct .bat/.ps1, python.exe vs pythonw.exe) — each with file, hook event and a wrapper fix
disk	total data-dir size, largest DBs, acp-messages accumulation trend

Capability profile

devin-doctor capabilities             # JSON profile, exit 0
devin-doctor capabilities --probe-network

capabilities prints a JSON object — {"profile": ..., "capabilities": {...}} — describing what the machine can do for the ecosystem (scheduler, daemon, local LLM, containers, comms, proxy, ≥24 GiB RAM, …). The profile is corporate by default (fail-closed); personal applies only when explicitly declared via DEVIN_ECOSYSTEM_PROFILE=corporate|personal or devin-profile.json ({"profile": "personal"}) in the Devin config dir — the env var wins. All probing is local; net.outbound/net.listener stay "unknown" unless --probe-network is passed, which performs exactly ONE outbound TCP connect (1.1.1.1:443 or the configured HTTPS_PROXY, 2 s timeout) plus a loopback bind — the only network call this tool can make.

Works with Devin alone (Devin-only mode)

devin-doctor is a pure local diagnostic: it reads Devin's own data directories, writes nothing, and never contacts a network service. No VM, no Tailscale, no Ollama, no Slack — just Devin Desktop plus Python. On a restricted or corporate machine it is the safest first tool: install, run devin-doctor, read the report.

Platform support

Tested on Windows and Linux. On Linux, session data defaults to $XDG_DATA_HOME/devin (normally ~/.local/share/devin) and UI stores default to $XDG_CONFIG_HOME/Devin (normally ~/.config/Devin). Windows stores use %APPDATA%\devin and %APPDATA%\Devin. Use --data-dir and --config-dir when the stores are elsewhere. macOS paths exist but are not verified.

devin-doctor plan — remediation plan, still read-only

plan runs the same checks but emits a numbered remediation plan for every WARN/FAIL finding (the check's fix suggestion) instead of a verdict — nothing is executed; execution stays a human decision or another tool's job. --json gives {"overall", "steps": [{check, status, finding, fix}]}. This replaced the original --fix idea so doctor can keep its "read-only, always" guarantee.

Limitations

• Version-bound. Store parsing follows devin-internals-spec (schema v15–v17). A newer Devin schema reports FAIL — "unknown version" — by design, rather than silently misreading.
• Read-only. It suggests fixes but never touches the data dir. --fix for the safe items is planned (see STATUS.md).
• Locked stores. If Devin is running, DBs may report SQLITE_BUSY — close Devin and re-run.
• macOS paths are implemented but not verified in CI.

Development

pip install -e ".[dev]"
python -m pytest

Tests run entirely on synthetic fixtures generated by devin_internals.fixtures — no real session data is ever read or required. scripts/make_fixture.py <dir> builds a fixture data dir for manual runs.

When to use this

• Devin misbehaves — missing history, auth errors, disk pressure — and you want one command to localize the cause.
• You want a health check before debugging: six checks (stores, schema, data health, config, hooks-windows, disk), each with a fix: suggestion.
• You need a paste-able report for a bug report: devin-doctor report --md.
• You are on a restricted machine: it is read-only and never contacts the network.

When NOT to use this

• You want it to repair things — it is read-only; --fix for safe items is planned.
• Your Devin schema is newer than v17 — it reports "unknown version" FAIL rather than misread.
• Devin is running and DBs are locked — close Devin and re-run to clear SQLITE_BUSY.

FAQ

How do I check if my Devin installation's local data is healthy? Run devin-doctor check. It inspects sessions.db, acp-messages/*.db, state.vscdb, credentials.toml and disk usage, printing PASS/WARN/FAIL per check with a fix: suggestion. Exit code is 0 unless something FAILs.

Is devin-doctor safe to run? Will it modify my data? It is strictly read-only — it opens Devin's stores for reading, writes nothing to the data dir, and never contacts a network service. Config check masks credential values in output. Fixes are suggested as text, never applied.

What does "unknown schema version" mean? Devin's sessions.db schema is versioned; devin-doctor understands v15–v17 via devin-internals-spec. A newer version produces a deliberate FAIL instead of a silent misread — update the tool or devin-internals-spec.

License

MIT — see LICENSE.