Claude shipped two powerful agent primitives this week. They are well-engineered. They solve real problems. And the first question every developer asked was: how do I use this with my existing open-source stack?

This post answers that question. Not with marketing slides, but with architecture patterns, real configuration files, and design-level code previews. We are building the integration layer between Qualixar OS and Claude's agent ecosystem -- subagent definitions that work today, a hybrid topology design that routes tasks between local and cloud execution, and a managed agents adapter that normalizes Claude's cloud runtime into the Qualixar OS orchestrator.

If you want the strategic comparison between managed and open-source agent infrastructure, read our companion post on why agent operating systems matter. This post is about the integration architecture.

What Claude Shipped (Quick Context)

Two primitives. Agent Teams is an experimental feature in Claude Code that enables peer-to-peer teammates -- multiple Claude instances collaborating on a shared task. Managed Agents is a public beta cloud runtime with sandboxing, session persistence, and event streaming. Both are documented at docs.anthropic.com and Anthropic's launch announcement. What follows is the architecture for extending both with an open-source agent OS.

Integration Pattern 1: Subagent Definitions

Claude Agent Teams discovers teammates through markdown files in .claude/agents/. Each file defines a role, available tools, and behavioral constraints. The team lead (the Claude Code session you are talking to) reads these definitions and delegates work to the teammates they describe.

Qualixar OS ships specialist agent definitions that plug directly into this discovery mechanism. When you copy them into your project's .claude/agents/ directory, Claude Code sees them as available teammates. No configuration beyond the file itself.

Here are two definitions that work today.

The Forge Architect

This agent wraps Qualixar OS's POMDP-based team designer into a Claude Code teammate. When the team lead says "design a team for this task," the Forge Architect calls Qualixar OS's MCP tools, proposes a plan with topology selection, agent roles, model routing, and cost constraints, and waits for approval before execution.

Qualixar OS Forge Architect
You are a multi-agent team design specialist powered by Qualixar OS.
Role
Design optimal agent teams using Forge AI's POMDP-based planning.
Given a task description, you select the topology, assign agent roles,
configure model routing, and set cost-quality constraints.
Tools
You have access to Qualixar OS MCP tools:
qos_forge_design — Generate a team plan from a task description
qos_topology_list — List available topologies with trade-offs
qos_cost_estimate — Estimate cost for a proposed team configuration

Workflow
1. Receive task description from team lead
2. Call qos_forge_design with the task
3. Present the proposed team: topology, agents, models, budget
4. Wait for approval before execution
5. On approval, call qos_execute_team to launch
Constraints
Always present cost estimate before execution
Prefer local models for tasks under complexity threshold 0.6
Flag any task requiring PII handling as local-only

The MCP tool names (qos_forge_design, qos_topology_list, etc.) reference Qualixar OS's MCP server. The agent definition file works today as a teammate -- Claude Code discovers and uses it -- but the underlying MCP tools require Qualixar OS to be running with its MCP server registered.

The Quality Judge

This agent solves a gap in Claude Agent Teams: there is no built-in quality gate between teammates completing work and that work being accepted. By adding the judge as a teammate, every output goes through Qualixar OS's multi-judge consensus pipeline before it reaches the team lead.

Qualixar OS Quality Judge
You are a quality gating agent powered by Qualixar OS's judge pipeline.
Role
Evaluate the output of other teammates against defined quality criteria.
Block low-quality outputs from being merged or shipped.
Tools
qos_judge_evaluate — Run output through multi-judge consensus
qos_judge_criteria — List active quality criteria for current project
qos_judge_history — View recent evaluation scores and trends

Workflow
1. Monitor teammate task completions via the shared task list
2. When a task is marked "done," pull the output
3. Run qos_judge_evaluate with the output and relevant criteria
4. If score >= threshold: approve and notify team lead
5. If score < threshold: reject with specific feedback, reassign to original teammate
Constraints
Never approve without running evaluation
Log every evaluation to the Qualixar OS dashboard
Escalate to team lead if three consecutive rejections occur

The evaluation criteria are configurable per project -- code review standards, writing quality thresholds, data accuracy requirements. The judge uses the same scoring engine that backs the Qualixar OS dashboard, so evaluation history and trends are visible across sessions.

Together, these two agents give Claude Agent Teams capabilities it does not have natively: intelligent team design (the Forge Architect picks the right topology and model for each subtask) and automated quality gating (the Judge rejects substandard work before it reaches you). Both are markdown files. Both work with Claude Code today.

Integration Pattern 2: Hybrid Topology Design

Qualixar OS supports 12 execution topologies -- sequential, parallel, hierarchical, debate, mesh, and seven more. We are building a 13th: Hybrid.

