gideon: Instructions file for Codex

AGENTS.md

Setup and orientation guide for Gideon. Written for whoever (or whatever) is standing this up for the first time: what the features are, which ones need credentials, and exactly which credentials.

The short version: three environment variables get you a working instance. Everything else is optional, and every integration you leave blank simply does not appear as a tool. Nothing breaks, the tool just is not offered to the model.

---

1. Fastest path to a running instance

git clone https://github.com/atlyslabs/gideon.git
cd gideon
cp backend/.env.example backend/.env

Edit backend/.env and set three things:

Variable	How to get it
ANTHROPIC_API_KEY	console.anthropic.com. Or use OPENAI_API_KEY / KIMI_API_KEY instead, see section 5.
ENCRYPTION_KEY	python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
SINGLE_USER_EMAIL	Your email. Used as the local identity.

Then:

docker compose up

Open http://localhost:3000. Postgres, Redis, the API and the frontend all come up together, and the schema is applied on first boot from backend/migrations/init.sql.

You are now logged in as one user with no password. That is AUTH_MODE=single_user, the default, and it is the intended setup for personal and self-hosted use. Do not expose an instance in this mode to a network you do not control, because there is no authentication in front of it.

Without Docker

# backend (Python 3.13)
cd backend && poetry install && poetry run uvicorn main:app --reload --port 8080

# frontend (Node 20)
cd frontend && npm install && npm run dev

Postgres and Redis still have to be reachable at whatever backend/.env points at.

---

2. Features, and what each one costs you in setup

"Needs nothing" means it works on a fresh instance with only the three required variables above.

Feature	What it does	What it needs
Chat	Streaming chat, extended thinking, tool use, file understanding	Needs nothing
Memory	Remembers durable facts about you, recalls them in later chats	Needs nothing. docker compose runs the Neo4j that powers the graph view; without it memory still works, backed by Postgres
Todos and delegation	Todos, plus delegating one to people over a Slack group DM with recurring nudges	Todos need nothing. Delegation needs Slack
Workflows	Natural-language automations on a schedule (every N minutes to weekly)	Needs nothing, but a workflow is only as useful as the integrations it can reach
Skills	Reusable instructions Gideon learns and applies	Needs nothing
Custom slash commands	Your own /<slug> prompts	Needs nothing
Hub	Daily briefing: meetings, todos, suggestions	Needs nothing. Meetings need Google, weather needs WEATHER_API_KEY
Usage and cost	Per-model token and USD accounting	Needs nothing
In-chat React previews	Gideon writes a component, you see it rendered	Needs a separate compile service, see PREVIEW_BUILDER_URL in section 7. Returns 501 unset
Meeting prep	Auto-generated prep notes before a meeting	Google (Calendar)
Email auto-draft	Drafts replies in your voice	Google (Gmail)
Slack trigger	@-mention Gideon in Slack, it replies in thread	GIDEON_BOT_TOKEN
Email trigger	CC a mailbox to kick off a run	GIDEON_INBOX_EMAIL + Google
WhatsApp trigger	Message Gideon on WhatsApp	WHATSAPP_* (Meta Cloud API)
Analytics over your warehouse	Gideon writes SELECT-only SQL against ClickHouse	CLICKHOUSE_*, see section 6
Surveys	Admin-built in-app surveys with cohort targeting	SURVEY_ADMINS (comma-separated emails)
Web search	Exa-backed research	EXA_API_KEY