Icaro0310/devin-internals-spec

> Track: Understand · Nature: infrastructure
> For: Developers, Maintainers
> Interface: CLI / Python library
> Path: Developers · step 3/4 — after devin-skill-catalog, before devin-powerups
# devin-internals-spec
Linux · Personal Windows · Corporate Windows
Part of the awesome-devin ecosystem: the curated hub for the devin- tools.
> Unofficial community project. Not affiliated with, endorsed by, or
> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
Windows · Linux · English
A documented map of Devin's local session stores — the CLI sessions.db, the
Desktop GUI acp-messages/.db and state.vscdb — plus a schema-version
detector and deterministic synthetic fixtures, so tooling fails loudly instead
of silently misreading your data.
## The problem
Everything Devin stores on your disk is kept in undocumented SQLite databases
whose schema changes without notice: sessions.db has already gone through
17 verified migrations (v1–v15 on 2026-05-06, v16 on 2026-07-05, v17 on
2026-09-14), plus a v18 ledger version registered from a drift artifact
(docs/SCHEMA.md §4).
Any tool that reads these stores has to reverse-engineer the format — and when
Cognition ships the next migration, those tools break silently: wrong counts,
missed rows, or corrupted interpretation, with no error raised.
The Devin Desktop app is worse off than the CLI: its stores
(acp-messages/.db, state.vscdb, session locks, the
refineryschemahistory migration ledger) are not documented anywhere.
## Prior art
Session-log tooling exists for other agent CLIs — e.g. tokmesh and
UniSessions document and parse Devin's CLI sessions.db. This project does
not reinvent that: it borrows the same idea (SQLite schema → typed parsing) and
extends it to what those tools don't cover — the Desktop GUI stores — and adds
the piece they lack: an explicit schema-version gate so a parser refuses to
run against a schema it has never seen.
## What makes it Devin-native
The differentiator, in one sentence: it's the map of what Devin keeps on your
disk — and it warns you when that changes.
1. Side-by-side: it covers acp-messages/.db, state.vscdb
(windsurfSpace. keys) and refineryschemahistory, which no existing
tool documents.
2. No-Devin: remove Devin and there is no store to document — the extra
disappears entirely.
3. Loud failure: detectschemaversion() returns a version contract and
raises on anything unknown, instead of guessing at bytes.
## Install
Python ≥ 3.10 required; install with uv (recommended) or pipx.
bash
uv tool install devin-internals-spec
or with pipx (install it via pip install --user pipx or your package manager, then pipx ensurepath):
bash
pipx install devin-internals-spec
For development:
bash
pip install -e ".[dev]"
pytest
## Usage
bash
devin-inspect schema # schema-detection contract (JSON)
devin-inspect sessions # list sessions (id, title, cwd, …)
devin-inspect health # locate + check all three stores
devin-inspect contract # unified drift check: schema +
# acp meta + usage shape, one report
devin-inspect make-fixture # deterministic synthetic stores
# for tests/demos (--kind, --seed,
# --schema-version, --n-sessions)
contract is the single drift boundary for the whole catalog: it reports