AstroDev

Overview

AstroDev is the coding agent that ships with the ArchAstro 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 archastro command.

Two things make it fit ArchAstro:

1. It can embed a live agent. Pick an agent from your linked app. AstroDev loads that agent's identity, default model, linked skills, and platform tools into the local coding loop, while keeping its file, shell, git, review, and delegation tools.
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 archastro list, deploy, and friends for that. AstroDev is the coding loop; the CLI is the operator surface. See CLI and Use ArchAstro from your coding agent.

Key features

Feature	What it gives you
Embedded agents	Work as one live platform agent with its identity, default model, linked skills, and scoped platform tools
Local coding loop	Read, search, edit, run shell and git commands, inspect diffs, review changes, and prepare pull requests
Reviewable autonomy	Permission modes, a read-only plan mode, tool cards, and explicit plan approval
Resumable sessions	Continue local conversation and tool history from ~/.astrodev
Parallel work	Delegate to subagents, isolate work in worktrees, and monitor background commands
Dynamic workflows	Let the model generate a bounded JavaScript program that coordinates independent or staged agents
Model choice	Use platform-routed models or configured OpenAI and xAI providers
Headless mode	Run the same agent loop non-interactively with -p / --print for scripts and CI

---

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
archastro init
archastro auth status

Running AstroDev always requires a platform CLI login, including standalone sessions and sessions that use a bring-your-own model. Provider login only supplies model credentials; it does not replace platform authentication. See Models and providers.

---

Run with an embedded agent

Selecting an agent embeds that live platform agent in the AstroDev session. AstroDev wires the agent in automatically; you do not need to run embed start, embed sync, or embed stop.

Agent resource	How AstroDev uses it
Identity	Adds the agent's persona and identity instructions to the coding session
Default model	Uses the agent's configured model unless you choose another model or pass --model
Platform tools	Lets the agent discover its deployed tools and call them through a permission-gated tool facade, under your existing platform access
Linked skills	Lists the agent's skills and loads their instructions and supporting files only when needed
Local tools	Keeps AstroDev's local file, shell, git, review, plan, and delegation capabilities; the embedded identity does not replace them

In the interactive TUI, linked skills also appear as /skill:<slug> commands. Choose None to run standalone; AstroDev then omits the platform agent's identity, tools, and skills but keeps the complete local coding surface.

An embedded-agent AstroDev session is still a local AstroDev coding session. It does not attach to an existing platform thread or run the agent's routines, and its resumable conversation history stays under ~/.astrodev. For persistent impersonation inside Claude Code, Codex, or Cursor, use Embed instead.

---

Start a session

From any directory:

archastro astrodev

That opens AstroDev's full-screen, alternate-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. Use Page Up, Page Down, or the mouse wheel to move through the session; AstroDev restores your normal shell screen when you exit.

For scripts, pipes, and other non-interactive use, run headless mode with --print (or -p) instead of launching the TUI.

Seed an agent

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

archastro astrodev support-agent
archastro 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:

archastro 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.

Headless mode

For scripts and CI, pass a prompt with -p or --print. That flag is the headless-mode switch; there is no separate --headless flag.

archastro astrodev -p "Summarize the uncommitted diff"
archastro astrodev -p "List failing tests" --output-format json --max-turns 8
archastro astrodev -p "Investigate this support issue" \
  --agent support-agent --model <model-id> --output-format json
archastro astrodev -p "Continue the investigation" --resume <session-id>

Headless runs require an existing CLI login and never open an interactive login flow. Use --agent with an exact agent id or lookup key; display names and fuzzy matches are not accepted, and the interactive positional agent argument is ignored. Without --agent, a fresh run is standalone with no platform agent attached. --resume continues the saved session with its original agent and history.

Text output is the default and prints only the final assistant response. --output-format json prints an envelope with type, subtype, is_error, session_id, and result; failed runs exit nonzero. --max-turns bounds the agent loop.

