Skip to main content
Get Athena running in 5 minutes. This guide gets you to your first session as quickly as possible.
1

Clone the repository

Clone the Athena repository to your local machine:
git clone https://github.com/winstonkoh87/Athena-Public.git
cd Athena-Public
Clone it anywhere you keep projects (e.g. ~/Projects/). This folder is your Athena workspace — your memory, protocols, and config all live here.
2

Set up a virtual environment

Create and activate a Python virtual environment:
python3 -m venv .venv
source .venv/bin/activate
On macOS (Homebrew) and Ubuntu 23.04+, installing packages without a virtual environment will fail with externally-managed-environment. Always create a .venv first.
3

Install the SDK

Install Athena in your virtual environment:
# ~30 seconds, no ML dependencies
pip install -e .
Don’t pip install athena-cli — that’s a different, unrelated package. Always install from inside the cloned repo.
4

Open in your AI editor

Open the Athena-Public/ directory as your workspace root in one of these editors:
Athena does NOT work through ChatGPT.com, Claude.ai, or Gemini web. You need an app that can read files from your disk. Think of Athena as a workspace for your editor, not a plugin for a chatbot.
“Why do I open the Athena folder instead of my own project?” — Athena is a workspace, not a library you install into another repo. You work inside the Athena folder, and it remembers everything across sessions. To work on external projects, reference them from within Athena or use multi-root workspaces in your IDE.
5

Boot Athena

In your IDE’s AI chat panel (e.g. Cmd+L in Cursor, the chat sidebar in Antigravity), type:
/start
/start, /end, and /tutorial are AI chat commands — you type them in the chat window where you talk to the AI, not in the terminal. They are slash commands that the AI agent reads and executes.
6

Take the guided tour (optional)

First time? Run the tutorial to build your profile:
/tutorial
This walks you through everything: what Athena is, how it works, builds your profile, and demos the tools (~20 min). Confident users can skip it.
7

Close your session

When you’re done working:
/end
This finalizes the session log, extracts key decisions, and commits everything to memory.

​
That’s it!

No API keys. No database setup. The folder is the product.

Your first session

Detailed walkthrough with tips

Installation guide

Full setup instructions

​
Important notes

Forks of public repos are public by default. If you plan to store personal data (health records, finances, journals), create a new private repo instead of forking. Copy the files manually or use git clone + git remote set-url to point to your private repo.
See the full setup guide for detailed walkthroughs and troubleshooting.

​
Windows compatibility

Athena uses modern terminal outputs (Emojis, Box-Drawing characters) which may cause a UnicodeEncodeError on legacy Windows terminals. To resolve this:
  1. Use Windows Terminal (available in the Microsoft Store)
  2. Set your Python IO encoding to UTF-8:
    • PowerShell: $env:PYTHONIOENCODING="utf-8"
    • Command Prompt: set PYTHONIOENCODING=utf-8
  3. Alternatively, enable strict UTF-8 globally: Settings > Time & Language > Language & Region > Administrative language settings > Change system locale > Check “Beta: Use Unicode UTF-8 for worldwide language support”

Build docs developers (and LLMs) love

Get started for freeTalk to us