DotAIOS

Give your AI one place to remember what matters.

DotAIOS keeps your identity, priorities, projects, notes, and trusted workflows in one private place, then connects that context to local AI agents through documented bridges. No DotAIOS account. No hosted memory.

Activation configures the documented bridge for Claude Code, Codex, and Gemini CLI when it finds them, and Cursor connects per project. Claude Code can auto-save sessions today; the others use explicit saving or import. Client support records what each client has actually been observed to do, so you can check rather than assume.

Why people use it

If you use more than one AI assistant, DotAIOS helps you:

• stop repeating who you are and what you are working on;
• keep projects, priorities, and important notes together;
• carry the same owned context across documented Claude Code, Codex, Cursor, Gemini CLI, and adapter surfaces.

The free core is available now.

Install: preview, then run

You need Node.js 20 or newer. You do not need a GitHub or DotAIOS account.

Run these commands yourself in Terminal, PowerShell, or another system shell. The first command previews the selected folder, detected clients, and collisions without creating ~/aios or changing client configuration or sync. npm may download and cache the named package. The second command runs the same pinned release and guides you through setup:

npx [email protected] setup --dry-run
npx [email protected] setup

Setup creates ~/aios, then connects supported AI apps detected on the machine. It preserves unmanaged files and stops before replacing existing configuration. Private GitHub sync is off by default.

Prefer to be walked through it?

Open Claude Code, Codex, Cursor, or any assistant that can run commands, and paste:

Please help me install DotAIOS. Read https://github.com/filocosta46/dotaios and follow the "If an AI assistant is helping you" section of INSTALL.md. Show me the preview first, explain it in plain language, and ask me before anything on my computer changes.

That section tells the assistant to preview first and to ask before every write, so you stay in control of each step. A careful assistant should be willing to help on those terms — and if it declines, run the two commands above yourself instead.

Afterward, either you or the assistant can verify the local installation with:

npx [email protected] doctor

Verify before running

The package is dotaios on npm, published from the filocosta46/dotaios repository. Release 2.0.0 maps to Git tag v2.0.0.

These commands inspect registry provenance and packaged contents without running DotAIOS setup:

npm view [email protected] version dist.integrity dist.tarball gitHead
npm view [email protected] scripts
npm pack [email protected] --dry-run

Those three commands show you the publisher, the integrity record, and every file in the package before anything runs. The package defines no preinstall, install, or postinstall script, so nothing executes until you invoke the CLI yourself. The commands above omit npx -y on purpose, so npm still asks you to confirm the pinned package — approve it once what you see matches what you expect. Interactive setup then offers private sync, a daily brief, conversation saving/backfill, and the optional Lightpanda helper; every one of them defaults to No. INSTALL.md has the full sequence and the security model has the package and permission boundaries.

What you have afterward

• One place for your identity and priorities
• A clear home for projects and next steps
• One-command restore of a project's committed remote state into a private local workspace
• Recent notes and saved conversations
• Long-term knowledge and sources
• Trusted workflows your assistants can follow

Your context stays in a local ~/aios folder: readable, portable, and yours. Activation may add a DotAIOS-managed block to ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, or ~/.gemini/GEMINI.md, plus documented skill links for detected clients. Machine-local project path mappings live in ~/.dotaios/projects.json. Existing unmanaged content is preserved. When you use an AI client, that provider processes the context you send it. You can optionally sync selected AIOS files privately between your own devices.

Project records sync with AIOS. Managed project repositories sit under its
ignored workspaces/ root with their own history and credentials, so source
code never enters the personal-context mirror.

DotAIOS does not keep an endless transcript. Important information is deliberately saved into the right place so it remains useful later.

Projects and workspaces

Register an existing repository without changing it, inspect the plan, then apply it:

npx -y dotaios@latest project add /path/to/project
npx -y dotaios@latest project add /path/to/project --apply
npx -y dotaios@latest attach /path/to/project --dry-run
npx -y dotaios@latest attach /path/to/project

