@0xjordan/ideality

Ideality

One machine. Many developer identities. No account bleed.

Ideality maps folders to developer identities, then starts each tool with the right Git author, SSH key, account environment, profile directory, secrets, network policy, and execution target.

Keep using git, gh, aws, vercel, codex, browsers, editors, and the rest of your normal toolchain. Ideality's managed shims select and isolate the matching identity automatically from $PWD.

Install · Quick start · Supported tools · Security · Documentation · Contributing

Why Ideality

Developer tools store identity in different places: global Git config, shell variables, dotfiles, browser profiles, vendor-specific directories, native credential stores, or an active CLI session. Switching projects can silently leave the wrong account active.

Ideality gives those tools one folder-aware identity boundary:

~/code/work/       -> work identity       -> git, gh, aws, vercel, codex
~/code/personal/   -> personal identity   -> git, gh, npm, railway, chrome
~/clients/acme/    -> acme identity       -> git, glab, gcloud, cursor

The longest matching folder root wins. Outside configured roots, Ideality uses the default identity. You can always override the selection explicitly.

Features

How It Works

1. Bind roots to identities. Each identity owns one or more folder roots and may define Git, SSH, tool, network, and VM settings.
2. Enable only the tools it needs. Ideality creates isolated profiles and managed shims for the selected adapters.
3. Run commands normally. A shim resolves the identity from $PWD, builds a clean process environment, and executes the real binary.
4. Inspect any decision. ideality status shows the active identity; ideality explain <tool> shows how a launch will be isolated.

command
  -> managed shim
  -> longest matching folder root
  -> identity + tool profile
  -> secrets / network / VM requirements
  -> real executable

Ideality does not make a repository execute commands when it is opened. Project handovers are parsed, reviewed, checked against team policy, and applied explicitly with ideality setup.

Install

Prebuilt binaries support Linux and macOS on x64 and arm64.

Package Managers

The registry package is scoped as @0xjordan/ideality, but it installs the normal ideality command:

npm install --global @0xjordan/ideality
pnpm add --global @0xjordan/ideality
bun add --global @0xjordan/ideality

# Yarn Classic
yarn global add @0xjordan/ideality

# Modern Yarn has no global install command; run it on demand
yarn dlx @0xjordan/ideality

The package installs the matching signed native release and verifies its authenticated metadata and checksum. If a package manager disables lifecycle scripts, the ideality launcher performs the same verified installation on first use.

Install Script

The installer authenticates the release metadata, verifies the selected archive checksum, and installs the binary to ~/.local/bin. Verification is automatic and requires no separate setup.

curl -fsSL https://raw.githubusercontent.com/0xJord4n/ideality/main/scripts/install.sh | bash

Pin a version or change the destination with IDEALITY_VERSION and IDEALITY_INSTALL_DIR:

IDEALITY_VERSION=0.1.0 \
IDEALITY_INSTALL_DIR="$HOME/bin" \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/0xJord4n/ideality/main/scripts/install.sh)"

Agent Skills

Ideality ships ten Agent Skills for operating the CLI and contributing adapters. Install them with Vercel's open Skills CLI:

npx skills add 0xJord4n/ideality
# or
bunx skills add 0xJord4n/ideality

Once Ideality is installed, its wrapper prefers bunx and falls back to npx:

ideality skills install
ideality skills install --list
ideality skills install --runner bunx
ideality skills install \
  --skill ideality-getting-started \
  --skill ideality-troubleshooting \
  --agent codex \
  --global

The installer supports the agents recognized by Vercel Skills, interactive skill selection, project or global scope, symlink or copy installation, and non-interactive --yes/--all modes. See the Agent Skills guide for the complete roster and options.

Build From Source

Source builds require the Bun version in .bun-version.

git clone https://github.com/0xJord4n/ideality.git
cd ideality
bun install --frozen-lockfile
bun run check
bun run build
bun link

sha256sum -c --ignore-missing SHA256SUMS.txt
# Public repositories
gh attestation verify ideality-linux-x64.tar.gz --repo 0xJord4n/ideality

Quick Start

Enter the folder that should use an account, then initialize it:

cd ~/code/work
ideality init

The current folder is selected automatically. The recommended setup asks for an identity name, uses your existing Git identity (or asks for it once) and SSH agent, enables the essential developer tools, and installs automatic shell and Git switching. Review the summary and you are ready.

Choose Advanced setup only when you want to generate or discover an SSH key, choose tool packs individually, or customize shell and Git integrations.

Open a new shell and inspect the result:

exec "$SHELL" -l

ideality status
ideality explain gh
gh auth status

Add another identity whenever you need one:

ideality identity add
ideality identity bind personal ~/code/personal
ideality identity default personal

For unattended provisioning:

ideality init --non-interactive \
  --label "Example Account" \
  --root ~/code \
  --git-name "Example Developer" \
  --git-email developer@example.com \
  --generate-ssh \
  --packs essentials,cloud,ai \
  --tools gh,cf,codex,aws,gcloud,gemini,copilot \
  --install \
  --shell zsh

Pause or disable Ideality