The Hybrid topology is a routing-aware execution pattern where some agents run locally on your machine (fast, free, private) and others dispatch to Claude Managed Agents in the cloud (sandboxed, checkpointed, session-persistent). The orchestrator decides where each task runs based on configurable routing criteria.

The routing decision follows a priority chain:

    Task arrives at Orchestrator
              |
              v
    +-------------------+
    | Contains PII?      |---- YES --> LOCAL ONLY
    +---------+---------+
              | NO
              v
    +-------------------+
    | Budget exceeded?   |---- YES --> LOCAL (cheapest)
    +---------+---------+
              | NO
              v
    +-------------------+
    | Needs sandbox?     |---- YES --> MANAGED AGENTS
    +---------+---------+
              | NO
              v
    +-------------------+
    | Latency < 2s?     |---- YES --> LOCAL
    +---------+---------+
              | NO
              v
        BEST AVAILABLE
        (cost-quality optimized)

PII handling always stays local. Code execution that requires sandboxing goes to Managed Agents. Budget constraints force fallback to local models. Everything else follows cost-quality optimization.

Here is the planned configuration format:

> Integration design -- coming in Qualixar OS v2.x. This YAML schema is the planned configuration format. Implementation ships with the hybrid topology feature. Schema is subject to change.

Hybrid Topology — DESIGN PREVIEW
This configuration format ships with Qualixar OS v2.x
Schema is subject to change based on implementation
topology: hybrid
name: "security-audit-team"
routing:
  default: local
  rules:
    - when:
        task_type: "code-execution"
        needs_sandbox: true
      route: managed-agents
      reason: "Untrusted code requires cloud sandbox"
    - when:
        task_type: "data-analysis"
        contains_pii: true
      route: local
      reason: "PII never leaves local infrastructure"
    - when:
        complexity: "high"
        budget_remaining_pct: "> 40"
      route: managed-agents
      reason: "Complex reasoning benefits from managed sessions"
    - when:
        latency_requirement: "< 2s"
      route: local
      reason: "Real-time tasks stay local for speed"
agents:
  - name: code-scanner
    model: claude-sonnet-4
    environment: managed  # Cloud sandbox — runs untrusted code safely
    tools: [file_read, code_execute, vulnerability_scan]
  - name: report-writer
    model: gpt-4o
    environment: local    # No sandbox needed, any model works
    tools: [file_write, template_render]
  - name: pii-detector
    model: ollama/llama-3.3
    environment: local    # PII handling — never leaves your machine
    tools: [regex_scan, entity_extract]
cost:
  budget: 5.00          # USD total
  local_weight: 0.0     # Local execution is free (no per-session fee; model API costs still apply)
  managed_weight: 0.08  # $0.08/session-hour for Claude Managed Agents (public beta pricing)

The budget engine tracks spending across both environments and automatically falls back to local execution when the cloud budget is exhausted. Local execution carries zero per-session runtime fees, though model API costs still apply for non-local models like GPT-4o. Managed Agents sessions cost $0.08 per session-hour at current public beta pricing.

This is what makes the Hybrid topology a first-class primitive rather than a deployment hack. The routing rules, cost tracking, and fallback logic are part of the topology definition itself -- not bolted on after the fact.

Integration Pattern 3: Managed Agents Adapter

Qualixar OS uses the Claw Bridge design pattern: every external runtime gets an adapter that normalizes task submission and result retrieval. The Claude Managed Agents adapter will be the bridge between the Qualixar OS orchestrator and Anthropic's cloud runtime.

> Architecture pattern -- implementation ships with Claw Bridge v2. Claude Managed Agents is in public beta. The HTTP API endpoints shown below are illustrative, derived from the four documented abstractions (Agent, Environment, Session, Events). Actual API paths will be verified against Anthropic's documentation before implementation.

