Astro Code is a terminal AI coding agent CLI. It runs inside your project, talks to chosen LLM provider, edits files, runs tools, manages agents, and gives interactive slash-command control from terminal UI.

• Multi-provider setup: Google AI Studio, Kimi, OpenAI, OpenRouter, DeepSeek, Ollama, LM Studio, custom OpenAI-compatible APIs
• Interactive provider/model picker
• /model live model switch from configured provider list
• Agent creation and agent model inheritance
• Terminal UI built with Ink/React
• Tool system for file edits, shell commands, search, agents, plugins, tasks, MCP, browser tools
• Local config in ~/.agent-cli/provider.json and ~/.astro.json
• Buildable single-file runtime in dist/

• Node.js 20+
• npm
• API key for cloud providers
• Ollama or LM Studio running locally for local providers

npm install
npm start

First run opens setup:

1. Select provider with arrow keys.
2. Enter API key when provider needs one.
3. Select model.
4. Start chatting in terminal.

Reset setup:

rm -f ~/.agent-cli/provider.json ~/.astro.json
npm start

npm run bootstrap       # prepare generated files
npm run full-bootstrap  # install/build bootstrap flow
npm run check:source    # validate local imports and runtime imports
npm run build           # bundle dist/astro-code.js and dist/agent.js
npm start               # run Astro Code CLI
npm run agent           # run agent entry

Inside Astro Code:

/model       show/change current provider model
/statusline  show provider/model in status line
/help        command help
/init        create project guidance
/config      edit settings
/agents      manage agents
/permissions manage tool permissions
/mcp         manage MCP servers
/theme       change terminal theme

bin/                    executable shims
dist/                   bundled runtime output
scripts/                build, bootstrap, source checks, run scripts
src/                    main TypeScript source
stubs/                  compatibility stubs for native/optional modules
vendor/                 vendored @agent-ai SDK packages

src/main.tsx            CLI boot, args, startup config
src/entrypoints/        executable entrypoints and SDK entry
src/screens/REPL.tsx    main interactive loop and prompt handling
src/query.ts            agent query loop, tool-use flow, stop hooks
src/QueryEngine.ts      non-interactive/headless query engine
src/Tool.ts             tool contract
src/Task.ts             task contract

src/utils/providerSetup.ts

Owns first-run provider wizard, saved provider config, active model env, static provider model lists, /model model source.

Config files:

~/.agent-cli/provider.json
~/.astro.json

Default local URLs:

Ollama    http://localhost:11434
LM Studio http://localhost:1234/v1

src/components/
src/components/PromptInput/
src/components/messages/
src/components/LogoV2/
src/ink/

Ink/React render tree. PromptInput handles typing, paste, slash command dispatch, loading state, and prompt footer. messages render assistant, user, system, API error, and tool messages.

src/commands/

Slash commands live here. Each command has index.ts plus implementation file/folder. /model lives in:

src/commands/model/model.tsx

src/tools/

Tools implement agent actions: file read/write, shell, search, agent spawning, browser, MCP, workflow, review, sleep, monitor, and more. Tool permissions flow through src/components/permissions/ and src/utils/permissions/.

src/components/agents/
src/tools/AgentTool/
src/utils/model/agent.ts

Agent UI, creation wizard, agent model selector, agent display, and tool runtime. Agents inherit current provider model unless user selects another provider-listed model.

src/services/api/
src/utils/model/
vendor/@agent-ai/

API client creation, retry behavior, streaming, error formatting, model parsing, model display, and provider-specific SDK compatibility. Provider model shown to user comes from static CLI lists, not live /models discovery.

src/bootstrap/state.ts
src/state/
src/context.ts

Global app/session state: model, cost, tokens, tasks, streaming state, permissions, durations, memory, notifications.

src/tasks/
src/jobs/
src/daemon/
src/server/
src/bridge/

Foreground/background tasks, local and remote sessions, bridge connections, task queues, server helpers, transport clients.

src/plugins/
src/skills/
src/commands/plugin/
src/components/mcp/
src/services/skillSearch/

Plugin marketplace, installed plugins, skill loading, MCP server UI, MCP tools, and skill discovery.

src/memdir/
src/services/compact/
src/services/contextCollapse/
src/services/sessionTranscript/
src/utils/context.ts

Project memory, session transcript, context compaction, microcompaction, memory discovery, and context budget handling.

User input
  -> PromptInput
  -> processSlashCommand or REPL onQuery
  -> query.ts
  -> services/api/astro.ts
  -> provider API stream
  -> handleMessageFromStream
  -> Messages render
  -> tools/tasks mutate files or run commands

Slash command flow:

/model
  -> src/commands/model/model.tsx
  -> src/utils/providerSetup.ts
  -> setProviderModel()
  -> AppState mainLoopModel update

Tool-use flow:

model requests tool
  -> query loop validates permission
  -> tool runs
  -> result appended
  -> model continues or stops

dist/astro-code.js   main CLI bundle
dist/agent.js        agent executable bundle
bin/agent.js         package bin shim

Build:

npm run build

Run built CLI:

node dist/astro-code.js

npm install
npm run check:source
npm run build
npm start

Before push:

npm run check:source
npm run build
git status

Never commit API keys, local config, node_modules, or generated local state. .gitignore excludes:

node_modules/
.astro/
.agent/
.bootstrap-report.json

Rotate any token pasted into terminal logs or chat.