Karl AI Agent Dotfiles

Orchestrated OpenCode agents with self-contained prompts. karl-orchestrator runs as the primary session (mode: primary) and routes phase work to managed subagents. Worker, scout, and reviewer run only as subagents and never delegate further:

Select the karl-orchestrator agent as the primary session.
The orchestrator routes mapping to karl-scout, bounded writes to karl-worker,
and independent evaluation to karl-reviewer.

ORCHESTRATOR owns routing, scope, and the final ready/not-ready decision. WORKER owns a change inside the given scope. REVIEWER adversarially re-validates the result by re-running verification against the acceptance criteria using the worker evidence as claims, without repairing. SCOUT returns cited facts, gaps, and dead ends without recommendations. Each agent prompt is self-contained: role, procedure, safety, and return contract live in the agent file. External non-Karl skills remain allowed.

Distribution

Content	OpenCode
Entry rules	None (routing lives in the orchestrator agent prompt, no managed block)
Orchestrator	harnesses/opencode/agents/karl-orchestrator.md, mode: primary
Worker	harnesses/opencode/agents/karl-worker.md, mode: subagent
Reviewer	harnesses/opencode/agents/karl-reviewer.md, mode: subagent
Scout	harnesses/opencode/agents/karl-scout.md, mode: subagent

Files under harnesses/opencode/agents/ hold the full agent context: permissions, mode, role, procedure, safety, and return contract. There are no karl-* skills; each prompt is self-contained. Agent files carry no model:; model selection lives in profiles/ and is applied by the installer (see below).

Install

The installer is split by platform: install.ps1 is Windows-only, install.sh covers Linux and macOS. Both installers have the same contract and the same flag semantics.

On Windows, PowerShell 7 is required and Developer Mode must be enabled to create symlinks without elevation. On Linux and macOS, the installer uses POSIX sh and normal symlink support and does not query the Windows registry.

Windows:

pwsh -File "$HOME/.agents/install.ps1" -DryRun
pwsh -File "$HOME/.agents/install.ps1"

Linux and macOS:

sh install.sh --dry-run
sh install.sh

install.sh flags mirror the PowerShell switches: --dry-run (-DryRun), --force (-Force), --uninstall (-Uninstall), --target-home <dir> (-TargetHome), --repo <url-or-path> (-RepoUrl), and --profile <name> (-Profile).

Install from GitHub URL

Both installers can bootstrap the repository themselves — no manual git clone step:

Linux and macOS:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/Carlos0934/karl-ai/master/install.sh)" -- --repo https://github.com/Carlos0934/karl-ai.git

Windows (PowerShell 7):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Carlos0934/karl-ai/master/install.ps1))) -RepoUrl https://github.com/Carlos0934/karl-ai.git

--repo (-RepoUrl) clones the repository into ~/.agents and runs the normal install from that clone. Private repositories use your existing git credentials, or a token-embedded HTTPS URL (never commit one). Re-running the same command updates the clone with git pull --ff-only. If ~/.agents exists but is not a matching clone, the installer refuses; re-run with --force (-Force) to back it up and re-clone.

The installer:

1. Validates the agent frontmatter (mode, description, permissions).
2. Removes any legacy block delimited by karl-ai comments in global AGENTS.md files (OpenCode-only now; Codex support was dropped).
3. Creates per-file symlinks for the OpenCode custom agents.
4. Removes legacy Codex karl-*.toml links.
5. Applies the selected agent model profile (karl-default unless -Profile/--profile says otherwise) to the global opencode.json.
6. Keeps backups under ~/.agents-backup/<timestamp>/ before replacing content (profile JSON backups sit next to opencode.json).

If a custom agent already exists and is not the expected symlink, the installer stops. Use -Force to back it up and replace it.

Uninstall

Windows:

pwsh -File "$HOME/.agents/install.ps1" -Uninstall -DryRun
pwsh -File "$HOME/.agents/install.ps1" -Uninstall

Linux and macOS:

sh install.sh --uninstall --dry-run
sh install.sh --uninstall

Uninstall removes only:

• blocks delimited by <!-- karl-ai: controlled-development -->
• symlinks whose target is inside this repository

Uninstall does not remove other rules, skills, or agents.

Sync to Another Machine

git clone <private-repository> "$HOME/.agents"
pwsh -File "$HOME/.agents/install.ps1"

On Linux or macOS run sh install.sh instead of the pwsh command after cloning.

External skills installed by other managers stay local and are not part of this repository. This repository ships no skills; agent context lives in the agent files.

Agent Model Profiles

profiles/*.json maps each karl-* agent to its model (<provider>/<model>#<effort>, effort optional). The agent files ship without model: in the frontmatter; the model comes from the applied profile:

Agent	karl-default	openai	contributor
karl-orchestrator	opencode-go/mimo-v2.6-pro	openai/gpt-6-sol#medium	opencode-go/muse-spark-1.3-contributor#high
karl-worker	opencode-go/glm-5.3-flash#high	openai/gpt-6-luna#xhigh	opencode-go/longcat-2.5-preview-free#high
karl-scout	opencode-go/gpt-6-luna#high	openai/gpt-6-luna#high	opencode-go/longcat-2.5-preview-free#high
karl-reviewer	opencode-go/gpt-6-luna#xhigh	openai/gpt-6-sol#high	opencode-go/muse-spark-1.3-contributor#xhigh

All IDs above exist in opencode models. An agent with no agent.<name>.model entry falls back to the primary's model (OpenCode subagent inheritance).

The installer asks for the profile on an interactive console (default karl-default, none skips) and applies it to the global opencode.json after linking the agents. Non-interactive runs apply karl-default without asking; pass -Profile/--profile explicitly to choose or skip:

pwsh -File "$HOME/.agents/install.ps1" -Profile openai
pwsh -File "$HOME/.agents/install.ps1" -Profile ""

sh install.sh --profile openai
sh install.sh --profile ""

Apply or switch a profile later, from any directory (project scope is the default):

pwsh -File "$HOME/.agents/scripts/apply-opencode-profile.ps1" -Profile openai
pwsh -File "$HOME/.agents/scripts/apply-opencode-profile.ps1" -Profile openai -Scope global

sh scripts/apply-opencode-profile.sh --profile openai
sh scripts/apply-opencode-profile.sh --profile openai --scope global

The script only writes agent.<karl-*>.model keys in the target opencode.json (./opencode.json for project scope, ~/.config/opencode/opencode.json for global). Everything else is preserved. Existing files get a sibling timestamped backup (opencode.json.bak-<timestamp>) unless -Force/--force skips it; --dry-run/-DryRun previews without writing. Use --list/-List to show available profiles. Confirm the effective model with opencode debug config.

Skill Diagnostics

OpenCode does not load ~/.agents/skills when started with:

OPENCODE_DISABLE_EXTERNAL_SKILLS=1

The installer warns if that variable is detected. Remove it from the environment before starting OpenCode; no need to duplicate or link skills into ~/.config/opencode/skills.

E2E

The offline tests run the full install/uninstall cycle in a temporary home. No credentials, Pester, or other dependencies required.

Windows (pwsh):

pwsh -NoProfile -File tests/e2e/install-lifecycle.ps1
pwsh -NoProfile -File tests/e2e/opencode-profile.ps1

Linux and macOS (sh):

sh tests/e2e/install-lifecycle.sh
sh tests/e2e/opencode-profile.sh

From any host you can reproduce the CI Debian install/uninstall run with Docker:

docker run --rm --mount "type=bind,source=$PWD,target=/repo" -w /repo debian:bookworm-slim sh tests/e2e/install-lifecycle.sh

CI validates the install/uninstall lifecycle and the profile apply lifecycle in three environments on every push, pull_request, manual run, and schedule:

• windows-latest with pwsh (install.ps1, Windows-only)
• debian:bookworm-slim container (on an Ubuntu runner) with POSIX sh, plus shellcheck on install.sh and the sh E2E
• macos-latest with POSIX sh, plus the same shellcheck

Action logs are published as diagnostic artifacts. TestResults/ is git-ignored.