Julian lechner
5e80d30936
CI / CI configuration security checks (push) Successful in 3s
CI / Capabilities and shell quality (push) Successful in 18s
CI / Python tests and compilation (push) Successful in 25s
CI / QMD unit tests (push) Successful in 11s
CI / Build and inspect generated packages (push) Successful in 17s
CI / PowerShell tests on Ubuntu (push) Successful in 1m11s
CI / Installed client configuration smoke tests (push) Successful in 1m10s
CI / Bash integration and installation guards (push) Failing after 1m13s
322 lines
16 KiB
Markdown
322 lines
16 KiB
Markdown
# My AI Configuration
|
|
|
|
|
|
|
|
|
|
|
|
[](LICENSE)
|
|
|
|
`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:
|
|
|
|
```powershell
|
|
.\scripts\commands\check-capabilities.ps1
|
|
```
|
|
|
|
Bash:
|
|
|
|
```bash
|
|
./scripts/commands/check-capabilities.sh
|
|
```
|
|
|
|
## Quickstart
|
|
|
|
With the [requirements](#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:
|
|
|
|
```powershell
|
|
git clone https://git.lechner-systems.at/fraujulian/MyAiConfiguration.git
|
|
cd MyAiConfiguration
|
|
.\scripts\commands\build.ps1 -Summary
|
|
.\scripts\commands\install.ps1 -Summary
|
|
```
|
|
|
|
Bash:
|
|
|
|
```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:
|
|
|
|
```powershell
|
|
git pull --ff-only
|
|
.\scripts\commands\build.ps1 -Summary
|
|
.\scripts\commands\update.ps1 -Quick -Summary
|
|
```
|
|
|
|
Bash:
|
|
|
|
```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 or 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
|
|
|
|
```text
|
|
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/`](docs/scripts.md) | Build, installation, update, diagnosis, and validation scripts. |
|
|
| `docs/` | Focused documentation about the configuration design. |
|
|
|
|
Client settings start in `adapters/codex/config/config.toml` and
|
|
`adapters/claude/config/settings.json`. Shared Markdown and metadata define behavior;
|
|
adapters supply client-specific formats and placeholders resolved during build or installation.
|
|
Generated output is not a source to edit.
|
|
|
|
The build creates:
|
|
|
|
```text
|
|
generated/
|
|
|-- codex-powershell/
|
|
|-- claude-powershell/
|
|
|-- codex-bash/
|
|
`-- claude-bash/
|
|
```
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
| --- | --- |
|
|
| [Scripts](docs/scripts.md) | Commands, checks, tests, and internal script layout. |
|
|
| [Configuration](docs/configuration.md) | Client settings, permissions, status displays, local QMD search, and verification. |
|
|
| [Extending the configuration](docs/extending-configuration.md) | Add shared rules, skills, and agents. |
|
|
| [Plugins](docs/plugins.md) | Plugin sources, selection, installation, updates, and removal. |
|
|
| [Hooks](docs/hooks.md) | Registered events, session-state helpers, notifications, and optional utilities. |
|
|
| [Agents](docs/agents.md) | Agent roles and when delegation is useful. |
|
|
| [Skills](docs/skills.md) | Skill categories and conditional rule loading. |
|
|
| [Hook package](shared/hooks/README.md) | Overview shipped with the hook scripts. |
|
|
| [Repository instructions](AI-Instructions.md) | Rules for maintaining this repository. |
|
|
|
|
## Build Script
|
|
|
|
Run the matching command from the repository root:
|
|
|
|
PowerShell:
|
|
```powershell
|
|
.\scripts\commands\build.ps1
|
|
```
|
|
|
|
Bash:
|
|
```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:
|
|
```powershell
|
|
.\scripts\commands\install.ps1 -DryRun
|
|
```
|
|
|
|
Bash:
|
|
```bash
|
|
./scripts/commands/install.sh --dry-run
|
|
```
|
|
|
|
Install the selected configuration interactively:
|
|
|
|
PowerShell:
|
|
```powershell
|
|
.\scripts\commands\install.ps1
|
|
```
|
|
|
|
Bash:
|
|
```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; installation includes `semantic-search` only when local QMD search is enabled.
|
|
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 removes its setup-owned package, models, and repository collections once no client still uses it. See [Local QMD search](docs/configuration.md#local-qmd-search) for storage and removal details.
|
|
Dry runs preview changes without updating extensions or retrieval. See [Plugins](docs/plugins.md) 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:
|
|
```powershell
|
|
.\scripts\commands\update.ps1
|
|
```
|
|
|
|
Bash:
|
|
```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:
|
|
```powershell
|
|
.\scripts\commands\uninstall.ps1
|
|
```
|
|
|
|
Bash:
|
|
```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. Local QMD search is disabled for the selected client(s). Its shared runtime,
|
|
owned models, and recorded repository collections are removed only when no client still uses it; the shared QMD database and foreign collections are retained. 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 full access under the account that launches it, with unrestricted command network access.
|
|
Launch Codex as the repository owner; Codex does not switch to that owner automatically. Full access removes
|
|
Codex's filesystem sandbox boundaries. Eligible approval requests still use automatic review. 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](docs/configuration.md) for settings, permissions, and limitations.
|
|
|
|
## Support
|
|
|
|
Create an [issue](https://git.lechner-systems.at/fraujulian/MyAiConfiguration/issues) for problems or proposed changes.
|
|
|
|
## Contributors
|
|
|
|
~ [**FrauJulian - Julian Lechner**](https://fraujulian.xyz/)
|
|
|
|
## License
|
|
|
|
Licensed under the [MIT License](LICENSE).
|