Installation Issues
”athena: command not found”
Ensure the SDK is installed from the cloned repo inside a virtual environment:
cd Athena-Public
python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
pip install -e .
source .venv/bin/activate).
“error: externally-managed-environment” (PEP 668)
This error occurs on macOS (Homebrew Python) and Ubuntu 23.04+ when installing packages without a virtual environment. Fix:
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
On macOS (Homebrew) and Ubuntu 23.04+, installing packages without a virtual environment will fail with externally-managed-environment. Always create a .venv first.
Session & Workflow Issues
Session logs not saving
Run /start at the beginning of your session. The agent needs to initialize before it can log.
Solution:
Check .context/memories/session_logs/ to verify logs are being created.
”No session log found” error
This occurs when you try to run /end or /save without first running /start.
Solution:
- Run
/start first to create a session log
- Continue your work
- Then use
/save or /end as needed
Workflow not recognized
Ensure the workflow file exists in .agent/workflows/ directory.
Check:
You should see files like start.md, end.md, think.md, etc.
Context & Memory Issues
Context window errors
Athena auto-retrieves ~2K tokens of context. If you’re hitting limits, your session may have drifted.
Solution:
Run /save to checkpoint and start fresh:
This creates a checkpoint and frees up context space.
Agent seems to forget previous conversations
This usually means session logs aren’t being properly saved or loaded.
Check:
- Verify
/start was run at the beginning of the session
- Check that
.context/memories/session_logs/ contains recent logs
- Ensure the SDK is properly installed (
pip install -e .)
Script & Automation Issues
Scripts don’t run
Check Python is installed:
Should return Python 3.10 or higher.
Permission denied (macOS/Linux)
Scripts may need execute permissions:
chmod +x .agent/scripts/*.py
Windows encoding errors
Run chcp 65001 before starting, or use the included ensure_env.ps1:
chcp 65001
# OR
.\ensure_env.ps1
Slow boot times
| Mode | Expected Time |
|---|
| Cold boot (first session) | ~1–2 minutes |
| Warm boot (cached) | < 5 seconds |
- Check your internet connection (for cloud embeddings)
- Reduce context loading by archiving old session logs
- Use local mode to avoid network latency
High API costs
Most users spend < $5/month on API calls.
If costs are higher:
- Switch to local mode for basic usage
- Review embedding frequency in your configuration
- Use lighter models for routine tasks
- Avoid GraphRAG if you don’t need it (~$50 one-time cost)
Vector Search & Database Issues
VectorRAG not working
Ensure you have the required API keys configured:
export GOOGLE_API_KEY="your-key-here"
export SUPABASE_URL="your-url-here"
export SUPABASE_ANON_KEY="your-key-here"
Database connection errors
Check Supabase credentials:
- Verify
SUPABASE_URL and SUPABASE_ANON_KEY are set
- Test connection to Supabase dashboard
- Check if free tier limits have been exceeded
IDE Integration Issues
Cursor/VS Code not recognizing workspace
Ensure .athena_root file exists in your workspace root:
# Should exist after running athena init
ls -la .athena_root
Antigravity integration issues
Verify AGENTS.md is in your workspace root:
athena init --ide antigravity
Getting Help
If you’re still experiencing issues:
- Check the FAQ for common questions
- Search GitHub Issues: Existing issues
- Ask in Discussions: Community forum
- Report a bug: New issue
When reporting issues, include:
- Your OS and Python version
- Full error message
- Steps to reproduce
- Relevant configuration files (with secrets redacted)