My AI Configuration

MyAiConfiguration is a version-controlled global user configuration for OpenAI Codex and Claude Code.

It keeps rules, skills, agents, hooks, and orchestration guidance in shared source files. Client adapters turn those files into shell-specific packages that can be inspected before they are installed.

Capability check

Check the selected shell's minimum version and required Python tools before setup. Missing jq produces a warning because only Claude's Bash status line needs it. The command exits with an error when a requirement is missing.

PowerShell:

.\scripts\commands\check-capabilities.ps1

Bash:

./scripts/commands/check-capabilities.sh

Quickstart

With the requirements installed, clone the repository, build it, then install it. Stop if any command fails. Installation asks for the shell, client, Flashbang, status line, local QMD search models, and extension choices.

PowerShell:

git clone https://git.lechner-systems.at/fraujulian/MyAiConfiguration.git
cd MyAiConfiguration
.\scripts\commands\build.ps1 -Summary
.\scripts\commands\install.ps1 -Summary

Bash:

git clone https://git.lechner-systems.at/fraujulian/MyAiConfiguration.git
cd MyAiConfiguration
./scripts/commands/build.sh --summary
./scripts/commands/install.sh --summary

For an already-installed configuration, use Quickupdate instead.

Quickupdate

Run these commands from the repository root. Quick reuses the shell, client, Flashbang, status line, retrieval, and extension choices from the last successful installation or update without opening selection menus. Stop if any command fails.

PowerShell:

git pull --ff-only
.\scripts\commands\build.ps1 -Summary
.\scripts\commands\update.ps1 -Quick -Summary

Bash:

git pull --ff-only
./scripts/commands/build.sh --summary
./scripts/commands/update.sh --quick --summary

If no selection has been saved yet, or it predates a required option, Quick stops with a hint. Run scripts/commands/update.ps1 or ./scripts/commands/update.sh once without Quick to save your choices. They are stored in ~/.my-ai-configuration/selection.json; dry runs and failed runs do not overwrite them. To change the selection later, run a normal update again. Quick does not automatically select newly added plugins.

Install and update also rebuild internally; the explicit build above lets you check the packages before installation.

Features

• One shared source of truth for Codex and Claude Code.
• Separate generated packages for PowerShell and Bash.
• Native PowerShell 5.1 and Bash scripts.
• Installation for Codex, Claude Code, or both, with explicit target parameters and an interactive plugin selection.
• Claude Code loads technology- and situation-specific rules as skills, so only their name and description sit permanently in context; the full rule text loads only when the skill is invoked. Codex keeps loading rules as plain files, unchanged.
• A managed-file manifest tracks unchanged and stale files. Replaced files are backed up; locally modified stale files are retained with a warning.
• Dry-run support (no destination writes, backups, or plugin changes) and timestamped backup directories.
• Finish notifications, Claude session-state hooks, optional safety utilities, and compact status displays.
• Separate install, update, and uninstall scripts: install refuses to run against an already-installed destination, update refuses to run against one that is not installed yet, and uninstall refuses to run against one that was never installed.
• User-level extension installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, MCPorter, Humanizer, Impeccable, and Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions installed and recorded by this setup can be removed through deselection.
• Optional local search for both clients through QMD with Qwen3-Embedding-0.6B, Qwen3-Reranker-0.6B, and QMD Query Expansion 1.7B (Yes/No/Auto; Auto benchmarks GPU, then CPU).

Requirements

• PowerShell 5.1 or newer; PowerShell 7 is supported as well.
• Bash 4.3 or newer, with standard utilities such as awk, sed, and sha256sum.
• Python 3.11 or newer for configuration validation and task-state hooks/helpers (python for PowerShell scripts, python3 for Bash scripts).
• jq for Claude's Bash status line; without it, that status line produces no output.
• Node.js 22 or newer and npm when local QMD search is enabled.
• Node.js 22 or newer and npm when MCPorter is selected.

