[!TIP]

Kord AIOS — multi-model agent orchestration meets story-driven development methodology. Built on Oh-My-Opencode + Synkra AIOS. 20+ specialized agents, squads, 149 skills, background tasks, LSP/AST tooling. npm package: kord-aios.

✅ Official repository: https://github.com/GDSDN/kord-aios

[!NOTE]

Versioning: Kord AIOS may reset public semver to 1.x even if earlier npm versions exist from upstream history. Always install via the npm latest tag unless you intentionally pin an older version.

Contents

• What is Kord AIOS?
• Quick Start
• Installation
• Architecture
  • Agents
  • Squads
  • Skills
  • Background Agents
• Features
  • Commands
  • Hooks
  • Tools
  • MCPs
  • Context Injection
  • Claude Code Compatibility
• Configuration
• Uninstallation
• Origin Story
• Contributing

What is Kord AIOS?

Kord AIOS is a version of Synkra AIOS built on top of Oh-My-Opencode — combining the best of both worlds: Synkra's proven agent methodology with Oh-My-Opencode's powerful plugin runtime.

Kord transforms your terminal into a full AI development team. Instead of one agent doing everything, Kord orchestrates 20+ specialized agents — each with the right model for the right job — working in parallel on your codebase.

Kord AIOS combines:

• Engine: OpenCode-native plugin runtime with background agents, parallel execution, LSP/AST tooling, Claude Code compatibility.
• Methodology: Story-driven execution, squads, quality gates, and battle-tested development skills.

Naming: The project is Kord AIOS. The npm package is kord-aios. The config file is kord-aios.json.

Quick Start

Include ultrawork (or just ulw) in your prompt. That's it.

Parallel agents, background tasks, deep exploration, and relentless execution activate automatically. The agent figures out the rest.

Installation

For Humans

Read the Installation Guide or paste it to your LLM agent and let it handle the setup.

For LLM Agents

Read and follow docs/guide/installation.md.

Note: Use bunx kord-aios init for setting up new projects if you have already installed Kord AIOS globally.

Architecture

Agents (20+)

Kord AIOS ships a full development team. All agents are customizable — override models, temperatures, prompts, and permissions in kord-aios.json.

Orchestration Layer

| Agent | Model | Role | |-------|-------|------| | Kord | Claude Opus 4.6 | Master orchestrator — delegates, plans, reviews | | Dev | GPT 5.3 Codex | Autonomous deep worker — goal-oriented, explores before acting | | Plan | Claude Opus 4.6 | Strategic planner with interview and high-accuracy modes | | Plan Reviewer | GPT 5.2 | Validates plan feasibility | | Plan Analyzer | Claude Opus 4.6 | Pre-planning analysis |

Specialist Layer

| Agent | Model | Role | |-------|-------|------| | Architect | GPT 5.2 | System design, debugging, strategic consultation | | Librarian | GLM 4.7 | Documentation search, open-source code exploration | | Explore | Grok Code Fast 1 | Blazing fast codebase grep | | UX Design Expert | Gemini 3 Pro | Frontend development and design | | Vision | Gemini 3 Flash | Image/screenshot/PDF analysis | | Data Engineer | — | Data pipeline methodology | | DevOps | — | Infrastructure and CI/CD |

Methodology Layer

| Agent | Role | |-------|------| | PM | Project Manager — epic structuring, wave planning | | PO | Product Owner — quality gate before dev execution | | QA | Quality assurance and test strategy | | SM | Scrum Master — sprint coordination, stateless Dev awareness | | Analyst | Strategic analysis and research | | Squad Creator | Creates new SQUAD.yaml manifests |

Squads

Squads are portable, reusable orchestration-aware domain packages. A squad brings domain-specialized agents, package assets (workflows/tasks/templates), skill references, and orchestration metadata — all defined in a single SQUAD.yaml manifest. The built-in default is code (src/features/builtin-squads/code/SQUAD.yaml).

Chief + Worker Model: Squads support L2 (chief) and L1 (worker) agent hierarchy. Chiefs have is_chief: true with auto-generated Squad Awareness and coordination protocol. Workers are standard subagents.

Naming Convention: Squad agents are registered with prefixed names (squad-{squadName}-{yamlKey}) to prevent collisions across squads.

