ID — portable context for AI tools

Keep your working preferences in reviewed files. Reuse them across projects and AI tools, and inspect what changed before sharing.

ID gives you a small owner profile, a derived soul.md, portable JSON exports, privacy rules, and a semantic diff. You choose which files an AI tool receives.

Start with one profile

Requires Python 3.11+ and uv. Run in a private working directory:

uv tool install id-protocol
idctl init --owner-id demo

Edit profiles/demo/profile.minimal.md: language, level of detail, working rules, and what a good result means to you. The starter is provisional until you review it. Use an owner ID such as demo or my-work-profile; a real name is unnecessary.

idctl validate --owner-id demo
idctl refresh-soul --owner-id demo
idctl export-interop --owner-id demo
idctl export-compact --owner-id demo
idctl validate-compact --owner-id demo

These commands work from an installed package, outside this repository. No Makefile, API key, central registry, or paid service is required. Validation checks structure and freshness; it cannot decide whether the profile reflects you.

What you get

Add profile.core.md and profile.extended.md when you need more detail. If core exists, it takes precedence over minimal for interop exports. The extended profile is optional. Init refuses to overwrite existing starter files.

Review before sharing

idctl diff --owner-id demo --since 7d

Diff uses Git history; commit reviewed source changes if you want version comparisons. interop.v1.json and soul.md are local derived context, not privacy-filtered sharing bundles. Review your policy and the resulting compact export before giving it to another tool. Legacy list policies (always_share, local_only, task_class_scoped) are converted in memory during validation and export; your source file stays unchanged. Unlisted fields remain local-only. Scoped entries map field paths to task-class lists. Mixed formats, conflicting rules, invalid types, and owner mismatches still block export. Missing policies also block compact/MCP export. The explicit --allow-unfiltered option permits a missing policy for a reviewed legacy workflow; it does not bypass an invalid policy.

Generating or exporting a file does not upload it. Source profiles remain under your control.

Use with agentsgen and SET

All remain separate products. ID does not install the others automatically. The first three versions are exercised together in release CI; skills are an optional workflow reference and are not part of the executable compatibility test.

For a repository that already has ID profiles:

idctl install-set-hook --path .

This creates a small repo-local adapter for SET. It requires idctl on PATH, preserves an existing custom hook, and resolves bootstrap files inside the selected owner directory. Complete SET setup.

Evidence and compatibility

Three reproducible demos verify installed onboarding, privacy-policy omissions, and the agentsgen/SET handoff with synthetic profiles. They measure CLI behavior and runtime, not AI task quality.

AI-client loading depends on each client's configuration. ID exports files for manual attachment or an adapter; it does not automatically synchronize ChatGPT, Claude, Cursor, or other clients. export-mcp creates resource JSON for an adapter; this package does not run an MCP stdio or HTTP server.

Historical benchmark runs are available as a dated snapshot. They are a small sample, not a general performance guarantee.

Explore or contribute

• Core protocol and full documentation.
• Profile layers, sharing, and semantic diffs.
• Integration boundaries and release notes.
• Contributing: include a synthetic reproduction, package version, and expected/actual output.

For source development: install .[dev], then run make validate and make coverage. Keep real private profiles outside this public repository.