Aegis for CodeBuddy

July 9, 2026 ยท View on GitHub

Guide for using Aegis with CodeBuddy through CodeBuddy's native skills and plugin-compatible distribution paths.

This page only covers the CodeBuddy host install path. For the current Aegis Method Pack authority order, release gate, host compatibility status, and known limitations, read:

  • docs/current/README.md
  • docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md
  • docs/current/AEGIS_METHOD_PACK_RELEASE_CHECKLIST.md
  • docs/current/AEGIS_KNOWN_LIMITATIONS.md

Current Verdict

CodeBuddy is structurally compatible with Aegis because it supports:

  • SKILL.md skills
  • user and project skill directories
  • plugin bundles that can include skills/, commands/, and hooks/
  • a CodeBuddy plugin metadata directory
  • compatibility with Claude Code plugin metadata

Aegis now ships a CodeBuddy plugin skeleton:

  • .codebuddy-plugin/plugin.json
  • .codebuddy-plugin/marketplace.json
  • skills/
  • commands/
  • hooks/

This means CodeBuddy is a supported product target. It does not mean CodeBuddy has current release-level fresh smoke evidence yet. The current compatibility matrix still records CodeBuddy as pending broader host rollout.

Keep a local Aegis checkout and install skills from it. This preserves both skill discovery and project workspace support verification.

Manual Skills Installation

Use this path when you want the most transparent install without relying on a marketplace flow.

macOS / Linux

git clone https://github.com/GanyuanRan/Aegis.git ~/.codebuddy/aegis
mkdir -p ~/.codebuddy/skills
cp -R ~/.codebuddy/aegis/skills/* ~/.codebuddy/skills/

Windows PowerShell

git clone https://github.com/GanyuanRan/Aegis.git "$env:USERPROFILE\.codebuddy\aegis"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codebuddy\skills"
Copy-Item -Recurse -Force "$env:USERPROFILE\.codebuddy\aegis\skills\*" "$env:USERPROFILE\.codebuddy\skills\"

The copy puts each Aegis skill directly at:

~/.codebuddy/skills/<skill-name>/SKILL.md

Because the checkout remains at ~/.codebuddy/aegis, project workspace support can be verified from that method-pack root.

Project-Local Installation

Inside a project where you want Aegis to be available:

mkdir -p .codebuddy/skills
cp -R /path/to/Aegis/skills/* .codebuddy/skills/

Use a project-local install when you want Aegis scoped to one repository instead of every CodeBuddy session on the machine.

Plugin Installation

CodeBuddy supports plugin metadata. Aegis provides .codebuddy-plugin/ for the CodeBuddy-specific path and keeps .claude-plugin/ as a compatible fallback.

For local development or smoke testing from a checked-out copy, use CodeBuddy's local plugin or marketplace flow for the repository, then restart or reload CodeBuddy according to the host prompt.

If the plugin command is unavailable or fails on a local machine, use the manual skills installation above and treat the plugin flow as pending environment verification.

Verification

After installation, start a new CodeBuddy session and ask:

Tell me about your Aegis skills and which one you would use before debugging a failing test.

Then run complete-install verification from the local Aegis checkout:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py --write-config --json

Do not run the doctor command from the target project directory; it belongs to the installed Aegis method-pack root.

Treat the install as complete only if the JSON reports "ok": true, "workspaceSupport": "available", and "configStatus": "configured".

Expected result:

  • CodeBuddy can see Aegis skills such as using-aegis, systematic-debugging, and brainstorming.
  • CodeBuddy can load the relevant skill on demand.
  • Project workspace support can be verified when the local checkout remains available.
  • CodeBuddy does not present Aegis as a full runtime platform or final completion authority.

Portable goal entry:

Aegis goal: Fix the auth refresh bug without rewriting the auth system.

Use this when you want goal-framing to set goal, success evidence, stop condition, and non-goals before routing onward. /aegis-goal <task> is an optional shortcut only when the current host/session supports slash-style aliases.

Updating

macOS / Linux

cd ~/.codebuddy/aegis
git pull
cp -R ~/.codebuddy/aegis/skills/* ~/.codebuddy/skills/

Windows PowerShell

Set-Location "$env:USERPROFILE\.codebuddy\aegis"
git pull
Copy-Item -Recurse -Force "$env:USERPROFILE\.codebuddy\aegis\skills\*" "$env:USERPROFILE\.codebuddy\skills\"

Restart CodeBuddy after updating.

Activation Mode

CodeBuddy uses native skill discovery for manually installed skills. The .codebuddy-plugin/ metadata exists for plugin distribution, but this repository does not currently ship a CodeBuddy-specific bootstrap hook.

That means AEGIS_ACTIVATION_MODE=explicit does not override CodeBuddy's own skill matcher by itself. For explicit use, ask CodeBuddy to load an Aegis skill directly, such as using-aegis or systematic-debugging.

You can still write the shared user-local Aegis config from the installed method-pack root:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py activation-mode explicit

Switch back to automatic mode with:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py activation-mode auto

Restart CodeBuddy or start a new session after changing local Aegis config. For this host, the command does not override CodeBuddy's native matcher.

Uninstalling

For manual skills installs, remove the copied Aegis skill directories from:

~/.codebuddy/skills/

If you installed through a CodeBuddy plugin flow, uninstall through CodeBuddy's plugin manager and then restart the host.

Troubleshooting

Skills are not visible

  1. Confirm a copied skill exists at ~/.codebuddy/skills/<skill-name>/SKILL.md or .codebuddy/skills/<skill-name>/SKILL.md.
  2. Restart CodeBuddy or start a new session.
  3. Ask CodeBuddy to list or describe available Aegis skills.
  4. Check whether a project-local skill with the same name is taking precedence.

Project workspace support not verified

If Aegis was installed by copying only skills/, the host may discover skills but not prove complete project workspace support. Keep or restore the local checkout, then run this from that checkout, not from the target project directory:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py --write-config --json

The JSON should include "workspaceSupport": "available" and "configStatus": "configured".

CodeBuddy CLI is installed but not runnable

If codebuddy --version or codebuddy --help fails, fix the local CodeBuddy CLI installation before treating any live smoke as valid. A binary on PATH is not enough to claim release-level host compatibility.

Official CodeBuddy References