Astra — Terminal AI Coding Agent

AI coding agents face a fundamental tension: power versus safety. Astra resolves this with a permission system (allow/ask/deny by pattern), approval gates for destructive operations, and scope isolation for multi-agent runs. The multi-provider failover means if one LLM hits rate limits, Astra seamlessly switches to the next provider — up to 3 switches per turn. The boss orchestrator mode delegates to specialized workers (explore, implement, shell, plan) while the multi-agent mode runs agents in parallel with disjoint file-scope claims.

The system uses a tool-use architecture where the LLM orchestrates a set of 23 registered tools. Each tool has a schema definition, permission level, and execution handler. The agent loop: user input → LLM reasoning → tool selection → permission check → execution → result → next iteration. Multi-agent mode uses file-scope claims — each agent locks specific file paths to prevent concurrent write conflicts. The messaging gateways (Telegram, Discord, WhatsApp) are thin adapters that map platform messages to the agent's standard input format and render tool approval buttons as platform-native interactive elements.

The agent maintains conversation history with context compaction when approaching model limits. Tool results are stored with correlation IDs linking them to the triggering LLM decision. Permission presets are defined per-pattern (bash: allow 'npm *', ask 'rm *', deny 'sudo *'). Project rules auto-discover AGENTS.md/CLAUDE.md files injected into system prompts. Skills are installable modules from the Vercel Agent Skills ecosystem.

The hardest challenge was multi-agent file-scope coordination. When multiple agents work on the same codebase, concurrent writes can corrupt files. Solved with a claim system: each agent declares which files it needs before starting work, and the orchestrator rejects overlapping claims. Context compaction required careful history summarization to preserve critical decisions while reducing token count. The messaging gateways needed platform-specific UX — Telegram's inline buttons for approve/deny, Discord's component interactions, WhatsApp's reply-based flow.

The agent is single-process but handles load through tool parallelism (multiple independent tool calls in one turn). Multi-agent mode scales horizontally by running separate Node.js processes with the orchestrator as coordinator. Docker deployment provides isolation per agent run. Conversation compaction keeps memory usage bounded regardless of session length.

Tool execution failures are reported to the LLM for retry with modified approach. Provider failover handles rate limits and API errors transparently. Browser automation pauses for CAPTCHAs and OTPs. Context overflow triggers compaction rather than truncation. Conversation history is persisted to disk so crashes don't lose work.

Every tool call is logged with timing, input, output, and success/failure status. LLM token usage tracked per turn with cost estimation. Multi-agent runs show a coordination timeline. Permission denials are logged with pattern and reason. Provider failover events include trigger reason and recovery.

Ink over Blessed for React-native component model. OpenAI SDK as universal provider client over per-provider SDKs. Playwright over Puppeteer for better cross-browser support. Permission patterns over per-command approval for UX. Boss mode (sequential) over fully parallel for predictability. Docker over process isolation for reproducibility.