Headless embedded-agent runs use the selected agent's identity and linked skills, and they can discover its platform tools. There is no interactive approval panel: local tools run non-interactively, but deployed platform tools cannot execute in headless mode because every platform tool call fails closed. The commit and push guard remains active.

---

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, the review prompt lets you approve and execute the whole plan, approve only the next pending step, request changes with notes, or close the review pane. Approving the whole plan leaves plan mode and restores the permission mode you had before planning; requesting changes keeps the session in plan mode.

You can also drive review from the /plan command:

/plan approve          # accept the pending plan and execute it
/plan step             # approve and run only the next pending step
/plan reject [notes]   # stay in plan mode and revise
/plan close            # close the review pane without approving
/plan help             # show plan-mode usage

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:

archastro astrodev provider list
archastro astrodev provider status
archastro astrodev provider login openai
archastro astrodev provider login xai --api-key sk-…
archastro 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|approve|step|reject|close|help]	Plan mode and plan review
/new	Fresh session with the current agent
/resume [id]	Resume a saved session
/clear	Reset conversation/model context in the same session while keeping the selected agent and project instructions
/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	Compatibility views for subagents and shell jobs
/work [action] [id]	List, inspect, stop, pause, resume, or rerun background 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).

Unified background-work control

/work is the common control surface for workflows (wf-*), subagents (sa-*), shell jobs (bg_*), monitors (mon-*), and long-running goals or loops (gl_*, rl_*, lp_*). Every runtime plugs into the same work-provider contract for listing, status, output, control, and session cleanup. The list shows each item's safe controls; unsupported actions fail explicitly instead of pretending that unlike runtimes have identical suspension semantics.

/work                         # list every background item and its controls
/work status <id>             # state, parent, phase, and available controls
/work output <id>             # captured output or terminal summary
/work stop <id|all>           # cancel one item or all live work
/work pause <id>              # pause at that runtime's safe boundary
/work resume <id>             # continue a paused item
/work rerun <id>              # start a new run when the item supports it

Pause is capability-safe: shell jobs and monitors use operating-system process suspension where supported, workflows let already-running agents finish and hold new agent dispatches, and goal/ralph/loop jobs stop chaining after the current turn. Stopping a long-running goal or loop also prevents another turn but does not pretend it can rewind a model call already in flight. A one-shot subagent cannot be safely suspended mid-model-call, so it supports status, output, and stop but not pause/resume. Status uses the same normalized states across providers (running, paused, waiting, blocked, succeeded, failed, or stopped) and includes a runtime's more specific native status when useful. The model has the same split surface through read-only work_status and permission-gated work_control tools.

The inventory is unified, but persistence remains capability-specific. Shell jobs, monitors, subagents, and workflow processes are stopped and drained when a session is cleared, replaced, resumed away from, or exited; they are not checkpointed. Long-running goal/ralph/loop metadata is deleted by /clear, remains attached to the old session across /new or /resume, and can be restored when that session is resumed. Exiting disposes its in-memory timer without deleting the saved metadata.

output appears only for work kinds that retain output or a terminal summary. Long-running goals and loops expose their objective and latest lifecycle update through status instead of claiming a separate output stream.

---

Dynamic workflows

AstroDev can decide to use its model-callable workflow tool when a task benefits from many independent agents or a repeatable sequence of agent stages. You can also ask directly: “Use a workflow to investigate these services in parallel.” This is a tool the model calls during a turn, not a slash command you invoke yourself.

The model supplies a self-contained JavaScript program. Every program begins with literal metadata and returns a JSON-serializable result:

export const meta = {
  name: "review-services",
  description: "Review several services and combine the findings",
  phases: [
    { title: "Review", detail: "Inspect each service in parallel" },
    { title: "Summarize" },
  ],
};

phase("Review");
const findings = await parallel([
  () => agent("Review the API service", { label: "api", phase: "Review" }),
  () => agent("Review the web service", { label: "web", phase: "Review" }),
]);