Agent Fields: fallback (per-agent fallback chain) and write_paths (extra write authority paths) are supported in SQUAD.yaml. write_paths is validated (relative only, no .., no root **, no docs/kord/ prefix).

Chief Permissions: Chiefs auto-enable permission.task = "allow" unless tools explicitly overrides task.

# .opencode/squads/my-squad/SQUAD.yaml
name: my-squad
description: My custom agent team

agents:
  chief:
    description: "Squad leader"
    is_chief: true
    mode: all
  specialist:
    description: "Domain expert"
    model: anthropic/claude-sonnet-4-5
    prompt: "You are a domain specialist..."

components:
  workflows: ["workflows/main.yaml"]
  tasks: ["tasks/create-campaign.md"]

orchestration:
  runner: workflow-engine
  delegation_mode: chief

Skills (149)

Battle-tested development methodologies encoded as SKILL.md files with YAML frontmatter. Each skill is a step-by-step instruction set for a specific development domain — from Git workflows to API design to testing strategies.

Skills are loaded from:

• src/features/builtin-skills/skills/ — shipped with the plugin
• .opencode/skills/ — project-specific
• ~/.config/opencode/skills/ — user-global
• .claude/skills/ — Claude Code compatible

Background Agents

Run multiple agents in parallel with per-provider and per-model concurrency management. Kord fires off exploration tasks to cheaper, faster models while the main agent focuses on implementation.

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": { "anthropic": 3, "openai": 5 },
    "modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
  }
}

Features

Full documentation: docs/guide/features.md | Configuration: docs/guide/configurations.md

Summary:

• 20+ Specialized Agents — right model for the right task, full dev team
• Squad System — SQUAD.yaml v2 manifests for domain-specific agent teams
• 149 Skills — battle-tested development workflows (5 hardcoded + 144 methodology)
• Background Agents — parallel async execution with concurrency limits
• LSP & AST Tools — structural refactoring, rename, diagnostics, AST-aware search
• 40+ Lifecycle Hooks — context injection, productivity automation, quality gates, recovery
• 12 Slash Commands — init-deep, ralph-loop, ulw-loop, refactor, start-work, checkpoint, status, squad, and more
• Built-in MCPs — web search (Exa), documentation (Context7), GitHub code search (Grep.app)
• Context Injection — auto-inject AGENTS.md, README, conditional rules per directory
• Claude Code Compatibility — full compat layer for commands, skills, agents, MCPs, hooks
• Todo Enforcer — forces completion, no half-finished work
• Comment Checker — prevents AI comment bloat, keeps code human-like
• Tmux Integration — visual multi-agent dashboard, watch agents work in parallel
• Story-Driven Pipeline — wave/story execution with persistent state
• CLI Installer — interactive setup with project maturity detection and doctor checks

Commands

| Command | Description | |---------|-------------| | /init-deep | Generate hierarchical AGENTS.md files throughout your project | | /ralph-loop | Self-referential dev loop — runs until task is 100% complete | | /ulw-loop | Ultrawork loop — ralph-loop with max parallel intensity | | /cancel-ralph | Cancel active loop | | /refactor | Intelligent refactoring with LSP, AST-grep, TDD verification | | /start-work | Start Build agent execution from a Plan-generated plan | | /stop-continuation | Stop continuation mechanisms for the current session | | /checkpoint | Trigger a PO checkpoint decision on current execution | | /status | Show current plan progress, wave, and pending items | | /squad | Switch active squad context | | /squad-create | Create a specialized squad for a domain | | /modelconfig | View and configure model routing per agent |