// DESIGN PREVIEW — Architecture pattern for Qualixar OS Claw Bridge v2
// Claude Managed Agents is in PUBLIC BETA. API surface may change.
// Actual API paths will be verified against Anthropic's docs before implementation.
// See: https://docs.anthropic.com/en/docs/build-with-claude/managed-agents
import type { BridgeAdapter, TaskResult, TaskOptions } from 'qualixar-os';
export class ClaudeManagedAdapter implements BridgeAdapter {
  // NOTE: These endpoints are ILLUSTRATIVE based on the public beta's
  // documented abstractions (Agent, Environment, Session, Events).
  // Verify actual paths at docs.anthropic.com before production use.
  private baseUrl = 'https://api.anthropic.com/v1/agents';
  async submitTask(task: TaskOptions): Promise {
    // 1. Create a managed agent session
    const session = await fetch(${this.baseUrl}/sessions, {
      method: 'POST',
      headers: {
        'x-api-key': process.env.ANTHROPIC_API_KEY!,
        'anthropic-version': '2025-01-01',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        model: task.model ?? 'claude-sonnet-4-20250514',
        instructions: task.systemPrompt,
        tools: task.tools,
        environment: {
          sandbox: true,
          network: task.needsNetwork ?? false,
        },
      }),
    });
    const { session_id } = await session.json();
    // 2. Send the task as a message
    const response = await fetch(
      ${this.baseUrl}/sessions/${session_id}/messages,
      {
        method: 'POST',
        headers: {
          'x-api-key': process.env.ANTHROPIC_API_KEY!,
          'anthropic-version': '2025-01-01',
          'content-type': 'application/json',
        },
        body: JSON.stringify({
          message: task.prompt,
        }),
      }
    );
    // 3. Stream SSE events until completion
    const result = await this.streamToCompletion(response);
    // 4. Return normalized result to Qualixar OS orchestrator
    return {
      agentId: task.agentId,
      output: result.content,
      cost: this.calculateCost(result),
      environment: 'managed',
      sessionId: session_id,
    };
  }
}

The pattern is straightforward: create a sandboxed session, send the task prompt, stream SSE events until the agent completes, and return a normalized TaskResult that the orchestrator handles identically to local results. The cost field captures both session-hour charges and token costs, feeding into the dashboard's unified cost tracking.

The adapter abstraction means adding new cloud runtimes follows the same pattern. When Google ships a managed agent runtime, it gets a GoogleManagedAdapter. When OpenAI does, it gets an OpenAIManagedAdapter. The orchestrator does not care where agents run -- it cares about the TaskResult.

Architecture: How It All Fits Together

Here is the full integration architecture showing how Qualixar OS sits between Claude Code and the execution environments:

                    +----------------------------------+
                    |       Claude Code Session         |
                    |  +---------+  +-------------+    |
                    |  | Lead    |  | Agent Teams  |    |
                    |  | Agent   |  | (Teammates)  |    |
                    |  +----+----+  +------+------+    |
                    +-------|--------------|-----------+
                            |              |
                     Subagent Defs    Task Dispatch
                            |              |
                    +-------v--------------v-----------+
                    |     Qualixar OS Orchestrator      |
                    |  +--------+ +--------+ +------+  |
                    |  | Router | | Forge  | |Judge |  |
                    |  +---+----+ +--------+ +------+  |
                    +------|--------------------------+
                           |
              +------------+------------+
              v                         v
    +-------------------+     +----------------------+
    |  LOCAL AGENTS      |     |  CLAUDE MANAGED       |
    |  (10+ providers)   |     |  AGENTS (Cloud)       |
    |  - Ollama          |     |  - Sandboxed          |
    |  - GPT-4           |     |  - Checkpointed       |
    |  - Gemini          |     |  - Session-persistent  |
    |  - Claude local    |     |  - $0.08/session-hr   |
    |  Cost: $0 runtime  |     |                        |
    +-------------------+     +----------------------+

The Claude Code session at the top discovers Qualixar OS agents through the .claude/agents/ definitions. The orchestrator in the middle handles routing, team design (Forge), and quality gating (Judge). At the bottom, tasks fan out to either local execution (10+ model providers, zero runtime cost) or Claude Managed Agents (sandboxed cloud execution at $0.08 per session-hour in public beta).

The key architectural property: the orchestrator treats local and managed agents identically. Both receive tasks through the same interface. Both return normalized results. Both report costs. The dashboard shows them side by side. The only difference is where computation happens -- and that decision is made by the routing rules, not by the developer at implementation time.

The Combined Value

The integration is not a feature comparison. It is a capability unlock. Here is what the combination enables that neither system has alone.

Without integration: You audit a codebase with Claude Agent Teams. All agents run Claude. PII in the code goes to Anthropic's cloud. There are no cost controls -- you discover the bill after the fact. There is no quality gate between a teammate completing work and that work being accepted. If you want a different model for a subtask (say, a fast local model for regex-heavy scanning), you cannot mix providers.

With integration: Same audit. The PII-handling tasks route to a local Ollama model automatically -- your sensitive data never leaves your machine. Complex reasoning tasks go to Claude Managed Agents with sandboxing so untrusted code executes safely. The judge pipeline scores every output before acceptance, catching errors that would otherwise slip through. Total cost is tracked in real time on the dashboard, with automatic fallback to local models when the budget threshold is hit. One orchestrator, both worlds.

Without integration: You want to run a debate topology where two agents argue about an architecture decision. Claude Agent Teams gives you peer-to-peer teammates, but they all run the same model with the same biases. A real debate needs different models with different reasoning patterns.