Core Bash setup scripts do not require PowerShell. The credential commands use Windows Credential Manager and require PowerShell, including when invoked through their Bash wrappers. The PowerShell scripts remain compatible with PowerShell 5.1; PowerShell 7 can also run them.

Architecture

shared definitions -> client adapters -> generated packages -> user installation

Directory	Purpose
shared/	Client-independent rules, agents, skills, hooks, status lines, and global instructions.
adapters/	Codex and Claude Code formats, settings, templates, and the plugin manifest.
generated/	Reproducible PowerShell and Bash packages. This directory is ignored by Git.
scripts/	Build, installation, update, diagnosis, and validation scripts.
docs/	Focused documentation about the configuration design.

The build creates:

generated/
|-- codex-powershell/
|-- claude-powershell/
|-- codex-bash/
`-- claude-bash/

Documentation

Document	Contents
Architecture	Shared sources, adapters, generated packages, and installation.
Scripts	Commands, checks, tests, and internal script layout.
Configuration	Client settings, permission defaults, status displays, and verification.
Extending the configuration	Add shared rules, skills, and agents.
Plugins	Plugin sources, selection, installation, updates, and removal.
Hooks	Registered events, session-state helpers, notifications, and optional utilities.
Agents	Agent roles and when delegation is useful.
Skills	Skill categories and conditional rule loading.
Codex adapter	Codex-specific configuration files.
Claude Code adapter	Claude-specific configuration files.
Hook package	Overview shipped with the hook scripts.
Repository instructions	Rules for maintaining this repository.

Build Script

Run the matching command from the repository root:

PowerShell:

.\scripts\commands\build.ps1

Bash:

./scripts/commands/build.sh

Rebuild when shared definitions, adapters, or generation logic change. Choose other verification according to the change's risk; documentation-only edits do not require a build. Building writes reproducible packages below generated/ and may use temporary validation files; it does not install global user configuration. Each build writes into its own generated.build-* directory and replaces generated/ only after validation, so a failed or parallel build never leaves it partial.

Installation Script

The installer asks for the target shell and client, unless they are passed as parameters, then refuses to continue if any selected destination is already installed (Already installed, use the update script.). Selecting PowerShell or Bash chooses the generated package format; installation always targets the current user's home directory. This check is skipped for a dry run, so previewing always works regardless of prior install state.

Preview an installation without changing user files, backups, or plugins:

PowerShell:

.\scripts\commands\install.ps1 -DryRun

Bash:

./scripts/commands/install.sh --dry-run

Install the selected configuration interactively:

PowerShell:

.\scripts\commands\install.ps1

Bash:

./scripts/commands/install.sh

Omitting either target parameter opens its selection prompt. There is no automatic shell default. For a noninteractive preview, supply both target parameters together with -DryRun or --dry-run.

Every installed file is tracked in a per-destination manifest (.ai-config-manifest.tsv). On update, unchanged files are not written or backed up. Files still shipped by the package are replaced when their content differs, including local edits; the previous content is backed up first. An untracked file at a package target path is also backed up and replaced, with a warning. Untracked files outside package target paths are left alone.

Previously managed files no longer shipped are backed up and removed if unchanged. If locally modified, they are backed up and retained with a warning. Backups are stored under backups/<timestamp>/ in each destination. Codex skill backups use .agents/.ai-config-skill-backups/ instead, so Codex does not discover backup copies as skills. Existing .agents/skills/backups/ content is moved there on the next install, update, or uninstall. Codex config.toml synchronization merges setup-owned keys while retaining other root keys, extra fields in managed tables, plugin and marketplace tables, other unmanaged tables, and unowned array tables. The previous file is backed up when content changes. Claude settings.json synchronization retains unrelated settings and hooks. Every managed file, including config.toml, settings.json, and the manifest, is written to a temporary sibling file and then renamed over the target, so an interrupted run never leaves a partly written file. Each destination is locked through .ai-config.lock while it syncs; a parallel install or update fails instead of interleaving writes. A lock left by an exited process of the same shell on the same host is replaced automatically. Before its first write, each sync records its planned changes in .ai-config-transaction.json; if a run is interrupted, the next install or update first rolls that destination back from the backups (ROLLBACK <destination> <stamp>). Dry runs still rebuild generated/, but do not modify installation destinations.

Selecting Codex also installs shared skills to .agents/skills. An interactive extension list includes plugins and Codex skills; unchecked extensions are skipped on installation. Normal install and update ask whether to enable Flashbang, apply the custom status line, and enable local QMD search. Choices are saved for Quickupdate. The shared skill catalog includes development skills and focused writing, image, site structure, psychology, and conversion skills. All retained skills are included in both generated clients. The status line defaults to enabled to preserve existing behavior. Disabling it removes the custom client setting and, for Claude, the setup-owned status line script. Disabling local QMD search on update removes only its setup-owned package, models, and repository collections. Dry runs preview changes without updating extensions or retrieval. See Plugins for client-specific behavior.

Update Script

Once a destination is installed, use the update script (not the installer) to refresh its files and plugins. It refuses to continue if any selected destination is not installed yet (Not installed, use the install script.), also skipped for a dry run.

PowerShell:

.\scripts\commands\update.ps1

Bash:

./scripts/commands/update.sh

It accepts the same -DryRun/--dry-run, -Client/--client, and -Shell/--shell parameters as the installer, re-syncs every managed file, and lets you revise the status line, Flashbang, retrieval, and extension choices. Selected extensions are installed or updated. Deselection removes only extensions recorded as installed by this setup; pre-existing or manually installed extensions are retained. Quickupdate reuses the saved choices.

Uninstall Script

Remove everything this setup previously installed for the selected client(s): managed files tracked in each destination's manifest, extensions and skills recorded in the extension ledger, an enabled local QMD search setup, and the saved Quickupdate selection (once no destination remains installed for any client).

PowerShell:

.\scripts\commands\uninstall.ps1

Bash:

./scripts/commands/uninstall.sh

Omitting -Client/--client opens the same selection prompt as install and update. Uninstall refuses to continue if none of the selected destinations are installed (Not installed, nothing to uninstall.), unless previewing with -DryRun/--dry-run, which always works and never changes anything.

Because this removes configuration rather than adding it, a real run asks for confirmation (Continue? [y/N]) before touching anything, unless -Force/--force is passed; running without a terminal attached and without -Force/--force fails instead of hanging. Removal reuses the same manifest-sync logic as install and update: every managed file is backed up under backups/<timestamp>/ before removal, and a file changed locally since the last install/update is backed up but left in place with a warning instead of being deleted. Files this setup never installed are never touched. Codex skill backups are kept under .agents/.ai-config-skill-backups/. A destination directory is only deleted once it is fully empty; backups already on disk are always kept. Extensions and skills recorded in the ledger are removed the same way update removes a deselected extension: pre-existing or manually installed ones outside the ledger are left alone, and a skill file modified since it was installed is kept with a warning. An enabled local QMD search setup is disabled and its setup-owned runtime and index removed for the selected client(s). The saved Quickupdate selection (~/.my-ai-configuration/selection.json) is only removed once uninstalling leaves no client installed at all, so uninstalling just one client out of a Both installation keeps the saved choices for the client that remains.

Uninstall does not remove the CLI tools themselves (codex, claude), any plugin marketplace registrations they keep outside this setup's ledger, or files this setup never installed.

Configuration overview

Codex and Claude Code receive the same shared rules, skills, agents, hooks, and status data. Codex loads applicable rules from generated files, while Claude Code exposes technology- and situation-specific rules as generated skills.

Codex defaults to workspace-write sandboxing and automatic review for eligible escalation requests. Claude uses automatic permissions and enables its sandbox where the platform supports it; explicit deny rules still apply where it does not. Both clients include the same logical agent roles and compact status displays. See Configuration for settings, permissions, and limitations.

Support

Create an issue for problems or proposed changes.

Contributors

~ FrauJulian - Julian Lechner

License

Licensed under the MIT License.