phase("Summarize");
return agent(
  `Combine these findings into one prioritized report: ${JSON.stringify(findings)}`,
  { label: "summary", phase: "Summarize" },
);

The generated program has a small orchestration API:

Global	Purpose
args	The JSON value passed to the workflow
agent(prompt, options)	Run an isolated AstroDev agent and return its result
parallel([() => …])	Start independent tasks together and preserve their result order
pipeline(items, ...stages)	Run each item through a sequence of stages; items run concurrently
phase(title)	Report a phase declared in meta.phases
log(value)	Add a bounded diagnostic entry to the saved run

agent accepts label, phase, model, and schema. The schema option requests structured JSON from that agent. Claude Code-specific options such as isolation, agentType, and effort are not supported and fail explicitly instead of being ignored. Phase declarations must use objects such as { title: "Review", detail: "optional" }, not bare strings.

Background runs and results

In an interactive tracked session, a workflow runs in the background by default so the main conversation remains usable. AstroDev immediately returns a wf-* work id, exposes its phase and child agents through /work, and injects a typed work-completion event when the workflow settles. /work pause cooperatively holds new agent dispatches while already-running agents finish; /work resume releases them. The model can request a foreground run when the current turn must consume its result. Exiting, clearing, replacing, or resuming away from the session stops and drains tracked workflow work rather than leaving child processes behind.

The workflow card shows the generated JavaScript with line numbers. Expand it to inspect the complete script; successful foreground runs show status and timing without replacing the source with a deeply expanded result tree. Inline scripts and JSON run snapshots are saved inside the session's workflows directory under ~/.astrodev. /work status <wf-id> reports the saved script path. Edit that file with the normal file tools, then /work rerun <wf-id> starts a fresh execution from its current contents; rerun does not resume a JavaScript continuation. Workflow processes are not restored after AstroDev exits.

Execution boundary

Generated JavaScript does not run inside the AstroDev process. AstroDev parses it first, rejects imports and dangerous runtime identifiers, then starts a memory-limited Node child process with filesystem and network permissions disabled. The child receives only the workflow API above. Agent requests cross a bounded JSON-lines IPC bridge back to the AstroDev harness, where the normal permission, read-only, model, and commit guards still apply.

Workflow runs are bounded by time, script size, retained logs, IPC message size, concurrency, and agent count. They cannot use process, require, dynamic imports, fetch, filesystem APIs, environment variables, nested workflows, runtime code generation, or nondeterministic Math.random().

---

How AstroDev relates to other surfaces

Surface	Role
AstroDev	Interactive or headless local coding agent; can embed a platform agent's identity, tools, and skills for the session
CLI verbs (list, deploy, create, …)	Create and operate platform objects; source of truth for automation
Astrorun	Local processing and review queue that can use AstroDev as a headless processor — see Astrorun
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
Developer Portal	Review agents, threads, activity, and org settings in the browser — see Portal

Pick the surface that matches the job: AstroDev for a focused local coding session, persistent Embed when an existing coding agent should be a specific live agent for a while, and CLI verbs for scripted deploys and inspection.

---

Typical workflows

Local feature work

cd my-repo
archastro 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

archastro astrodev support-agent

The session inherits that agent's identity, default model, linked skills, and scoped platform-tool surface while retaining AstroDev's local coding tools. Reproduce a customer-facing failure against local config files, or draft a template change while staying in the agent's voice.

Scripted check in CI

archastro auth status   # non-interactive token already configured
archastro 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. Astrorun — turn agent work into a local processing queue with persisted review records.
3. Use ArchAstro from your coding agent — Claude Code, Codex, and Cursor plugin setup.
4. Embed — run as a live agent inside those coding agents.
5. Agents — identity, tools, routines, and the model behind every agent you can select in AstroDev.
6. Skills — reusable packages that show up as slash commands when attached to an agent.