MyAiConfiguration/README.md

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 platform-specific packages that can be inspected before they are installed.

Features

• One shared source of truth for Codex and Claude Code.
• Separate generated packages for Windows and Linux.
• 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 and update scripts: install refuses to run against an already-installed destination, update refuses to run against one that is not installed yet.
• User-level plugin installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, Humanizer, Impeccable, and Anthropic Frontend Design, with an interactive per-plugin toggle during both install and update; update pre-checks plugins that are already installed, so unchecking one uninstalls it and checking one installs or updates it.

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 Windows and Linux packages. This directory is ignored by Git.
scripts/	Build, installation, update, diagnosis, and platform validation entry points.
docs/	Focused documentation about the configuration design.

The build creates:

generated/
├── codex-windows/
├── claude-windows/
├── codex-linux/
└── claude-linux/

Requirements

• Windows PowerShell 5.1 or newer on Windows.
• Bash 4.3 or newer on Linux, with standard utilities such as awk, sed, and sha256sum.
• Python 3.11 or newer for configuration validation (python for PowerShell scripts, python3 for Bash scripts).
• Git for marketplace installation and branch display; Node.js/npm (npx) for Codex's external skill installers.
• jq for Claude's Bash status line; without it, that status line produces no output.
• The Codex and Claude Code CLIs for the clients that should be installed or diagnosed.
• Network access for plugin installation and updates.

The Bash scripts do not require PowerShell. The PowerShell scripts remain compatible with Windows PowerShell 5.1; PowerShell 7 can also run them.

Build

Run the matching command from the repository root:

Powershell: (Windows)

.\scripts\build.ps1

Bash: (Linux)

./scripts/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.

Installation

The installer asks for the target platform 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 Linux or Windows 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: (Windows)

.\scripts\install.ps1 -DryRun 

Bash: (Linux)

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

Install the selected configuration interactively:

Powershell: (Windows)

.\scripts\install.ps1 

Bash: (Linux)

./scripts/install.sh 

Omitting either target parameter opens its selection prompt. There is no automatic platform 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. Local Codex plugins and marketplaces tables are preserved when syncing config.toml; other local settings are not generally merged. Dry runs still rebuild generated/, but do not modify installation destinations.

Selecting Codex also installs shared skills to .agents/skills. Before plugins are installed, an interactive list lets you toggle each configured plugin on or off (all checked by default); unchecked plugins are skipped. This step is also skipped for a dry run. Codex-only selection omits Humanizer, Impeccable, and Anthropic Frontend Design because they use separate skill installers and are always ensured. See Plugins for client-specific behavior.

Update

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: (Windows)

.\scripts\update.ps1 

Bash: (Linux)

./scripts/update.sh 

It accepts the same -DryRun/--dry-run, -Client/--client, and -Platform/--platform parameters as the installer, re-syncs every managed file the same way, and shows the same plugin toggle list — but pre-checks plugins that are already installed. Checking a plugin that is not installed installs it; checking one that is installed updates it; unchecking an installed plugin uninstalls it. Selection happens before managed files are synchronized. For Both, the initial selection follows Claude's installed plugins, not the union of both clients.

Doctor

Check client availability, generated packages, source directories, hooks, and installed managed files:

Powershell: (Windows)

.\scripts\doctor.ps1 

Bash: (Linux)

./scripts/doctor.sh 

Use -Summary (PowerShell) or --summary (Bash) with build, doctor, install, update, and test scripts for compact output. Omit the flag for detailed output. Summary mode retains warnings and failure status, but can suppress captured plugin-command output on failure. Set AI_CONFIG_VERBOSE=1 when full plugin failure output is needed.

Configuration

Codex receives global instructions, rules, skills, agent TOML files, hooks, and config.toml. Its defaults keep writes workspace-scoped and use automatic review for eligible escalation requests. Every rule ships as a plain file under rules/, and AGENTS.md tells Codex to load the matching one by path.

Claude Code receives the equivalent global instructions, agents, hooks, and settings.json. General rules are embedded once in CLAUDE.md (and in Codex's AGENTS.md); every technology- or situation-specific rule (adapters/claude/rule-skills.tsv) is generated as a skill under skills/rules/ instead, so only its name and description are permanently visible and the full rule text loads only when Claude invokes it. Its generated settings use the supported automatic permission mode where available.

Both clients receive the same logical agent roles:

• Architect
• Implementer
• Researcher
• Reviewer
• Verifier

Agent use is proportional to the task. Small changes can stay with the implementer, while additional roles are available when research, design, independent review, or focused verification adds value.

Verification is also proportional: the agent selects checks based on changed behavior, affected callers, risk, and uncertainty. A small change may need only focused inspection; builds, tests, and separate reviews are not automatic. Explicit user and project requirements still apply.

Both status displays include model, effort, repository, branch, context-window size, context used, and tokens used. Claude uses two colored lines, with context usage turning yellow at 60% and red at 85%. Codex uses its native status items and rendering. See Configuration for details and limitations.

Extending the Configuration

Add a rule

Create a focused Markdown file in shared/rules/. For a rule that applies only to a language, framework, tool, or change area, add a row to adapters/claude/rule-skills.tsv (Claude generates it as a skill) and add its loading condition to the Codex rule-loading text in scripts/build.ps1/scripts/build.sh (Codex loads it as a plain file, by path). Put always-applicable guidance in general.md, which the build embeds for both clients; a new rule file is not automatically embedded.

Add a skill

Create shared/skills/<category>/<skill>/SKILL.md with valid YAML frontmatter and a concise workflow. Reference shared rules instead of repeating persistent standards.

Add an agent

Create shared/agents/<agent>/agent.yml and instructions.md. Keep semantic behavior in these shared files; the build renders the Codex and Claude Code formats.

Rebuild after every semantic change.

Security

• Never store API keys, OAuth tokens, credentials, authentication state, or sensitive logs in this repository.
• Review generated output and use the installer's dry-run before installation.
• Global installation happens only through an explicit installer invocation.
• Plugins execute with permissions granted by their client; review their upstream sources and trust prompts.
• Codex keeps workspace sandboxing enabled and requires escalation outside expected development boundaries.

Support

Create an issue for problems or proposed changes.

Contributors

~ FrauJulian - Julian Lechner

License

Licensed under the MIT License.