AstroDev

Overview

AstroDev is the interactive coding agent that ships with the ArchAgents CLI. You run it in a terminal, in the repo you're working on. It reads and edits local files, runs shell commands, and can open pull requests — the same loop you get from Claude Code, Codex, or Cursor, but as a single archagent command.

Two things make it fit ArchAgents:

1. It can embody a live agent. Pick an agent from your linked workspace. AstroDev loads that agent's identity, skills, and platform tools so the session behaves like that agent working in your checkout — not a generic chat with no product context.
2. It can run without an agent. Leave the agent unset and you still get a full local coding session against the working directory, using the models and permissions you configure.

Use AstroDev when you want a dedicated terminal session for coding work, when you want to debug or extend a platform agent against real files, or when you need a headless one-shot prompt in CI.

It is not a replacement for the CLI verbs that create, deploy, and inspect platform objects. Use archagent list, deploy, and friends for that. AstroDev is the coding loop; the CLI is the operator surface. See CLI and Use ArchAgents from your coding agent.

---

Prerequisites

1. Install the CLI and sign in (see Getting Started).
2. Connect the current directory if you want agent selection and project context:

cd my-project
archagent init
archagent auth status

Platform login is required for interactive sessions that list your agents and for the default model path (platform-routed models). Bring-your-own providers can be configured separately; see Models and providers.

---

Start a session

From any directory:

archagent astrodev

That opens the full-screen TUI. On first paint you see the brand header, then session metadata (agent, session id, branch, working directory). After your first message the header collapses to a compact status bar so the transcript has room.

Seed an agent

Pass an agent id, lookup key, or name fragment so the selector starts focused:

archagent astrodev support-agent
archagent astrodev --agent agi_…

Inside a session you can switch agents with /agent (optional query to filter the list).

Resume a previous session

When you exit, the CLI prints the session id and a resume command:

archagent astrodev --resume <session-id>

From inside AstroDev, /resume picks a saved session or takes a matching id. Sessions and user-scope configuration live under ~/.astrodev on your machine.

One-shot headless run

For scripts and CI, skip the TUI:

archagent astrodev --print "Summarize the uncommitted diff" --output-format text
archagent astrodev --print "List failing tests" --output-format json --max-turns 8
archagent astrodev --print "…" --agent support-agent --model <model-id>

Headless runs require an existing CLI login. They never open an interactive login flow. Use --agent for an exact agent id or lookup key (no fuzzy matching). Without --agent, the run is a standalone session with no platform agent attached.

---

The session chrome

Region	What it shows
Header	Agent, full session id, git branch, working directory (compact after the first user message)
Transcript	Messages, tool cards, plan panel, and status rows
Prompt	Where you type; slash commands start with /
Footer	Active model (provider · model), permission mode chip, key hints

Keyboard

Key	Action
Enter	Send (or queue while a turn is running)
Shift+Enter / Option+Enter	Newline in the prompt
Shift+Tab	Cycle permission mode (includes plan)
Esc	Stop the in-flight turn — does not exit
Ctrl+C	Quit the session

While a turn is running the footer switches to phase + queue hints (tab cycles delivery for the next message).

---

Permission modes

Permission mode is the baseline for how aggressively AstroDev acts without asking. Cycle with Shift+Tab, or set explicitly:

/mode
/mode default
/mode acceptEdits
/mode plan
/mode deny
/mode auto
/mode bypass

Mode	Behavior
default	Ask before unmatched tool use
acceptEdits (edits)	Auto-allow file edits and writes; still ask for other tools
plan	Read-only planning: reads allowed, file edits and writes denied until you approve a plan
deny	Deny unmatched tool use by default
auto	High autonomy — auto-approve actions (configured deny rules still apply); shown with a ⚠ chip
bypass	High autonomy — skip the permission engine entirely; ⚠ chip

Fresh sessions default to auto when that mode is allowed. High-autonomy modes are impossible to miss in the footer. Your last mode is remembered across sessions when it is still allowed.

---

Plan mode

Plan mode is for "think first, change second." Enter it with Shift+Tab until the chip shows plan, or:

/plan
/plan on
/mode plan

While plan mode is on:

• The session is read-only for file edits and writes.
• The agent explores the codebase and builds a plan (markdown body + ordered steps).
• A plan panel shows the full draft as it evolves — nothing is truncated for review.

When a plan is ready for your decision, AstroDev prompts you the same way it elicits other choices:

• Approve — leave plan mode, restore the permission mode you had before planning, and execute the approved plan.
• Request changes — stay in plan mode and revise.

You can also drive review from slash commands:

/approve     # accept pending plan and execute
/reject      # keep plan mode and revise
/step        # approve and run only the next pending step

The agent can enter plan mode itself via its plan tool when it needs a read-only design pass. Either way, you review the markdown before edits land.

Turn plan mode off when you want a normal coding loop again:

/plan off

---

Models and providers

The footer shows the active route as provider · model. Platform-routed models appear as astrodev · … so the product name is what you see day to day. Bring-your-own providers keep their own ids (openai · …, xai · …).

Inside the session

/model              # pick or filter models
/provider           # switch platform | openai | xai
/provider platform

Outside the session (CLI)

Manage BYO credentials without changing your default model:

archagent astrodev provider list
archagent astrodev provider status
archagent astrodev provider login openai
archagent astrodev provider login xai --api-key sk-…
archagent astrodev provider login openai --device-code   # SSH / headless OAuth

provider login stores credentials only. Select the model afterward with /model openai/… or /model xai/… in the TUI (or --model for headless).

---

Slash commands (essentials)

Type / at the prompt for autocomplete. /help lists everything registered in the current session (built-ins plus skills).

Command	Purpose
/help	List slash commands
/agent [query]	Switch platform agent
/model [query]	Select model
/provider [platform|openai|xai]	Select model provider
/mode […]	Show or set permission mode
/plan [on|off]	Toggle plan mode
/approve / /reject / /step	Plan review
/new	Fresh session with the current agent
/resume [id]	Resume a saved session
/clear	Clear the transcript view
/theme [light|dark|auto|toggle]	Color theme
/quit	Exit

Code review and shipping

Command	Purpose
/diff	Summary of uncommitted changes
/review	Read-only review of local changes
/code-review	Severity-ranked findings with file:line
/security-review	Auth, secrets, injection-focused review
/simplify	Flag over-engineering and dead code
/pr-context	Branch, files, PR metadata, CI
/pr-describe	Generate PR body (summary, risk, impact, testing)
/pr-create [--submit]	Preview a PR; --submit opens it
/pr-review <n|url|branch>	Review a remote PR
/ci	CI status and actionable failures

Parallel work

Command	Purpose
/worktree <task>	Isolated branch + worktree for a task
/worktrees	Status of worktrees
/worktree-agent …	Write-capable subagent in a worktree
/delegate [--bg] <subagent> <task>	Hand off work to a subagent
/subagents / /jobs / /work	Inspect concurrent work
/monitor <command>	Background process whose output becomes events

Skills attached to the selected platform agent appear as /skill:… (and related skill management under /skills).

---

How AstroDev relates to other surfaces

Surface	Role
AstroDev	Interactive (or headless) coding agent in the terminal; optional platform agent identity
CLI verbs (list, deploy, create, …)	Create and operate platform objects; source of truth for automation
Coding-agent plugins (Claude Code, Codex, Cursor)	Same platform operations from the chat where you already work — see coding agents
Embed	Step into one live agent's exact tools and skills inside Claude Code / Codex / Cursor — see Embed
ArchAgents Portal	Review agents, threads, activity, and org settings in the browser — see Portal

Pick the surface that matches the job: AstroDev for a focused coding session, embed when your coding agent should be a specific live agent for a while, CLI for scripted deploys and inspection.

---

Typical workflows

Local feature work

cd my-repo
archagent astrodev

Describe the change. Use /mode acceptEdits or stay in auto if you trust the loop. When the diff looks right: /review, then /pr-describe and /pr-create --submit.

Plan before touching the tree

/plan on

Ask for an approach on a risky migration or multi-service change. Read the full plan panel. Approve when the steps match what you want; reject and refine if not.

Debug as a platform agent

archagent astrodev support-agent

The session inherits that agent's identity and skills. Reproduce a customer-facing failure against the local config files, or draft a template change while staying in the agent's voice.

Scripted check in CI

archagent auth status   # non-interactive token already configured
archagent astrodev --print "Report whether the PR description matches the diff" \
  --output-format json --max-turns 6

---

Where to go next

1. CLI — install, auth, init, and day-to-day operator commands.
2. Use ArchAgents from your coding agent — Claude Code, Codex, and Cursor plugin setup.
3. Embed — run as a live agent inside those coding agents.
4. Agents — identity, tools, routines, and the model behind every agent you can select in AstroDev.
5. Skills — reusable packages that show up as slash commands when attached to an agent.