Astra logoAstra/docsgithub ↗

// open source

Contributing

Astra is MIT licensed and built by @VishalDevx. The core is a single-agent ReAct loop — no LangGraph, no external agent framework.

Architecture

The core loop streams an LLM response, executes tool calls, and repeats until done. Boss mode nests additional runAgentLoop instances inside the delegate tool, following the orchestrator-workers pattern. Multi-agent mode runs those loops concurrently inside spawn_agents, with a per-turn file claim registry enforcing disjoint write scopes and serialized approval prompts.

src/
├── agent/
│   ├── loop.ts              # Core ReAct loop (+ model failover)
│   ├── model-failover.ts    # Rate-limit/quota detection, fallback picker
│   ├── session.ts           # Session state, events, boss/multi routing
│   ├── orchestrator/        # Boss prompt, workers, traces
│   ├── multi-agent/         # Parallel agents, file claims, model assignment
│   └── tools/               # Built-in tool implementations
├── gateway/
│   ├── shared/              # Channel bridge, queue, commands, format
│   ├── telegram/            # Telegram bot daemon (grammY)
│   ├── discord/             # Discord DM gateway (discord.js)
│   ├── whatsapp/            # WhatsApp Web gateway (Baileys)
│   └── scheduler.ts         # Fires due reminders and daily tasks
├── providers/               # OpenAI, Groq, Gemini, OpenRouter, Ollama
├── ui/                      # Ink TUI
└── modes/print-mode.ts      # Headless / CI output

Development

git clone https://github.com/VishalDevx/astra.git
cd astra
npm install
npm run dev              # interactive TUI
npm test                 # run the test suite
npm run test:watch       # watch mode
npm run test:coverage    # coverage report
npm run build && npm start

Evaluation suite

Astra includes agent evaluations used to guard regressions:

npm run eval                  # smoke suite (optional)
npm run eval:full            # full agent evaluations (expensive)
npm run eval:deterministic   # deterministic evals, no API keys

Ways to help

  • Open issues for bugs and sharp edges on the issue tracker.
  • Add tests for existing tools and gateways.
  • Improve this documentation and the website.
  • Suggest new tools, providers, and gateway integrations via pull requests.

License

Astra is released under the MIT License.