Use ArchAstro from your coding agent

Overview

The fastest way to use ArchAstro is through the coding agent you already work in — Claude Code, Codex, or Gemini CLI. One setup command installs a ArchAstro plugin into all three. From that moment on, your coding agent can deploy agents, inspect runs, manage secrets, and step into a live agent's context the same way it edits code in your repo.

This is not a shortcut path or a separate API surface. It's the same CLI, the same auth, the same project context — driven from the chat where you already think about your work.

Why it's the recommended path:

Your context stays in one place. The same coding agent that knows your codebase also knows how your live agent is configured. No copy-pasting IDs between terminals and dashboards.
The platform's privacy boundaries hold. The plugin uses your existing ArchAstro session and reaches the platform through the same scoped developer endpoints the CLI uses. Org and team boundaries, secret-scope rules, and approval flows continue to apply unchanged.
The CLI is still the source of truth. When you want to script something into CI or share a one-shot command with a teammate, you drop down to the CLI. The plugin is the interactive face of the same surface.

One-time setup

Install the CLI for your platform, then run:

archastro setup

That one command installs the ArchAstro plugin into Claude Code, Codex, and OpenCode in the same pass. Restart the coding agent once afterwards so the plugin loads.

Common flags:

--scope project — install for the current repo only (default is per-user).
--claude-only or --codex-only — scope to a single harness.
--dry-run — preview the changes before they're written.

After setup, your coding agent runs against the same ArchAstro project the CLI is logged into. No second authentication step.

What your coding agent can do

Anything the CLI can do, your coding agent can do — by talking to it the way you already do. Some examples worth knowing about up front:

Deploy an agent from a spec. You describe the agent in plain language. The coding agent writes an agent.yaml, validates it, and deploys.

List and inspect what's already there. Ask "what agents do we have?" or "what tools is the support agent attached to?" — the coding agent runs the right list and describe commands and summarizes the results.

Manage per-agent secrets. Ask the coding agent to add a Stripe key to the support agent. It runs create agentenvvar with the right scoping and confirms back. Values stay write-only — the platform never returns them in cleartext, no matter who's asking. See Secrets.

Step into a live agent's context. Type /agents:impersonate in Claude Code (or $impersonate in Codex) and your coding agent picks up the live agent's exact tools and skills — useful for reproducing reported behavior or debugging a cross-company rollout. See Impersonation.

Run a tool through the impersonated surface. Once you're impersonating, ask your coding agent to call one of that agent's tools directly. The call goes through the platform's normal tool surface — every guardrail the live agent has, your coding agent inherits.

A concrete example

You've inherited a support automation project. You want to know what it actually does before changing anything. Open Claude Code (or Codex) inside the repo and ask:

This repo has an ArchAstro project linked. Use the ArchAstro plugin to:
1. List the agents in this project.
2. For each agent, summarize its identity, attached routines, and tools.
3. Pick the agent that looks like the main support automation. Tell me what
   knowledge sources it has and whether it has any per-agent secrets.
4. Run a test prompt against that agent in a sandbox so we can see how it replies.

Your coding agent walks the list, describes each agent, picks the right one, summarizes its surface, and uses a sandbox to test — all in one session. The same loop in a dashboard would be a half-dozen page navigations.

When to use the CLI directly

The plugin is the interactive face. For everything that should be repeatable, scriptable, or shared, use the CLI:

CI/CD — deploy agent.yaml from your pipeline, gate on validate, roll forward only after a successful sandbox test.
One-shot commands you'll paste in chat — short, exact CLI invocations are easier to share than free-text instructions.
Bulk or scheduled work — automations, batch updates, scheduled exports.

The CLI is the source of truth. The plugin makes the source of truth feel native to your existing workflow.

Privacy and trust

The plugin doesn't add a new authorization layer. Everything it does goes through the same scoped developer endpoints the CLI uses, under your existing ArchAstro session.

What that means in practice:

Your coding agent only sees what you can see. Org, team, sandbox, and agent-ownership boundaries all carry through.
Secrets stay write-only. Listing them returns masked previews; cleartext is reserved for the agent at runtime, behind explicit ownership checks.
Impersonation is precise — it picks up one agent's local surface, not a blanket admin context. Company boundaries, shared-thread membership, and approval flows continue to apply.
Privileged actions (impersonation, login-as-user) generate audit events with an impersonated_by claim and warning-level logs by design.

You stay in control of your project. The coding agent makes that control faster to use.

Where to go next

Getting Started — the full zero-to-one path, with the coding-agent flow as Step 2.
For Coding Agents — machine-friendly setup rules to paste into the coding agent itself.
Impersonation — step into a live agent's context from inside Claude Code or Codex.
Secrets — manage per-agent credentials safely from the same workflow.