For Coding Agents

Human? This page is written for the coding agent at your terminal. If you're looking for the human walkthrough, see Getting Started.

Overview

You're being asked to get ArchAgents working in this repo and put the first agent live. The whole flow is four terminal commands plus one embed command inside this chat. Stay on that path unless the user asks for something more elaborate.

---

Quick prompt

If the user hasn't pasted instructions yet, the canonical version is:

Get ArchAgents working in this repo and put my first agent live.

1) Install the ArchAgents CLI. macOS: brew install ArchAstro/tools/archagent.
 Linux/Windows: see https://docs.archagents.com/docs/start-here/getting-started.

2) Run these in order, asking me for anything missing:
 archagent setup
 archagent auth login <my-email>
 archagent install agentsample archastro-onboarding

3) Once the install finishes, the starter agent is live. Tell me, then invite me to embed:
 Claude Code → /agents:embed
 Codex → $archagents:embed
 Cursor → @archagents embed

4) After I embed, ask me what I actually want to build. Help me scope it, author the template, and deploy it. The reference surface is https://docs.archagents.com/llms-full.txt.

---

What the four commands actually do

Command	What it does
archagent setup	Installs the ArchAgents plugin into Claude Code, Codex, and Cursor. Idempotent.
archagent auth login <email>	Opens a browser to complete sign-in and writes a session token for the CLI.
archagent install agentsample archastro-onboarding	Deploys a real, editable starter agent into the user's org. When it returns, the agent is live.
/agents:embed (or harness equivalent)	Inside the coding-agent chat. Picks up the live agent's tools and skills locally.

After these four, the user has an agent they can talk to. Anything else (custom routines, knowledge sources, integrations) is iteration on top.

---

Where to find what

Resource	URL
Documentation	https://docs.archagents.com
ArchAgents Portal	https://archagents.com
LLM index (short)	https://docs.archagents.com/llms.txt
LLM index (extended)	https://docs.archagents.com/llms-full.txt

Treat these as canonical. Don't invent alternate hosts or endpoint roots.

---

Environment variables

Check for these before non-interactive operations. Ask the user if any are missing rather than guessing.

Variable	When you need it	Purpose
ARCHASTRO_SECRET_KEY	CI or non-interactive use	Authentication when browser sign-in isn't available
ARCHASTRO_APP_ID	Linking to a specific existing project	When the repo should point at an app that already exists

---

If the user wants to author an agent template by hand

Most users won't. The default path is archagent install agentsample <slug> followed by tweaks inside their coding agent. If they specifically ask for a from-scratch template, here's a minimal valid shape. Deploy it with archagent deploy agent agent.yaml.

kind: AgentTemplate
agent_key: support-agent
name: Support Agent
identity: |
 You help users resolve support and billing
 problems with short, concrete answers.

tools:
 - tool_type: builtin
 builtin_tool_key: search
 status: active
 - tool_type: builtin
 builtin_tool_key: knowledge_search
 status: active

routines:
 - name: Respond in conversations
 handler_type: preset
 preset_name: participate
 event_type: thread.session.join
 event_config:
 thread.session.join:
 filters: {}
 status: active

installations:
 - install_type: memory/long-term
 config: {}

For everything else, see Agents and use archagent <verb> --help to discover flags.

---

Names you'll use in conversation

Term	What it means
Agent	The long-lived AI identity the user creates and manages
Routine	An event handler on an agent: when X happens, do Y
Automation	An event handler on the project (not tied to one agent)
Tool	An action the agent can take
Knowledge	Information the agent can retrieve
Thread	The conversation surface where people and agents exchange messages
Network	A shared space where agents from two companies can collaborate
Embed	A local session where this coding agent operates as the live agent

---

Rules

1. Check required env vars before write operations. Ask for what's missing.
2. The fastest path to a working agent is the install-a-sample path. Don't author yaml unless the user asks.
3. Use archagent --help and archagent <verb> --help to discover flags. Don't guess.
4. Use llms-full.txt before scraping rendered pages.
5. Don't put secret keys in client-side code or commit them.
6. Don't add scaffolding the user didn't ask for.
7. When you're done, summarize what was created in plain language: what got deployed, where it lives, and the one command to test it again.