// reference

Configuration

Everything lives under ~/.astra (override with ASTRA_DIR) — settings, sessions, memory, plans, traces, gateway auth, and Twitter sessions.

Config directory

Path	Purpose
`settings.json`	Provider/model, thinking level, agent & orchestrator mode, API keys, skills, permissions, project rules.
`sessions/*.jsonl`	Chat history (one file per session).
`last-session.json`	Pointer to resume with `-c`.
`memory.json`	Cross-session memory.
`plan.json`	Active task plan.
`mcp.json`	MCP server definitions.
`traces/<sessionId>/`	Boss worker trace logs (JSONL).
`telegram-sessions.json` etc.	Gateway chat → session id mappings.
`whatsapp-auth/`	Baileys WhatsApp Web credentials.
`twitter-profile/`	Persistent X/Twitter browser session (cookies).
`twitter-batch-results/`	Per-item reports from `astra twitter-batch` runs.
`schedules.json`	Active reminders and daily scheduled tasks.

settings.json

{
  "defaultProvider": "free",
  "defaultModel": "meta-llama/llama-3.3-70b-instruct:free",
  "thinkingLevel": "off",
  "agentMode": "build",
  "orchestratorMode": "off",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "permissions": {
    "bash": { "*": "ask", "npm test *": "allow" }
  },
  "projectRules": {
    "enabled": true
  },
  "multiAgent": {
    "maxParallel": 3
  }
}

Set orchestratorMode to "boss" or "multi" to enable an orchestrator by default. multiAgent.maxParallel caps concurrent agents.

Thinking level (thinkingLevel in settings or /settings) enables extended reasoning on supported models: Claude Sonnet/Opus 4+, OpenAI o3/o4-mini, and Gemini 2.5+. Other providers ignore it.

Environment variables

Variable	Description
`OPENROUTER_API_KEY`	OpenRouter (free tier models).
`OPENAI_API_KEY`	OpenAI.
`ANTHROPIC_API_KEY`	Anthropic (Claude).
`GROQ_API_KEY`	Groq.
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	Google Gemini.
`ASTRA_DIR`	Config directory (default `~/.astra`).
`ASTRA_MAX_TOOL_ROUNDS`	Max tool-call rounds per turn (default `50`).
`ASTRA_MAX_DELEGATIONS`	Max worker delegations per boss turn (default `10`).
`ASTRA_MAX_SPAWNS`	Max agents spawned per multi-agent turn (default `12`).
`ASTRA_COMPACTION_ENABLED`	`0`/`false` to disable auto-compaction.
`ASTRA_COMPACTION_RESERVE_TOKENS`	Tokens reserved for the model response (default `16384`).
`ASTRA_NO_PROJECT_RULES`	`1` to disable project rules injection.
`TELEGRAM_BOT_TOKEN` / `TELEGRAM_ALLOWED_USER_IDS`	Telegram gateway (overrides settings).
`DISCORD_BOT_TOKEN` / `DISCORD_ALLOWED_USER_IDS`	Discord gateway (overrides settings).
`WHATSAPP_ALLOWED_USER_IDS`	WhatsApp gateway allowlist.

Voice

Trigger voice input with /voice — speak a task instead of typing it. Voice prompts are treated like any other message and can be combined with gateways for hands-free use.

Context compaction

When a session approaches the model's context window, Astra summarizes older messages to free space (tunable via compaction in settings or ASTRA_COMPACTION_* env vars). Use /compact manually to force a summarization with an optional focus.