FAQ

What is devtwin, in one sentence?

A local CLI that keeps private, source-linked project context (decisions, facts, open questions, handoff notes) outside your repositories and gives your coding agent a short brief of it at the start of each session.

How is it different from AGENTS.md, CLAUDE.md or my agent’s built-in memory?

Repository instruction files are shared with everyone who can read the repository. Built-in memory belongs to one agent product. devtwin is private to you, works across Claude Code and Codex, and keeps each organization’s context in its own scope. They work well together. See How devtwin compares.

Does it send my code or context anywhere?

No. devtwin has no hosted service, and most commands make no network request at all. The exceptions are commands you run on purpose: stack check and stack digest contact only the hosts you approved, and skill-sources check, preview and stage read public GitHub data. If you join an organization hub, hub sync and the hub sync job talk to your organization’s own Git remote over SSH. See Network use.

Your agent is a different matter: whatever you paste into a session, including a brief, may go to that agent’s model provider.

Does it write to my repository?

Never. Onboarding reads a few files and stores what it learns in your private store. The onboarding preview shows "repoWrites": [] to prove it.

Which agents does it work with?

Claude Code and Codex, through the bundled skills. You can also use it with any agent by running devtwin context brief and pasting the result.

Do I need an API key, an account or a database?

No. You need Git and Node.js 22.13 or later. Everything else is files on your disk.

Is it on npm?

Not yet. You run it from a Git checkout with node bin/devtwin.mjs, or a devtwin alias. The devtwin name on npm currently holds only a placeholder, so don’t install it. See Installation.

Does it run on Linux or Windows?

macOS is the reference platform. The test suite also runs on Linux, but Linux is not officially supported yet. Windows is not supported.

Does it remember things automatically?

No record is written unless you, or an agent through a bundled skill, run a record or lesson command, and agent writes are proposals until you publish or accept them. A brief reaches a session only when you or a skill fetch it. With the agent hook installed, matching lesson lines arrive on their own while the agent works.

Why does every command need --pilot?

The pilot file lists the only folders devtwin may write to and the repositories it may read. Requiring it on every call means the CLI never guesses where your data goes. For daily use, the live config at ~/.devtwin/live.json plays the same role. See Where your data lives.

Why do some commands ask for a fingerprint?

The fingerprint identifies the exact plan you previewed. Applying with it means devtwin applies that plan and nothing newer: if a file or the store changed in between, the apply is refused and you preview again. See How it works.

How do I change or delete a record?

You don’t edit records in place. Write a successor with record supersede; the old record drops out of briefs and stays on disk as history. There is no delete command. See Records.

Can my team share context?

Not through a shared store: devtwin keeps one private store per machine, with no sync. Your team can share lessons through an organization hub, a Git repository your organization owns. To pass project context on, export selected records as a handoff packet that anyone can read without devtwin. Team conventions belong in the repository’s own instruction files.

Do my lessons leave my machine?

Only when you say so. Agent proposals stay on your machine. A lesson goes to a hub only when you run lesson accept --target hub or lesson copy in your own terminal and click Approve in the dialog that shows the exact text. A general or project lesson never leaves your machine. The one exception to per-item approval is “working on” notes, which post under the consent you give at hub join, and which you can stop with note revoke.

What do my colleagues see?

Your accepted hub lessons, labelled as claimed by your handle, and your “working on” notes: one line with your handle, the branch name and the folder areas you edit. Never your records, your prompts or your store. Their agents get a lesson only when they touch a matching file, package or topic. published list shows everything devtwin published in your name.

Can an agent publish for me?

No. An agent can propose up to three lessons per session, but lesson accept, lesson copy, published delete and hub join are owner actions. The devtwin hook denies them from an agent shell, and each one shows a macOS dialog that only you can approve.

Is my data backed up?

No. The store lives only on your disk. Back up ~/.devtwin with your usual backup tool if the context matters to you. Backup and restore is the top item on the roadmap.

Can I store credentials in it?

No, and devtwin tries to stop you: titles and bodies that look like secrets are refused with DEVTWIN_SENSITIVE_CONTENT. The check is a tripwire, not a guarantee. Keep credentials in your password manager or keychain.

Does it pick the right GitHub or Slack account for each organization?

That is identity routing. It is designed but not shipped yet; no account or connect command exists today. See Identity routing.

I used devtwin when it was called devctx. What do I do?

Move your live setup with devtwin live migrate, which copies your store and leaves the old one untouched. See Migrate from devctx.

What license is it under?

Apache-2.0. See Contributing if you want to help.