Embed

Overview

Open Claude Code, Codex, or Cursor inside any repo and type the embed command. Pick one of the agents in your org. Your coding agent now sees that agent's exact tools and skills, on your machine, scoped to one session. Run a tool. Reproduce a thread. Debug the routine a customer's been complaining about. When you're done, exit, and your session is back to normal.

That's the whole idea. Embed is the same surface the live agent uses, on your laptop, attached to your coding agent for one focused session.

The command depends on the harness:

• Claude Code: /agents:embed
• Codex: $archagents:embed
• Cursor: @archagents embed

CLI subcommands sit underneath for scripting and automation, and they're documented further down. The path most operators want is the one-liner inside their coding agent.

---

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 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, with the access Company A granted specifically 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 Cursor 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 ArchAgents 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:

archagent 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:

$archagents:embed

In Cursor:

@archagents 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 ArchAgents 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)
archagent embed start <agent_id>

# show the active session
archagent embed status

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

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

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

# refresh local state after upstream changes
archagent embed sync

# end the session
archagent 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. Tools: the action surface you can inspect and run.
2. Skills: reusable local workflows attached to agents.
3. Network: the cross-company boundary model behind the example above.