Disable automatic shell dispatch and Git identity routing without deleting identities, credentials, plugins, or other state:

ideality disable --dry-run
ideality disable

The current terminal has already loaded its shell hook, so open a new terminal after disabling. Restore the integrations at any time with:

ideality enable

Both commands accept --shell zsh|bash|fish, --rc <path>, --no-shell, and --no-git. ideality install remains an equivalent way to enable and regenerate all integrations.

Verify dispatch is active

ideality git check gh              # shim intercepts this tool
ideality git status                # configured profile vs effective Git author
ideality git repair --dry-run      # preview repo-local author overrides
ideality git repair                # clear them so the profile applies
ideality doctor --strict           # shim-path + git:identity findings

Directories without configuration

When no bound root contains the current directory, shims pass through to the real binary with your ambient environment instead of applying any identity — status, explain, env, and git status all report this as passthrough. Pass --identity <id> to force an identity anyway:

ideality run --identity work -- gh auth status

To restore the previous fallback (apply the default identity everywhere), set "routing": { "unmatched": "default" } in config.jsonc.

Project Setup

Run the project wizard anywhere inside a repository:

ideality setup

The wizard can activate an existing local identity, import a shared project identity, or create a new one. It then selects tools and optional network or VM requirements before showing the exact files and integrations it will change.

Choose between:

• Local activation: keep the binding only in your user registry.
• Complete handover: write a portable .ideality/project.jsonc containing the project identity and tool profiles.
• Requirements-only handover: share required tools without identity profiles or credential references.

Automation uses the same operation without prompts:

ideality setup --non-interactive \
  --identity work \
  --tools gh,cf,vercel,codex \
  --project \
  --yes

ideality setup --non-interactive \
  --identity work \
  --tools gh,codex \
  --project \
  --requirements-only \
  --dry-run

Teams can constrain handovers with .ideality/policy.jsonc and enforce the contract in CI:

ideality policy check

See team policy contracts for the schema and CI patterns.

Supported Tools

Recommended ideality init enables Developer essentials automatically. Advanced setup and ideality identity add offer packs first, followed by fine-grained tool selection. Only enabled tools receive identity profiles and managed shims.

The built-in catalog ships 58 adapters across 7 selectable packs:

• Developer essentials: cf, chrome, claude, codex, firefox, gh, opencode, railway, vercel
• Cloud accounts: aws, az, doctl, gcloud
• Source control: bitbucket, gerrit, glab, tea
• Editors and desktop: code, cursor, discord, goland, idea, pycharm, rustrover, slack, webstorm, windsurf, zed
• Package registries: bun, cargo, composer, gem, gradle, mvn, npm, nuget, pip, pnpm, uv, yarn
• Deployment platforms: firebase, fly, heroku, netlify, pulumi, render, shopify, sst, stripe, supabase
• AI tools: aider, amp, cn, copilot, gemini, goose, kiro-cli, qwen

Adapters report full, partial, or credentials isolation based on the controls exposed by the upstream application. The tool pack and isolation matrix documents the exact mechanism for every built-in adapter.

Manage packs and tools after setup:

ideality tool packs
ideality tool enable-pack work cloud
ideality tool disable-pack work editors
ideality tool enable work stripe
ideality tool list

Bun is intentionally not shimmed because it may be the runtime starting Ideality. Use ideality run bun -- <args> when registry isolation is required.

Everyday Workflows

Inspect And Run

ideality status
ideality explain vercel
ideality explain cf --path ~/code/work/project --json

ideality run gh --identity work -- auth status
ideality run chrome --identity personal -- https://github.com

Authentication

ideality auth gh status
ideality auth railway login --identity work
ideality auth status --all

Git And SSH

ideality identity ssh-public work
ideality identity bind work ~/projects/client
ideality identity unbind work ~/projects/legacy

Git integration uses generated includeIf configuration, including author, signing, and core.sshCommand. Other tools use process-only shims and isolated profile directories.

Secrets

Starter profiles use logical references instead of literal tokens. The default backend stores locked local files:

ideality secret set work railway RAILWAY_API_TOKEN
printf '%s' "$TOKEN" |
  ideality secret set work cf CLOUDFLARE_API_TOKEN --stdin
ideality secret list

Available backends include local files, age, macOS Keychain, pass, 1Password, Bitwarden, and Dashlane:

ideality secret backend age \
  --recipient age1... \
  --identity-file ~/.config/age/keys.txt

ideality secret backend keychain
ideality secret backend pass --prefix developer/ideality
ideality secret backend onepassword

Secret values are resolved only while starting the selected tool. Status, doctor, explain, config output, audit history, and the TUI remain redacted. Run ideality env --reveal only when you intentionally need resolved values.

Network And VM Isolation

Network and VM profiles are folder-aware execution requirements. A selected host VPN is enforced before Ideality starts a native tool or VM.

ideality network add
ideality vm add
ideality vm bind work dev-vm
ideality network bind work corp-vpn --tool chrome
ideality network up corp-vpn
ideality vm exec dev-vm -- bun test
ideality doctor --strict