The portable project record lives in ~/aios/projects. The checkout stays where it is. On another machine, restore a missing checkout into the ignored workspace shelf with:

npx -y dotaios@latest project restore <slug-or-id> --dry-run
npx -y dotaios@latest project restore <slug-or-id>

DotAIOS never copies a project's source code into the personal-context mirror.

Optional private sync

Sync is opt-in and uses a private GitHub repository you control:

npx -y dotaios@latest sync setup
npx -y dotaios@latest sync now
npx -y dotaios@latest sync status

Credentials stay on the machine and are not written into the Git remote URL. Managed project checkouts, external vault contents, secrets, and ignored local state are outside the mirror. Stop syncing and remove the local sync credential with npx -y dotaios@latest sync logout; the private repository remains in your GitHub account.

Managed Agent Skills

AIOS real directories under skills/<name>/SKILL.md are canonical. Native
agent folders are derived projections; linked shelf entries and real skills
found only in native folders stay unroutable until explicit adoption.

dotaios skills inventory --json
dotaios skills adopt /reviewed/local/skill --json
dotaios skills adopt /reviewed/local/skill \
  --apply <operation-id> --fingerprint <sha256>
dotaios skills reconcile --json
dotaios skills remove <name> --json

Preview commands are zero-write. Apply requires both exact tokens from the
matching preview. Adoption copies the complete bounded regular-file bundle,
never executes scripts, and refuses links, special or hardlinked files, stale
proofs, unsafe parents, and foreign collisions.

Updating

First inspect the newest release metadata without executing it:

npm view dotaios@latest version dist.integrity dist.tarball gitHead scripts dependencies

Review the returned source tag, integrity, scripts, and dependencies. Replace
<version> below with that exact reviewed version and keep it identical in
every command:

npx dotaios@<version> --version
npx dotaios@<version> doctor
npx dotaios@<version> migrate
npx dotaios@<version> migrate --apply <plan-id>
npx dotaios@<version> activate
npx dotaios@<version> skills doctor
npx dotaios@<version> capture enable claude-code
npx dotaios@<version> mcp config --agent <agent>

migrate is a read-only preview. Run the migrate --apply <plan-id> line only
when the preview prints that exact plan, using the same release. Re-run capture
only if Claude Code capture was already enabled. For every configured MCP
client, run mcp config --agent <agent>, merge the printed fragment into that
client's existing configuration, and restart it. DotAIOS MCP does not edit
client config automatically. Do not replace <version> with latest.

Disconnecting or removing

DotAIOS has no hosted account or background service to cancel. Before removing local data, make a backup of anything you want to keep.

npx -y dotaios@latest capture disable claude-code
npx -y dotaios@latest sync logout

Those commands stop managed capture and private sync. The last step is deliberately yours: review the DotAIOS-managed bridge blocks and links in your client configuration, remove those, then archive or delete ~/aios. There is no one-command wipe, because the same command would have to guess which parts of your client configuration are ours — and anything unmanaged is left exactly as you wrote it.

Good to know

• A browser-only chat cannot open local files by itself.
• Each assistant discovers and uses local context in its own way. Client support records what has been observed for each one, rather than asking you to take it on faith.
• Claude Code supports managed automatic session capture today. Other clients use explicit capture, import, or the bundled save-session workflow.
• Optional sync sends the selected Git mirror to your own private GitHub repository. The free core does not upload context to a DotAIOS service.
• Client support separates configured, discoverable, invoked, and produced evidence for each client.

The promise

• Private by default. DotAIOS does not run a hosted memory service.
• Yours to keep. Your context lives in readable local files, not inside a locked-in account.
• Works with the assistants you choose. Models are rented. Your context is owned.

Docs

• INSTALL.md — human-run install and removal
• Getting started — product walkthrough
• Architecture · Projects · Client support · Security · all guides

License

MIT