Skip to main content

​
Overview

Athena works with any agent that reads Markdown. For agents that support project-level config, athena init generates the native configuration file automatically.
The beauty of Athena’s architecture is that it’s IDE-agnostic. The entire system is stored in Markdown files that any AI agent can read.

​
First-Class Integrations

Config File: AGENTS.mdInit Command:
athena init --ide antigravity
Features:
  • Native AGENTS.md support
  • Multi-agent coordination
  • Full workspace access
  • Terminal execution
Recommended Settings:
  • Non-workspace file access: Enabled
  • Terminal auto-execution: Always Proceed
  • Secure mode: Disabled (for trusted environments)

​
Generic Compatibility

Any AI agent that reads Markdown files from the project directory will work out of the box:

Claude Code

Reads CLAUDE.md or .claude/ directoryNo init required - Just create workspace

Windsurf

Reads project files directlyNo init required - Point at workspace

GitHub Copilot Chat

Reads workspace filesNo init required - Works with VS Code

Local LLMs

Any local modelManual setup - Point at .framework/ and .context/

​
How Init Works

When you run athena init --ide <name>, Athena creates:
1

Standard Workspace Structure

Creates .agent/, .context/, .framework/ directories
2

IDE-Specific Config File

Generates the config file that tells the agent where to find Athena’s memory, identity, and workflows
3

Boot Instructions

Adds references to /start, /end, /save workflows
4

Directory References

Links to key directories and files
5

Session Discipline

Includes session management guidelines

​
Configuration File Contents

The IDE-specific config file is a Markdown document containing:

​
Boot Instructions

## Core Workflows

| Command | File | Purpose |
|:--------|:-----|:--------|
| `/start` | `.agent/workflows/start.md` | Boot the agent session |
| `/end` | `.agent/workflows/end.md` | Close session, file insights |
| `/save` | `.agent/workflows/save.md` | Mid-session checkpoint |

​
Directory Map

## Key Directories

- `.framework/` - Core identity and principles (stable)
- `.context/` - User-specific data (frequently updated)
- `.agent/` - Agent configuration (workflows, scripts, skills)

​
Session Discipline

## Session Discipline

1. **Always `/start`** - Load identity and context
2. **Always `/end`** - Commit insights to memory
3. **Checkpoint often** - Use `/save` before risky changes
4. **Load on-demand** - Don't load all files upfront

​
Multi-Agent Support

Protocol 413: Multi-Agent CoordinationWhen running multiple AI agents on the same workspace:
  • ❌ NEVER git stash (other agent’s WIP lost)
  • ❌ NEVER switch branches without explicit request
  • ✅ ALWAYS git pull --rebase before pushing
  • ✅ Commit only YOUR changed files

​
Multi-Agent Safety

​
Required Permissions

To achieve “Total Life OS” functionality, the IDE must have elevated permissions:
SettingValuePurpose
Non-Workspace File AccessEnabledAllows Athena to reach folders outside its root
Terminal Auto ExecutionAlways Proceed (optional)Enables autonomous script execution
Secure ModeDisabledRemoves friction for trusted environments
Power vs. Safety: An AI that manages your entire life must have access to your entire life. There is no way to sandbox an agent while simultaneously granting it full autonomy.Mitigation:
  1. Quicksave before dangerous operations
  2. Deny List catastrophic commands (e.g., rm -rf /)
  3. Git Commit on every /end session

​
Adding a New IDE

To add support for a new IDE:
1

Determine Config Location

Find where the IDE reads its agent rules from (e.g., .cursor/rules.md)
2

Add Template

Add a template constant to src/athena/cli/init.py
3

Add Handler

Create handler function in src/athena/cli/init.py
4

Register IDE

Add the IDE name to the choices list in src/athena/__main__.py
5

Test Init

Test athena init --ide yourname in clean directory
6

Submit PR

Submit pull request with new IDE support

​
Example Implementation

# In src/athena/cli/init.py

YOURIDE_TEMPLATE = """
# Athena Configuration for YourIDE

## Core Workflows

| Command | File | Purpose |
|:--------|:-----|:--------|
| `/start` | `.agent/workflows/start.md` | Boot the agent session |
| `/end` | `.agent/workflows/end.md` | Close session, file insights |

## Key Directories

- `.framework/` - Core identity (stable)
- `.context/` - User data (updated)
- `.agent/` - Configuration

## Session Discipline

1. Always `/start` to load identity
2. Always `/end` to commit insights
3. Use `/save` before risky changes
"""

def create_youride_config():
    config_path = Path(".youride/athena.md")
    config_path.parent.mkdir(exist_ok=True)
    config_path.write_text(YOURIDE_TEMPLATE)
    print(f"✓ Created {config_path}")

​
Compatibility Matrix

FeatureAntigravityCursorVS CodeGemini CLIGeneric
Auto-init✅✅✅✅⚠️ Manual
Workflow support✅✅⚠️ Partial✅⚠️ Depends
Multi-agent✅✅❌❌❌
Terminal execution✅✅✅✅⚠️ Depends
File access✅✅⚠️ Limited✅⚠️ Depends
VectorRAG✅✅✅✅✅
Legend:
  • ✅ Full support
  • ⚠️ Partial/manual setup required
  • ❌ Not supported

​
Troubleshooting

Symptom: Agent acts like generic AI, ignores workflowsSolution:
  1. Check config file exists in correct location
  2. Verify agent has workspace permissions
  3. Manually reference .framework/modules/Core_Identity.md
  4. Restart IDE/agent
Symptom: /start doesn’t workSolution:
  1. Verify .agent/workflows/ directory exists
  2. Check workflow files have correct frontmatter
  3. Load workflow manually first time
  4. Add workflow paths to agent config
Symptom: Git conflicts, lost changesSolution:
  1. Ensure Protocol 413 is loaded
  2. Use separate branches per agent
  3. Create agent_lock.json for coordination
  4. Never use git stash with multiple agents
Symptom: Can’t access files outside workspaceSolution:
  1. Enable non-workspace file access in IDE settings
  2. Check mount points in src/athena/boot/constants.py
  3. Verify filesystem permissions
  4. Use relative paths when possible

​
Best Practices

One Agent, One Branch

When using multiple agents, assign each to a dedicated branch to avoid conflicts.

Always Init First

Run athena init --ide <name> before first use to ensure proper configuration.

Verify Permissions

Check IDE has necessary permissions before expecting advanced features.

Test in Isolation

Test new IDE integrations in a clean directory before using in production.

​
Next Steps

Getting Started

Set up your first Athena workspace

Architecture

Understand the system design

Workflows

Learn about session management

Build docs developers (and LLMs) love

Get started for freeTalk to us