Features
Every command and capability in Athena is designed for developer control, local privacy, and uncompromising honesty.
1. Analysis & Multi-Ecosystem Detection
Deep AST inspection across 10 language ecosystems without external telemetry.
Athena scans your repository structure, package manifests, build definitions, schema files, and HTTP routers. It identifies languages, frameworks, monorepos, database entities, environment variable names, container configs, and CI workflows.
- 10 language ecosystems: JavaScript/TypeScript (npm), Python, Go, Rust, Java/Kotlin (Maven, Gradle), PHP (Composer), C#/.NET (NuGet), Ruby, Dart/Flutter (pub), Elixir (Hex/Mix)
- Also detected in any project: Dockerfiles, Compose, Kubernetes, Terraform, CI pipelines and hosting configs
- Detects environment variable names, but never records or exposes secret values
- Every finding is labeled FACT, DETECTED, INFERRED or UNKNOWN, with file evidence
2. Knowledge Docs with Preserved Edits
Re-analyze as often as you want — your custom notes and manual edits are never lost.
Athena writes 11 structured markdown documents to .athena/, plus rules.md. Re-running analysis automatically updates generated sections based on repository changes while surgically preserving your developer notes and custom guidelines.
- 11 modular generated documents: project, architecture, database, api, auth, security, testing, debugging, performance, code-review, deployment
- Clear delimiter headers protect developer-written annotations
- Commit-friendly Markdown ready for git version control
- Evidence citations ensure teammates and AI agents know exactly where facts originate
3. Developer Rules (rules.md)
Establish architectural boundaries and project conventions across all AI coding agents.
rules.md is a 100% developer-owned file. Athena never overwrites it. When agents run, they read these rules, and athena review lists them as a checklist for your changes.
- Owned entirely by you — Athena never regenerates it; it only changes when you edit it or use athena rules
- Fed directly to Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Antigravity, Windsurf, Cline, and any agent that reads AGENTS.md
- Prevents recurring agent mistakes (e.g. invalid type casts, missing validation, wrong import paths)
- Listed by athena review as a checklist for every change
- Never import from database directly in route handlers; use service layer.
- All user input must pass through Zod schema validation.
- No any types allowed under src/core/.
4. Sync & Watch
Detect code drift as you develop, without surprise file overwrites.
athena sync shows which documents would change and why, then asks once before applying them. Use --dry-run to see the plan without writing, --diff to see full diffs, --yes to apply without asking, and --check in CI (exits with code 1 if knowledge is out of date). Sections you edited by hand are kept unless you pass --force.
- athena sync shows which documents would change and asks once before applying
- Updates are NEVER applied blindly — human-in-the-loop review
- Full diffs of proposed changes with athena sync --diff
- Keeps AI context fresh as features evolve across commits
5. Local Web UI (athena open)
A browser-based knowledge cockpit running strictly on 127.0.0.1 with session security.
Athena listens on 127.0.0.1, port 7432 by default (or the next free port if 7432 is busy), and opens http://127.0.0.1:7432/#token=…. The token is in the URL fragment (after #), so browsers never send it in requests or Referer headers.
- Listens on 127.0.0.1, port 7432 by default (or next free port if busy)
- Token is in the URL fragment (after #), so browsers never send it in requests
- Markdown editor with Preview, Edit and History (from Git) tabs for every knowledge document
- Real-time sync diff viewer, rules manager, and activity monitor
6. Agent Integrations & Activity Hooks
Plug into Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Antigravity, Windsurf, Cline, and any agent that reads AGENTS.md.
Athena seamlessly links with leading AI coding tools. It configures agent instructions, provides rules, and connects hooks so you can track agent tool invocations through athena activity.
- Dedicated setup for Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Antigravity, Windsurf, Cline, and AGENTS.md
- Athena activity tracks agent tool calls observed through hooks
- Instructs agents to read the relevant .athena/ knowledge before they change code
- Consistent instruction format across terminal and editor agents
7. MCP Server (12 Stdio Tools)
Model Context Protocol interface enabling AI agents to fetch live context on demand.
Athena provides a full Model Context Protocol (MCP) server over standard input/output. Agents can call 12 distinct tools to query architecture, schemas, routes, rules, and diffs on the fly.
- 12 MCP tools available: get_relevant_context, get_project_context, get_architecture, get_database_schema, get_api_context, get_security_context, get_project_rules, get_knowledge_document, get_project_changes, get_project_graph, get_athena_status, update_knowledge
- Read-only by default for maximum security
- update_knowledge requires explicit opt-in with --allow-write flag
- Registered automatically for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), Codex (.codex/config.toml), GitHub Copilot in VS Code (.vscode/mcp.json) and Gemini CLI (.gemini/settings.json). Any other MCP client can run athena mcp.
8. Project Graph & Context Engine
Pinpoint exact knowledge files for any task without overloading agent context windows.
Large repositories overwhelm AI context windows. athena context analyzes your requested task, traverses package and route graphs, and recommends the minimal set of verified knowledge files to load.
- athena graph / athena architecture maps dependencies, routes, and entities
- Eliminates context bloat and token waste for coding agents
- Explains WHY each file is recommended with specific citations
- Helps agents skip knowledge that isn't relevant to the task
9. Security Scan & Diff Review
Execute native ecosystem audit tools and review git diff facts and rules.
athena security wraps your language's native audit commands (npm/pnpm audit, pip-audit, govulncheck, cargo audit, composer audit) and saves results to .athena/security-scan.json. They are added to security.md on the next athena sync. A tool that isn't installed is reported as unknown, never as 'no problems'. athena review checks your current git diff for facts worth reviewing. It flags possible secrets and committed .env files (these two are blockers and exit with code 1), new dependencies, changes to API, auth or database code, source changes without test changes, TODO/FIXME or debug leftovers, large added files, high/critical advisories from the last athena security scan, and knowledge that is out of date for the change. It then lists your enabled rules from rules.md and the code-review.md checklist for you or your agent to go through. Rules are a checklist, not automated checks.
- Runs ecosystem audit tools locally without third-party telemetry
- Checks uncommitted git diffs for facts worth reviewing before commit
- Lists your enabled rules from rules.md and code-review.md as a checklist
- Flags accidental secrets and committed .env files as blocking errors
10. Optional AI Enrichment (Always INFERRED)
Optional LLM synthesis for high-level summaries — never required, always marked INFERRED.
The provider is chosen in .athena/config.json. Check the setup with athena ai status. athena ai enrich sends redacted knowledge documents to the provider and writes the answer to a separate file, .athena/ai-suggestions.md, labeled INFERRED. It never edits your knowledge documents. Flags: --docs <list> (default: project, architecture, database, api), --dry-run (shows exactly what would be sent and sends nothing), and --consent (required before sending anything to a remote provider). Default models: Anthropic claude-sonnet-5, OpenAI gpt-4.1-mini, Google gemini-2.5-flash, Ollama llama3.1. API keys are read from ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY). Ollama runs locally.
- 100% optional: core analysis works completely offline without AI
- Default models: Anthropic claude-sonnet-5, OpenAI gpt-4.1-mini, Google gemini-2.5-flash, Ollama llama3.1
- Writes suggestions to separate .athena/ai-suggestions.md, labeled INFERRED
- Never edits your knowledge documents; requires --consent for remote providers
11. CI checks & pre-commit hook
Automate knowledge drift checks and PR diff reviews in CI and local git hooks.
Keep your knowledge documents in sync and block secrets from landing in repository history. Athena provides a native GitHub Action and a pre-commit hook that checks for stale knowledge and uncommitted secrets.
- GitHub Action (uses: Sabari-Vasan-SM/athena@v0) runs athena sync --check and fails when .athena/ is out of date
- On pull requests it also runs athena review against the PR base, and fails on blockers: possible secrets and committed .env files
- With comment: true it posts one PR comment and updates it on later pushes (requires pull-requests: write permissions)
- Pre-commit hook: athena git-hook install blocks commits when .athena/ knowledge is out of date (--review also blocks possible secrets)
- athena git-hook status shows whether it's installed; athena git-hook uninstall removes only Athena's part
- Teammates without Athena installed are not blocked; husky, lefthook or pre-commit users can add npx --no-install athena sync --check
- Runs on Linux and macOS runners; findings show type and file location only, never matched secret values
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the review diffs the pull request against its base commit
- uses: Sabari-Vasan-SM/athena@v0
with:
comment: true