Custom commands: .opencode/commands/*.md or .claude/commands/*.md

Hooks (40+)

Hooks intercept agent lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop.

| Category | Hooks | Purpose | |----------|-------|--------| | Context | directory-agents-injector, readme-injector, rules-injector, compaction-context-injector | Auto-inject AGENTS.md, README, rules when reading files | | Productivity | keyword-detector, think-mode, ralph-loop, auto-slash-command | Activate modes (ultrawork/ulw), think deeply, loop execution | | Quality | comment-checker, thinking-block-validator, edit-error-recovery | Prevent comment bloat, validate blocks, recover from failures | | Recovery | session-recovery, context-window-limit-recovery, background-compaction | Handle errors, context limits, auto-compact | | Truncation | grep-output-truncator, tool-output-truncator | Dynamically truncate output to keep context lean | | Notifications | auto-update-checker, background-notification, session-notification | Version checks, task completion, OS notifications |

Disable specific hooks: "disabled_hooks": ["comment-checker"] in config.

Tools

LSP (IDE Features for Agents)

| Tool | Description | |------|-------------| | lsp_diagnostics | Errors/warnings before build | | lsp_rename | Rename symbol across workspace | | lsp_goto_definition | Jump to definition | | lsp_find_references | Find all usages | | lsp_symbols | File outline or workspace search |

AST-Grep — ast_grep_search and ast_grep_replace for pattern search/replace across 25 languages.

Delegation — task (category-based routing: visual, business-logic, custom), call_kord_agent (direct spawn with run_in_background), background_output / background_cancel.

Session — session_list, session_read, session_search, session_info for browsing agent session history.

Interactive Terminal — interactive_bash for tmux-based TUI apps (vim, htop, pudb).

MCPs (Built-in)

| MCP | Purpose | |-----|--------| | websearch | Real-time web search (Exa AI) | | context7 | Official documentation lookup for any library/framework | | grep_app | Code search across public GitHub repos |

Skills can embed their own MCP servers via YAML frontmatter, including OAuth-protected remote MCPs with full RFC compliance.

Context Injection

• AGENTS.md — auto-injected when reading files (walks file directory → project root, collecting all AGENTS.md)
• README.md — directory context injection
• Conditional rules — .claude/rules/*.md with glob patterns and alwaysApply

Claude Code Compatibility

Full compatibility layer for Claude Code configurations:

| Type | Locations | |------|----------| | Commands | ~/.claude/commands/, .claude/commands/ | | Skills | ~/.claude/skills/*/SKILL.md, .claude/skills/*/SKILL.md | | Agents | ~/.claude/agents/*.md, .claude/agents/*.md | | MCPs | ~/.claude/.mcp.json, .mcp.json (with ${VAR} expansion) | | Hooks | settings.json hook execution |

Toggle features: "claude_code": { "mcp": false, "commands": false, ... } in config.

Configuration

Config file: .opencode/kord-aios.json (project) or ~/.config/opencode/kord-aios.json (user).

JSONC supported — comments and trailing commas work.

What you can configure:

• Agent models, temperatures, prompts, and tool permissions
• Background task concurrency per provider/model
• Disabled hooks, skills, agents
• Category-based task delegation routing
• Built-in MCPs (websearch, context7, grep_app)
• LSP and experimental features

OpenCode Agent Overrides

You can override methodology agents from disk with .opencode/agents/*.md and ~/.config/opencode/agents/*.md.

• Agent keys are derived from filename (course-creator.md -> course-creator).
• Frontmatter write_paths is enforced by agent-authority to gate file writes.
• T0 agents (kord, dev, builder, planner) are protected and cannot be overridden from OpenCode agent files.

See the full Configuration Documentation for details.

Uninstallation

To remove Kord AIOS:

1. Remove the plugin from your OpenCode config

   Edit ~/.config/opencode/opencode.json (or opencode.jsonc) and remove "kord-aios" from the plugin array:

   jq '.plugin = [.plugin[] | select(. != "kord-aios")]' \
       ~/.config/opencode/opencode.json > /tmp/oc.json && \
       mv /tmp/oc.json ~/.config/opencode/opencode.json

2. Remove configuration files (optional)

   rm -f ~/.config/opencode/kord-aios.json
   rm -f .opencode/kord-aios.json

3. Verify removal

   opencode --version
   # Kord AIOS should no longer be loaded

Origin Story

I wanted a disciplined way to run AI development workflows without giving up control of models and runtime behavior.

OpenCode provided the open, multi-model engine. Kord AIOS adds the orchestration and methodology layer on top: squads, story-driven execution, quality gates, and specialized agents.

Kord AIOS is the result: structured execution with full control over models, prompts, tools, skills, and squads.

Contributing

See CONTRIBUTING.md for development setup, code conventions, and PR guidelines.

Warnings

• Requires OpenCode >= 1.0.150.
• If you're on 1.0.132 or older, an OpenCode bug may break config.
  • The fix was merged after 1.0.132 — use a newer version.