Lima is the executable macOS/Linux VM backend. Apple VZ, Cloud Hypervisor, and Firecracker are capability-checked helper backends. Mullvad, WireGuard, OpenVPN, Tailscale exit nodes, Cloudflare WARP, and custom network wrappers are supported with provider-specific enforcement boundaries.

See network and VM isolation for setup, enforcement levels, secret handling, and leak-prevention guarantees.

Terminal Dashboard

ideality tui

The dashboard stages identity, folder, tool, network, VM, plugin, and secret backend changes in memory. It previews a readable diff and writes only after an explicit save through transactional history. Press ? on any screen for the full keymap, g for plugin manifest administration, and k for secret-backend administration. Plugin installation or removal requires a clean staged draft; destructive actions require explicit confirmation.

Custom Adapters

Add a local tool directly:

ideality tool add acme --executable acme
ideality tool env work acme \
  ACME_HOME value:{{idealityHome}}/profiles/{{identity}}/acme
ideality tool env work acme ACME_TOKEN secret:{{identity}}/acme-token
ideality tool args work acme -- --region eu

Or distribute a portable declarative manifest:

{
  "schemaVersion": 1,
  "kind": "tool",
  "id": "acme",
  "displayName": "Acme CLI",
  "pack": "custom",
  "executable": {
    "primary": "acme",
    "alternatives": ["acme-cli"]
  },
  "isolation": {
    "scope": "process",
    "state": "credentials"
  },
  "auth": {
    "status": ["account", "show"]
  },
  "profile": {
    "env": {
      "ACME_TOKEN": {
        "from": "secret",
        "key": "{{identity}}/acme-token"
      }
    }
  }
}

ideality plugin validate acme.ideality.jsonc
ideality plugin install acme.ideality.jsonc

Tool manifests are data, not executable plugins. Commands and arguments are strict argv arrays. Runtime plugins cannot inject privileged network, VM, or secret-backend code. See custom adapters.

Security Model

Useful checks:

ideality identity bind work ~/projects/client --dry-run
ideality plugin install acme.ideality.jsonc --dry-run
ideality rollback --list
ideality rollback latest --dry-run
ideality doctor --strict

Structured audit history is local and explicitly opt-in. By default Ideality does not create an audit file or record events.

ideality audit enable --max-events 1000 --max-bytes 5242880
ideality audit list
ideality audit list --type secret.set --json
ideality audit prune --confirm
ideality audit disable

Audit payloads are allowlisted and redacted. They never include executable paths, secret values, resolved environments, raw stdout or stderr, token-like strings, or full argv. See SECURITY.md for operational guidance.

Configuration

Managed state defaults to ~/.ideality:

~/.ideality/
├── audit/          # optional redacted JSONL history
├── bin/            # managed tool shims
├── completions/    # generated shell completions
├── config.jsonc    # identity and adapter registry
├── git/            # generated conditional Git configuration
├── history/        # transactional registry snapshots
├── plugins/        # installed declarative manifests
├── profiles/       # identity-specific tool state
├── runtime/        # active network and VM runtime state
├── secrets/        # local secret backend storage
├── shell/          # generated shell integration
└── ssh/            # generated SSH keys

Inspect or edit the registry through the CLI:

ideality config path
ideality config validate
ideality config show
ideality config edit
ideality config migrate --dry-run

Updates

Direct binary installs update in place. Package-manager installs are detected and never overwritten. Update them through the manager that installed them:

npm update --global @0xjordan/ideality
pnpm update --global @0xjordan/ideality
bun update --global @0xjordan/ideality

# Yarn Classic
yarn global upgrade @0xjordan/ideality

Modern Yarn's yarn dlx mode has no persistent installation to update. Run yarn dlx @0xjordan/ideality@latest whenever you want the latest release.

ideality update --check
ideality update --dry-run
ideality update
ideality update --version 0.1.0

An update verifies signed metadata and the archive checksum, proves the staged binary version, checks migration readiness, snapshots config bytes, and rolls back both the binary and config if migration fails. After swapping the binary it refreshes shell and Git integrations (the equivalent of ideality install, opt out with --no-refresh), then tells you to reload your shell — a CLI cannot replace its parent shell, so finish with:

exec "$SHELL" -l

Legacy managed installations are never overwritten; remove the old managed installation first, then use the signed installer so only one ideality remains on PATH.

Command Reference

Run ideality --help or ideality <command> --help for flags and examples.

Documentation

Development

bun install --frozen-lockfile
bun run dev -- --help
bun run check
bun run audit
bun run perf:check
bun run build

bun run check verifies formatting, lint, TypeScript, the built-in catalog, privileged adapter contracts, generated documentation, and the full test suite.

Adding a built-in tool adapter is a two-file contribution: one manifest and one behavior contract. The repository scaffolder registers it and regenerates the catalog documentation:

bun run catalog:new acme --display-name "Acme CLI" --pack deployment
bun run check

See CONTRIBUTING.md for adapter contracts, privileged contribution rules, tests, and pull request templates.

License

Ideality is available under the MIT License.