Where your data lives

devtwin keeps two things apart: the kit, which is public code you clone, and your store, which holds everything you add. The store lives in private folders outside the kit and outside your repositories. Nothing moves from the store into the kit, and nothing is uploaded anywhere.

The pilot file

Every stateful command takes --pilot <file>. The pilot file is a small JSON document that says which folders devtwin may use:

{
  "schemaVersion": 1,
  "pilotRoot": "/private/tmp/devtwin-demo.WlXG7p",
  "configRoot": "/private/tmp/devtwin-demo.WlXG7p/config",
  "dataRoot": "/private/tmp/devtwin-demo.WlXG7p/data",
  "stateRoot": "/private/tmp/devtwin-demo.WlXG7p/state",
  "inputsRoot": "/private/tmp/devtwin-demo.WlXG7p/inputs",
  "agentHomes": [],
  "repos": ["/private/tmp/devtwin-demo.WlXG7p/repos/atlas"],
  "forbidden": []
}

Field	Purpose
`pilotRoot`	The folder that contains the store.
`configRoot`	Settings, scopes, project bindings, the project registry and your personal profile.
`dataRoot`	Records, proposals, handoff exports, digests and drafts.
`stateRoot`	Locks, run receipts and other bookkeeping.
`inputsRoot`	Files you hand to `devtwin`, such as record bodies for `--body-file` and local policy hubs.
`repos`	Repositories `devtwin` may read. Onboarding refuses any other path.
`agentHomes`	Disposable agent folders that test installs may write to. Leave it empty unless you need it.
`forbidden`	Extra paths `devtwin` must never touch.

All paths must be absolute and canonical. The store folders must not be inside a Git repository: devtwin init refuses with DEVTWIN_PATH_UNSAFE if they are.

There are two ways to get a pilot file:

A disposable pilot for trying things out, like the one the Quickstart writes in a temporary folder.
A live config at ~/.devtwin/live.json for daily use on your real projects. It adds a live block that names your real skill folders and a pinned copy of the kit. See Live mode.

Layout of the store

After the Quickstart, a disposable store looks like this:

Directorydevtwin-demo.WlXG7p/ the pilot root
- pilot.json
- Directoryconfig/
  - user.json preferences and actor references from init
  - registry.json which worktree belongs to which project
  - Directoryscopes/
    example.json scope settings, hubs and policies
  - Directoryprojects/
    Directoryexample/
    Directoryexample.atlas/
    v1.json binding: worktree paths, remotes, approved source hashes
  - Directoryprofile/ your personal profile and its revisions, once set
    …
- Directorydata/
  - Directoryscopes/
    Directoryexample/
    Directoryprojects/
    Directoryexample.atlas/
    Directoryrecords/
    Directoryrec_94315938d3e27ab174b5665d/
    record.json kind, status, title, sources, hashes
    body.md the record body
    …
    Directoryproposals/ records waiting for review
    …
    Directoryoperations/ manifests of each onboarding
    …
    Directorystaging/ in-progress writes
    …
  - Directoryexports/
    Directoryhandoffs/
    Directoryexample/
    Directoryexample.atlas/
    search.handoff.md
- Directorystate/
  - Directorylocks/
    …
  - Directoryruns/
    Directoryrun_acec42756c3bbc296b7b7c32/
    receipt.json
- Directoryinputs/ files you supply, such as record bodies
  - …
- Directoryrepos/
  - Directoryatlas/ the demo repository, never written by devtwin
    …

Other features add their own folders as you use them: data/digests/ and data/drafts/ for the stack watch and saved drafts, state/stack/ for its approvals, and skill workspaces for the personal harness. Scoped versions of these live under data/scopes/<scope>/.

Lessons, the agent hook and the organization hub add these:

Path	Holds
`data/personal/records/`	Your personal lessons and preferences. They follow you to every scope.
`data/scopes/<scope>/org/records/`	The scope’s org home for lesson records.
`data/lesson-proposals/`	Lesson proposals from agents, one file each, until you accept or reject them.
`data/pref-proposals/`	Preference proposals from agents, one file each. Declined ones stay, so they are not proposed again.
`data/pref-retired.json`	Preferences you retired. The instruction block leaves them out.
`data/templates/outputs/`	Your own output templates: heading structure only.
`config/hubs/<scope>.json`	The hub binding: hub ID, handle, commit email and note consent.
`state/lessons/<scope>.json`	The lesson index for a scope. A cache that `lesson index` and `hub sync` rebuild.
`state/hooks/`	The kit receipt, per-session files, the budget log and the hook log. They hold no prompt text.
`state/hubs/<hubId>/`	The outbox, the colleagues’ notes cache, replacement notices and tombstone memory.
`<hub root>/<scope>/`	The local clone of the hub, inside a hub root folder you approved. Not in the store.

Live mode layout

In live mode, everything private lives under one folder in your home directory:

Directory~/.devtwin/ mode 0700, created by you
- live.json the live config
- Directorykit/ a separate clone of the kit, pinned to a reviewed commit
  - …
- Directorystore/ the pilot root
  - Directoryconfig/
    …
  - Directorydata/
    …
  - Directorystate/
    …
  - Directoryinputs/
    …

Outside this folder, live mode writes only devtwin-* skill folders inside ~/.claude/skills and ~/.agents/skills, and the exact paths you approved as write classes: hub clone folders, devtwin’s own entries in the agent hook settings files, and its devtwin.*.plist files in ~/Library/LaunchAgents. See Live mode.

Protection and its limits

Private file modes. New files are created with mode 0600 and folders with 0700, so other users on the machine can’t read them.
Not encrypted. devtwin does not encrypt the store. Use full-disk encryption, such as FileVault on macOS.
No backup and no sync. The store exists only on your disk. A hub shares only the lessons you accept and your “working on” notes, never the store. If you lose it, you lose its records. Back up ~/.devtwin with your usual backup tool if the context matters to you.
The fence is not a sandbox. devtwin refuses to write outside the pilot’s folders and always refuses your real agent homes (~/.claude, ~/.codex, ~/.agents, ~/.gemini, ~/.cursor, ~/.commandcode, plus $CLAUDE_CONFIG_DIR and $CODEX_HOME when set) and the kit checkout. That limits the CLI, not other programs: any process running as you, including your agent, can still read the store.

Read the Security model for the full set of assumptions.

Don’t edit the store by hand

Records, bindings and manifests are cross-checked by hash. If you edit or move a file, devtwin treats it as corrupt. A corrupt record you added drops out of briefs, and handoff exports for that project fail with DEVTWIN_INTEGRITY. A corrupt record written by onboarding goes further: every brief for that project fails with DEVTWIN_RECOVERY_REQUIRED.

Run devtwin doctor --pilot "$PILOT" to check the store’s health. It reports corrupt records, leftover locks and incomplete writes without changing anything. There is no repair command, so keep the files as they are and see the error reference before you act.

To change a record, supersede it. To remove a demo store, delete its folder yourself: devtwin never deletes your data.

What’s in the public kit

The kit you clone contains only the CLI code, data schemas, generic skill templates, catalogs, tests and documentation. It never contains your records or profile. The kit’s own package check fails if private-looking paths, such as records/, profile/ or drafts/, are ever committed to it, so a personal fork stays clean too.