With integration: The Forge Architect designs a debate team: Claude Sonnet argues for microservices (managed, cloud), GPT-4o argues for a monolith (local), and a local Llama judge evaluates both arguments against your project constraints. Three models, two environments, one topology. The diversity of reasoning is the point.

Without integration: Your CI pipeline needs 50 agent runs per day for test generation, code review, and documentation updates. At $0.08 per session-hour, the managed runtime cost adds up. For routine, non-sensitive tasks, you are paying for sandboxing you do not need.

With integration: Routine tasks (documentation, boilerplate generation, simple reviews) run locally at zero runtime cost. Only tasks that genuinely need sandboxing or session persistence dispatch to managed agents. The routing rules handle this automatically. Your monthly bill reflects the actual value of cloud execution, not a blanket tax on every agent invocation.

Getting Started Today

Five steps. The subagent definitions work now. The hybrid topology and managed agents adapter ship with Qualixar OS v2.x.

Step 1: Install Qualixar OS
npx qualixar-os
Step 2: Copy subagent definitions into your project
NOTE: The exact source path depends on how Qualixar OS distributes
agent definitions. Check the README after install for the correct path.
mkdir -p .claude/agents
cp -r .qualixar-os/agents/qos-*.md .claude/agents/
Step 3: Enable Claude Agent Teams
Config lives in ~/.claude.json (NOT ~/.claude/settings.json)
Add teammateMode to your existing config, or create the file:
echo '{ "teammateMode": "auto" }' >> ~/.claude.json
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Step 4: Start Claude Code — the agents appear as available teammates
claude
Step 5: Ask the team lead to use the Forge Architect
"Design a team for: audit this codebase for security vulnerabilities"

After step 4, Claude Code discovers the Qualixar OS agent definitions in .claude/agents/ and offers them as teammate options. The Forge Architect designs the team. The Quality Judge gates the output. When the hybrid topology ships, tasks will route between your machine and Claude's cloud automatically.

Here is what the dashboard will look like when hybrid execution is running:

> Expected dashboard output -- illustrative format for the hybrid topology feature.

Qualixar OS Dashboard — Hybrid Execution (expected output)
------------------------------------------------------------
Team: security-audit-team
Topology: hybrid (local + managed)
Status: RUNNING
Agent              Environment   Model              Status    Cost
---------------------------------------------------------------------
code-scanner       MANAGED       claude-sonnet-4    RUNNING   $0.12
report-writer      LOCAL         gpt-4o             DONE      $0.03
pii-detector       LOCAL         ollama/llama-3.3   DONE      $0.00
                                                    ---------
                                           Total:   $0.15 / $5.00

Every agent, its execution environment, model, status, and cost -- regardless of whether it runs locally or in Claude's cloud. This is the operational visibility layer that neither Claude Agent Teams nor Managed Agents provides on its own. The dashboard runs at localhost:3333 and updates in real time.

What We Use Claude For Every Day

This is not a theoretical integration. We use Claude to build Qualixar OS. This blog post was written with Claude. Our test suites run through Claude Code. Our architecture reviews happen in Claude Code sessions with agent teams.

We use Claude every day. This integration makes both tools better.

That is the core point. Qualixar OS is not an alternative to Claude. It is an extension. Claude provides the best reasoning models on the market. Qualixar OS provides the orchestration layer that makes those models work alongside other models, with routing intelligence, quality gating, cost tracking, and operational visibility. Managed Agents provides cloud sandboxing for tasks that need it. The three layers compose naturally because they solve different problems at different levels of the stack.

We built the subagent definitions because we needed them. We designed the hybrid topology because we hit the limitations of single-environment execution in our own workflows. We are building the managed agents adapter because Claude's cloud runtime is genuinely useful for sandboxed execution, and pretending otherwise would be dishonest.

What Comes Next

The subagent definitions are available now. The hybrid topology and managed agents adapter are in active development and ship with Qualixar OS v2.x.

If you want to understand the architecture in depth, read the Qualixar OS paper on arXiv (2604.06392). It covers the 12 execution topologies, the universal command protocol, the bootstrap architecture, and the design decisions that make model-agnostic orchestration possible.

If you want to see the product, visit Qualixar OS on qualixar.com.

If you want to follow the development, star the repo on GitHub.

If you want to understand how the agent infrastructure market is shaping up -- why Anthropic, Google, OpenAI, and Salesforce are all building agent runtimes, and what it means for developers -- read the agent OS thesis that started this conversation.

The future of agent execution is not one runtime. It is hybrid -- local and cloud, open and managed, many models and many topologies, all orchestrated through a layer that treats them as equals. That is what we are building.