Athena

Athena is a single-user personal assistant and second brain that runs inside your coding agent. It lives in your own Claude Code or Codex session and orchestrates your real tools — Gmail, Google Calendar, Notion, and an object-storage knowledge vault — under one shared agent contract. You talk to it in plain language; it captures what matters, retrieves it by meaning, and surfaces the right work at the right moment.

Are you an AI agent reading this repo? You are Athena. Read AGENTS.md — it is your operating contract. To set Athena up for a user, use the install prompt directly below.

Install Athena with your agent

Paste this into Claude Code, Codex, or any capable coding agent. It will install the CLI, wire up your services, and run first-time setup — pausing to ask you only for the credentials no agent can create on your behalf.

Install and set up Athena for me — a single-user personal assistant and "second
brain" that runs inside this agent session. Repo: https://github.com/firatcand/athena
macOS/Linux only. Work step by step and pause to ask me for anything only I can provide.

1. Fetch and read the repo's AGENTS.md so you understand Athena and its safety rules
   (email is draft-only; never run S3 bucket-hardening or destructive store commands
   yourself — hand those to me).
2. Install the CLI — try in order, stop at the first that works, then confirm
   `athena --version`:
   • npm install -g @firatcand/athena          (needs Bun: https://bun.sh)
   • else: download install.sh from the latest release, show it to me, then run it
     (self-contained binary — no Bun needed)
   • else: git clone the repo, `bun install`, `bun run build`
3. Run `athena doctor` to see which external tools are missing, then help me install +
   authenticate each: gws (Gmail/Calendar), ntn (Notion), aws (S3 vault), hydradb
   (semantic brain). Give me the install command for each; I'll do the auth.
4. Ask me for the credentials only I can create — one at a time, each with a one-line
   pointer to where I get it — and set them as env vars (or tell me to load them via my
   secret manager): NOTION_API_TOKEN; ATHENA_S3_BUCKET + AWS_REGION +
   AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY; HYDRA_DB_TENANT_ID + HYDRA_DB_API_KEY;
   and a Google OAuth client for gws.
5. Run `athena init`. Use the persona details I give you (name, role, projects,
   timezone) and the resource IDs above. This scaffolds the workspace, provisions my
   9 Notion databases, stores env, and renders my AGENTS.md contract.
6. Print the exact one-time S3 bucket-hardening commands (create bucket, enable
   versioning, block public access) for ME to run in my own terminal — do NOT run them.
7. Verify: `athena doctor` is all-green and `athena status` prints my orientation. Then
   tell me Athena is ready and give me 3 example things I can say to it.

Prefer to drive it yourself? See Install and Setup below.

What Athena is

Athena is not a chatbot or an MCP server — it is a schema-aware CLI plus an agent contract. Your agent host (Claude Code or Codex) is the runtime; Athena is the identity and the toolset layered on top of it via AGENTS.md.

Three ideas make it different:

• CLIs are the tool surface — not MCPs. The athena command is the core orchestrator; purpose-built external CLIs (gws, ntn, aws, hydradb) handle service-specific work. Deterministic, inspectable, scriptable.
• A two-tier knowledge model. A canonical, agent-only vault in object storage holds one self-describing markdown document per idea. A semantic brain makes everything recallable by meaning. Notion stays the curated, human-facing surface for work in progress — content flows one way (vault → Notion); only state and URLs flow back.
• Single-user by design. It's your second brain, on your agent subscription. macOS / Linux.

Features & benefits

| You get | How it works | |---|---| | Capture anything, durable instantly | athena capture writes a canonical vault document synchronously (the slug prints immediately), then projects it to the brain — recallable by meaning moments later. | | Save the web into your brain | athena ingest-source --url … fetches a page (SSRF-guarded), extracts readable text, and files it as a source doc. | | Find by meaning, not keywords | athena search is semantic recall intersected with metadata filters (type, stage, project) — precise, not just fuzzy. | | Follow the threads | Typed relations between docs (athena link) power graph traversal (athena related, athena map) so connected ideas surface together. | | Meeting prep & logging | Parse "meeting with X next Tuesday" into a Google Calendar event with a Meet link plus a Notion meeting note — cross-referenced to your CRM. | | Gmail triage — draft-only | Classify and label unread mail and prepare replies as drafts. Athena never sends; you press send. | | Calendar prep | A per-meeting brief: who they are, last contact, relevant captured notes cited by slug. | | Promote to Notion | athena promote moves a captured item into the right one of your 9 Notion databases (Tasks, Ideas, Content Hub, Projects…), one-way, with state + URL flowing back. | | Self-maintaining | athena dream is a headless enrichment pass: re-projects stale docs, surfaces Notion drift and orphans — it surfaces, never silently mutates. | | Auditable & safe by construction | Versioned vault, no silent deletions, least-privilege sandboxing (see Safety). |

Install

macOS / Linux only. Three ways, easiest first:

1. npm (needs Bun as the runtime)

npm install -g @firatcand/athena
athena --version

2. Prebuilt binary — self-contained, no Bun required. Deliberately not a curl | sh one-liner: download it, read it, then run it. It picks the binary for your platform, verifies its SHA-256 against the release checksums (fail-closed), and installs to ~/.local/bin/athena.

curl -fsSLO https://github.com/firatcand/athena/releases/latest/download/install.sh
less install.sh          # inspect before running
sh install.sh

3. From source (needs Bun)

git clone https://github.com/firatcand/athena && cd athena
bun install
bun run build            # produces ./athena

Setup

1. Run the onboarding wizard. athena init handles persona, workspace scaffold, credential storage, and Notion provisioning in one pass — prompting for anything you don't pass as a flag:

athena init              # persona → renders AGENTS.md; scaffolds workspace;
                         # stores env; provisions your 9 Notion databases
athena doctor            # re-check external CLIs are installed + authenticated
athena status            # daily orientation: inbox counts, health, what needs attention

2. Bring your own keys. Athena is secret-manager-agnostic — it reads credentials from the process environment and doesn't care how they got there. Either drop them in a gitignored .env.local (cp .env.example .env.local && chmod 600 .env.local), or launch your agent session under a secret manager (Infisical, Doppler, 1Password, direnv, …) so Athena and the external CLIs inherit them.

| Variable | Needed for | |---|---| | NOTION_API_TOKEN | Notion (the only globally required var) | | ATHENA_S3_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | the vault | | HYDRA_DB_TENANT_ID, HYDRA_DB_API_KEY (HYDRA_DB_SUB_TENANT_ID optional) | the semantic brain | | GOOGLE_WORKSPACE_CLI_* | Gmail / Calendar via gws | | OPENAI_API_KEY | optional — only the opt-in contradiction judge |

gws reads its OAuth client config from the ambient shell environment (not Athena's .env.local) and manages its own token store. Your per-workspace Notion database IDs live in a local config file, not in .env.example.

3. Provision the vault bucket — operator-run. One-time bucket create + enable versioning + block public access is run by you in your own terminal, never by the agent. See ARCHITECTURE.md.

External CLIs Athena orchestrates (install + authenticate each):

| CLI | Purpose | Install (example) | |---|---|---| | gws | Google Workspace — Gmail + Calendar | brew install gws | | ntn | Notion API | npm install -g ntn | | aws | S3 vault provisioning + manual object ops | brew install awscli | | hydradb | Semantic brain — recall + auto-graph | pipx install hydradb-cli |

How you use it

Mostly you just talk to Athena in natural language inside your agent session; it translates intent into the CLI calls below. You can also drive the CLI directly:

# Capture a thought — durable immediately, semantically recallable shortly after
athena capture --type concept \
  --body "CLIs beat MCPs as an agent tool surface" --tags architecture
# → Filed: wiki/concepts/clis-beat-mcps-as-an-agent-tool-surface

# Ingest a URL (fetch → extract readable text → project to the brain)
athena ingest-source --url "https://example.com/some-article" --kind article

# Retrieve by meaning, filtered by metadata
athena search "agent tool surface" --type concept
athena get wiki/concepts/clis-beat-mcps-as-an-agent-tool-surface

# Connect ideas, then explore the neighborhood
athena link --from wiki/concepts/a --to wiki/concepts/b --kind related --reason "same thesis"
athena map "agent tool surface"

# Promote a captured item into Notion (one-way; state + URL flow back)
athena promote --slug wiki/ideas/<slug> --to task --project "<your-project>" --priority Medium

And in plain language, for example:

• "Triage my unread inbox from the last day." → classifies, labels, prepares drafts (never sends).
• "What's on my calendar tomorrow, and prep me for each meeting."
• "What have I read about agent tool surfaces?" → semantic retrieval + a synthesis with cited slugs.

Full command reference lives in AGENTS.md.

How it works at a glance

        you  (natural language, inside Claude Code / Codex)
                              │
                              ▼
                   ┌────────────────────┐
                   │     Athena CLI     │   schema-aware orchestrator
                   │    (AGENTS.md)     │   — one shared contract
                   └────────────────────┘
             capture / ingest │        │ orchestrate
                              ▼         ▼
                 ┌──────────────┐   external CLIs
                 │   S3 vault   │   gws · ntn · aws · hydradb
                 │  (canonical) │
                 │  markdown +  │── project body ──▶ ┌───────────────┐
                 │  frontmatter │ ◀─ recall (search)─│    HydraDB    │
                 │  + _index    │                    │ semantic brain│
                 └──────┬───────┘                    └───────────────┘
                        │  promote  (one-way: body)
                        ▼
                 ┌──────────────┐
                 │    Notion    │  curated human work-in-progress
                 │  (your DBs)  │  ◀─ state + URL flow back
                 └──────────────┘

• Vault (canonical): one self-describing markdown+YAML document per knowledge unit, plus a derived index for metadata-filtered search and graph adjacency.
• Brain (semantic): recall by meaning and an auto-derived entity graph. It holds no metadata and no typed edges — that structured layer lives entirely in the vault.
• Notion (human surface): curated work in progress; promotion is one-way for content, with only state and URLs flowing back.

Full design in ARCHITECTURE.md · shipped-vs-planned in ROADMAP.md.

Safety

Athena is built to be trustworthy with your inbox and your data:

• Email is draft-only. It never auto-sends. Every send-capable command is deny-listed at the sandbox layer and reinforced in the agent contract. Triage classifies, labels, and prepares drafts — you press send.
• No silent deletions. Documents are never removed without explicit, per-document confirmation. The vault is versioned, so routine deletes are recoverable.
• Surface, don't mutate. Maintenance passes report drift and orphans; healing external state stays an explicit, confirmed action.
• Least privilege. Destructive storage/tenant operations are deny-listed for the agent; bucket hardening is operator-run only.

License

MIT — see LICENSE.