Embed

Overview

Embed lets your coding agent — Claude Code, Codex, or OpenCode — operate from a live agent's exact local surface. The platform fetches that agent's manifest, writes local state for the session, and exposes the agent's tools and skills to your coding agent.

The result: when you're debugging a live agent's behavior, your local coding agent sees the same tools, the same skills, and the same approved surface the live agent does. No guessing from prompts, no copying snippets out of stale screenshots.

The flow is built around your coding agent on purpose. The CLI subcommands underneath exist for scripting and automation, and they're documented here for completeness. The path most operators want is /agents:embed in Claude Code or $embed in Codex.

---

A concrete example

Company B is integrating with Company A's platform. Company A owns the infrastructure and exposes a Platform Support Agent into a shared rollout thread. Company B's engineer already has access to Company A's support app for this rollout and needs to debug why the acme-billing-webhooks integration keeps failing during webhook validation.

This is a privileged workflow, not the default path for everyday collaboration. The flow:

1. Join the shared rollout thread in Agent Network.
2. From Claude Code or Codex, run the embed command to step into Company A's support agent.
3. List the agent's tools and skills.
4. Run the relevant troubleshooting tool through the embed surface.
5. Sync if Company A revises the upstream agent during the session.

The engineer is now operating from the support agent's exact attached surface — after Company A deliberately granted that access for the rollout.

---

What embed is — and what it isn't

Embed is precise.

It does:

• pull the selected agent's current local operating surface onto your machine
• show which tools and skills are attached right now
• let you run those tools through the same surface the live agent uses
• install the agent's linked skills into Claude Code, Codex, or OpenCode for local work

It does not:

• promote one agent into a blanket platform administrator
• bypass company boundaries or shared-thread membership
• expose private knowledge the agent wasn't already configured to reach
• replace the normal product workflow for shared teams, threads, or approvals

The platform's security boundary is explicit:

• Embed changes your local coding-agent context to one selected agent.
• You can only embed an agent inside an ArchAstro app you can already access.
• The local plugin reaches the agent through private developer endpoints scoped to that app.
• Tool execution still goes through the agent's normal attached platform surface.
• Company boundaries, shared-thread membership, and any approvals in the live setup continue to apply.

That precision is the value — embed gives you the live agent's exact surface, not blanket new authority.

Treat it as privileged operator access

Before rolling embed out broadly, the company that owns the agent decides:

• who is allowed to embed agents
• which apps and agents those people can embed
• how that authorization is reviewed
• how sessions are recorded or reviewed during rollouts and incidents

The safe default is narrow: grant embed access to the people who need it for a clear business purpose, and review it the way you'd review any other privileged access. For developer-side "login as user" flows, the platform mints a user JWT with an impersonated_by claim and logs the event at warning level — the audit trail is built in.

---

The path most operators use: from your coding agent

Run setup once from your terminal so the local plugin is installed:

archastro setup

Restart Claude Code or Codex after setup so the plugin loads. From here on, every embed step happens inside your coding agent.

Start

In Claude Code:

/agents:embed

In Codex:

$embed

If the app exposes a single agent, the command picks it. If several are available, the command walks you through an interactive selection. To target a different ArchAstro app, update the CLI app context first from your terminal, then start an embed session again from your coding agent.

Inspect

Once an embed session is active, ask the two most useful questions first:

1. What can this agent do?
2. What reusable guidance or commands does it already carry?

The same embed entry point lists the agent's tools and skills. Most "missing capability" reports turn out to be agents that already have the right tool or skill attached.

Run a tool

Ask your coding agent to use the embedded agent's tools for the task at hand. That's the fastest way to confirm whether the live agent has the operational surface a real troubleshooting task needs. In the Company A / Company B example, this is where the engineer confirms that the support agent's search capability actually reaches the approved troubleshooting corpus before escalating.

Install a linked skill

Linked skills are reusable local workflows attached to the agent — runbooks, custom commands, structured prompts. Install only the skill package you need, after listing the available ones first.

This is where embed becomes especially valuable: the agent's operational knowledge becomes available to the local coding workflow, instead of staying trapped in the remote platform definition. The cross-company guarantee holds — installing a linked skill doesn't flatten company boundaries or expose a whole workspace.

Sync after upstream changes

If Company A updates the support agent's tool set, a linked skill changes, or the manifest is revised after your local session started, refresh from the same embed entry point. Local state stays honest with the live definition.

Stop cleanly

When the session is done, stop the embed session from the same place. The platform removes local embed state from your machine, and your coding agent returns to its normal context.

---

CLI reference for scripting

The CLI subcommands underneath the plugin exist for automation, CI hooks, and the rare case where a coding agent isn't part of the loop. They write to the same local state the plugin manages, so an embed session started from the CLI works the same inside Claude Code or Codex.

# start a session for a specific agent (or run with no argument to pick interactively)
archastro embed start <agent_id>

# show the active session
archastro embed status

# list the active agent's tools and skills
archastro embed list tools
archastro embed list skills

# install a linked skill into the local coding harness
archastro embed install skill <skill_id>

# execute one of the active agent's tools by ID, lookup key, or builtin tool key
archastro embed run tool <tool>

# refresh local state after upstream changes
archastro embed sync

# end the session
archastro embed stop

Use these when you're scripting against the loop. The interactive operator path stays inside your coding agent.

---

Common use cases

• Reproduce a live agent's behavior locally.
• Inspect the exact tools and skills an agent has.
• Help your coding agent work from the same attached surface as the live agent.
• Debug cross-company rollout and support flows without flattening company boundaries.

---

Best practices

1. Embed only the agent you actually need.
2. Inspect attached tools and skills before requesting more access.
3. Tie cross-company embed sessions to one shared thread or business purpose.
4. Stop the embed session when the local session is done — the manifest, identity files, and skill installations come back off your machine cleanly.

---

Where to go next

1. Read Tools for the action surface you can inspect and run.
2. Read Skills for reusable local workflows attached to agents.
3. Read Agent Network for the cross-company boundary model behind the example above.