Athena MCP server
Commit Nov 11, 2026An autonomous multi-agent AI framework that performs local terminal execution, browser automation, and filesystem management with persistent memory.
Also known as RAGHUTTAMA-DEV/Athena
- Stars
- 2
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- —
What is Athena MCP?
Athena is an autonomous multi-agent AI framework that performs local terminal execution, browser automation, and filesystem management with persistent memory. It exposes 6 tools, such as global, user, workspace.
Summary generated from the project's README
About Athena MCP server
Developers seeking an autonomous agent for local machine tasks can use Athena to manage files, execute terminal commands, and automate web browsers. This TypeScript-based system operates directly within your local environment, providing hands-on access to your filesystem, a Python sandbox for data processing, and a Playwright-driven Chromium instance for live DOM interaction. It is designed for long-running, complex workflows that require reliability through SQLite-backed checkpoints and hierarchical run state tracking.
Users interact with the system via an interactive CLI or through MCP integration. The framework manages complexity by decomposing difficult requests into a Plan DAG and utilizes a multi-scope memory model to track information across global, workspace, and project levels. Security is a core focus, featuring a policy engine, prompt injection defense, and circuit breakers to protect against failing tool runtimes or unintended destructive commands.
What you can do with it
- 1Automated web interaction and data captureAn AI client can use the browser tools to navigate websites, click elements, and take screenshots.
- 2Resuming interrupted long-running tasksYou can stop a complex execution and restart it later from the exact point it left off.
Written from the project's README. Every use case is checked against a quote from it.
Athena MCP tools 6
Detected from the READMEglobaluserworkspaceprojectsessiontask
Configuration
ATHENA_ALLOW_ALLATHENA_WORKER_CONCURRENCYDATABASE_PATHGEMINI_API_KEYGEMINI_MODELLANGFUSE_HOSTLANGFUSE_PUBLIC_KEYLANGFUSE_SECRET_KEYLLM_PROVIDERMAX_TURNSNVIDIA_API_KEYNVIDIA_BASE_URLNVIDIA_MODELTELEGRAM_BOT_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableraghuttama-dev/athena is public and reachablegithub.com/raghuttama-dev/athena ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-11github.com/raghuttama-dev/athena ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub🏛️ Athena: Autonomous Multi-Tool AI Agent System
Athena is a production-grade, local-first autonomous AI agent system engineered in TypeScript. Designed for reliability, safety, and long-running execution, Athena pairs local machine access (terminal, filesystem, browser automation, Python sandbox) with adaptive multi-phase orchestration, hierarchical run state and recovery, multi-scope persistent memory, circuit-breaker-protected tool runtimes, dedicated coding harness bridge, durable background event scheduling, multi-layered security and prompt defense, and deep OpenTelemetry/Langfuse observability with trajectory replay debugging.
📹 Demo
🎬 Watch Athena in Action:
📋 Table of Contents
- 📹 Demo
- 💡 Core Philosophy
- 🚀 Architecture Phases (Phases 1–8 Implemented)
- ✨ Key Features & Capabilities
- 1. Agent Runtime & Durable Execution (Phase 1)
- 2. Context Engine & Multi-Scope Memory (Phase 2)
- 3. Resilient Tool Runtime (Phase 3)
- 4. Adaptive Orchestration & Self-Repair (Phase 4)
- 5. Coding Harness Integration (Phase 5)
- 6. Background Event Runtime & Worker Pool (Phase 6)
- 7. Reliability, Security & Policy Engine (Phase 7)
- 8. Observability, Telemetry & Replay Debugger (Phase 8)
- 9. Model Context Protocol (MCP) Integration
- 🛠️ Comprehensive Built-in Toolset
- 🏗️ System Architecture & Structure
- ⚡ Quick Start & Getting Started
- 🧠 Multi-LLM Provider Architecture
- 🔌 Model Context Protocol (MCP) Setup & Configuration
- 💻 Usage & CLI Commands
- 🧪 Manual Feature Test Prompts
- 📊 Evaluation & Benchmark Suite
- 🧪 Test Suite & Verification Commands
- 📜 License
💡 Core Philosophy
💻 1. Local-First Machine Native Access
Athena runs directly on your local developer environment with hands-on capabilities:
- Local Terminal Execution: Runs shell commands, scripts, git workflows, and system tools via
terminal. - Direct Filesystem Management: Inspects, reads, writes, and surgical-edits workspace files (
readFile,filesystem,replaceFileContent,grepSearch). - Python Sandbox: Executes local Python code for analytics, math, and data processing (
executePython). - Interactive Headless Browser: Automates Chromium via Playwright for live DOM interaction, element clicking/typing, and screenshot capture (
browser,browserNavigate,browserAction,browserScreenshot).
🌱 2. Adaptive Complexity & Resilience First
Athena prioritizes reliability and recoverability over raw token counts:
- Adaptive Orchestration: Simple requests use a fast direct tool loop with zero planning token overhead. Complex requests automatically decompose into a Plan DAG, run acceptance verifications, and trigger self-repair loops.
- Cooperative Cancellation & Run Resumption: Any long-running task can be interrupted cleanly via
Ctrl+Cand resumed later from SQLite checkpoints using/resume <runId>. - Deep Security Guardrails: Dual-boundary prompt injection defense, recursive secret redacting, and a centralized policy engine prevent unintended access to sensitive files or destructive shell commands.
- Continuous Self-Evolution: Dynamic procedural skill learning (
skills/) and multi-scope episodic memory allow Athena to grow alongside you.
🚀 Architecture Phases (Phases 1–8 Implemented)
Athena is engineered as a multi-tier modular architecture across 8 fully implemented and verified phases:
┌────────────────────────────────────────────────────────────────────────┐
│ Athena Autonomous Runtime │
└──────────────────────────────────┬─────────────────────────────────────┘
│
┌─────────────────────────────────┴─────────────────────────────────┐
│ Phase 1: Authoritative RunState, Budgets & Resumption │
├───────────────────────────────────────────────────────────────────┤
│ Phase 2: ContextEngine, Multi-Scope Memory & Contradiction Logic │
├───────────────────────────────────────────────────────────────────┤
│ Phase 3: Resilient ToolRuntime, Circuit Breakers & Offloading │
├───────────────────────────────────────────────────────────────────┤
│ Phase 4: Adaptive Orchestrator, TaskClassifier & Self-Repair DAG │
├───────────────────────────────────────────────────────────────────┤
│ Phase 5: Coding Harness Bridge, Git Snapshots & Acceptance Gate │
├───────────────────────────────────────────────────────────────────┤
│ Phase 6: Scheduler (Timezones), EventBus & Priority WorkerPool │
├───────────────────────────────────────────────────────────────────┤
│ Phase 7: PolicyEngine, PromptDefense & Credential Isolation │
├───────────────────────────────────────────────────────────────────┤
│ Phase 8: Telemetry Alignment, Replay Debugger & Adversarial Suite │
└───────────────────────────────────────────────────────────────────┘
✨ Key Features & Capabilities
1. Agent Runtime & Durable Execution (Phase 1)
- Authoritative
RunStateModel: Explicit lifecycle tracking (queued➔running➔waiting➔verifying➔completed/failed/cancelled) persisted transactionally to SQLite (runsandrun_events). - Sub-Agent Run Tree Hierarchy: Explicit parentage tracking with
runId,parentRunId, androotRunIdacross nested delegation trees. - Typed
AgentEventStream: Real-time event emission for status transitions, turns, thoughts, tool executions, sub-agent spawning, plan updates, and budget alerts viaAgentEventEmitter. - Cooperative Cancellation:
CancellationTokenSourcecreates hierarchical cancellation tokens that cleanly abort LLM generation, child processes, sub-agents, and tools onCtrl+C. - Interrupted Run Resumption: Resume paused, failed, or interrupted runs with full turn history and state via
/resume <runId>andagent.resumeRun(runId). - Multi-Resource Budget Engine: Bounded execution with strict limits on
maxTimeMs,maxTokens,maxCostUsd,maxToolCalls,maxTurns, and child sub-agent allocations. - Idempotency Tagging: Side-effect tool calls generate unique idempotency keys to prevent accidental duplicate actions upon retry.
2. Context Engine & Multi-Scope Memory (Phase 2)
- Unified Context Pipeline:
ContextEnginedynamically budgets and synthesizes system prompt instructions, workspace state, relevant scoped memory, and active conversation history within model token limits. - Multi-Scope Memory Model:
global: Universal knowledge and user preferences across all projects.user: User-specific metadata, contact info, and constraints.workspace: Working directory facts, repo layout, and tooling conventions.project: Project goals, milestones, and architectural decisions.session: Current conversation thread history.task: Ephemeral context dedicated to an active sub-task.
- Memory Provenance & Confidence: Every memory record tracks origin
runId, source type (user message / tool execution / subagent finding), timestamp, and calibrated confidence score (0.0 to 1.0). - Contradiction Resolution & Lifecycle: Full lifecycle tracking (
active➔confirmed➔contradicted➔superseded➔deleted) with bidirectionalsupersededByandsupersedespointers when new facts invalidate older ones. - User Memory Controls: Interactive CLI commands (
/memory inspect,/memory scopes,/memory forget <id>,/memory purge <scope>). - Skill Registry Intelligence: Tracks procedural skill versions, invocation counts, and success rates in SQLite.
3. Resilient Tool Runtime (Phase 3)
- Standardized
ToolResult<T>Envelope: Unified return structure across all tools:interface ToolResult<T> { success: boolean; data?: T; error?: { code: string; message: string }; retryable: boolean; metadata?: Record<string, any>; } - Tool Manifests: Every tool declares permissions (
fs:read,fs:write,cmd:exec,browser,memory,system), risk levels (safe,confirm,destructive), timeout policies, andparallelSafeconcurrency flags. - Central Timeout Policies: Fine-grained per-tool execution timeouts (5s math, 15s search, 45s browser, 60s terminal) with cooperative cancellation tokens.
- Circuit Breaker Registry: Protects against flaky MCP servers or failing remote APIs with automatic state transitions (
closed➔open➔half-open➔closed), failure thresholds, and recovery cooldowns. - Semantic Schema Validation: Validates parameter types and required fields against JSON Schema definitions prior to tool invocation.
- Large Output Offloading: Payloads exceeding 16KB are automatically offloaded to disk artifacts (
scratch/artifacts/), returning structured preview envelopes with artifact paths to avoid blowing out model context windows. - Dynamic Tool Pruning (
ToolSelector): Intent-based filter that dynamically prunes 20+ registered tools down to relevant subsets for the current turn.
4. Adaptive Orchestration & Self-Repair (Phase 4)
- Task Complexity Classification: Zero-token-overhead heuristic router (
TaskClassifier) assigning complexity classes:simple: Direct tool loop with zero planning overhead.medium: Standard loop with state checkpointing and focused context.complex: Formal DAG decomposition and dependency scheduling.high_risk: Mandatory verification gate and human-in-the-loop confirmation.
- Plan DAG Engine: Decomposes complex tasks into directed acyclic step graphs (
PlanDAG,PlanStep) with dependency resolution and step-level status tracking. - Dynamic Escalation Engine: Automatically escalates execution mode (
simple➔medium➔complex) upon detecting repeated tool failures or lack of convergence. - Verification Gate: Evaluates task completion against acceptance criteria, scoring responses and flagging defects.
- Self-Repair Diagnostic Loop: Re-prompts the model with structured diagnostic feedback when verification checks flag missing requirements or broken tests.
5. Coding Harness Integration (Phase 5)
- Zero-Duplicate Architecture: Athena orchestrates complex repository modifications via an external Coding Harness process bridge (
CodingHarnessBridge) without duplicating sandbox or git logic. - Typed Communication Protocol:
CodingTaskRequest:{ runId, task, cwd, traceId, maxIterations, timeoutSec, constraints, autoSnapshot }CodingTaskResult:{ status, summary, filesChanged, testsPassed, diff, checkpointId, stdout, stderr, error, durationMs }
- Shared Trace & Run ID: Propagates Athena
runIdvia--trace-idfor end-to-end telemetry correlation. - Live Event Streaming: Streams child process thoughts, tool calls, and test runs directly into Athena's terminal UI and event stream.
- Repository Intelligence (
inspectRepo): Auto-detects package managers (npm,yarn,pnpm,bun,pip,cargo), test runners, and git branch status. - Git Snapshots & Automatic Rollback: Automatically creates pre-execution git snapshots and rolls back workspace state if verification tests fail.
- Coding Acceptance Gate: Verifies exit status, changed file paths, and test execution outcomes before declaring success.
6. Background Event Runtime & Worker Pool (Phase 6)
- Durable Task Scheduler: Persistent cron and timer engine stored in SQLite that survives system restarts (
Scheduler). - Full IANA Timezone Support: Schedule jobs with complete timezone awareness (
America/New_York,Asia/Kolkata,UTC, etc.) using nativeIntl.DateTimeFormat. - Atomic Job Leases / Distributed Locks: SQLite-backed lease manager (
JobLeaseManager) with auto-heartbeat renewal and stale lease takeover, preventing duplicate executions across worker processes. - Decoupled Event Bus (
EventBus): Wildcard topic subscription (*,timer:*,webhook:*) with sliding-window idempotency deduplication and an audit trail inevent_log. - Priority Worker Pool (
WorkerPool): Asynchronous task runner with configurable concurrency (ATHENA_WORKER_CONCURRENCY) and priority queues (critical>high>normal>low).
7. Reliability, Security & Policy Engine (Phase 7)
- Central Policy Engine (
PolicyEngine): Rule-based security gatekeeper:- Blocks access to sensitive paths (
.env,id_rsa,.ssh/,credentials.json,client_secret*.json). - Enforces workspace boundaries against directory traversal (
../). - Restricts destructive commands (
rm -rf /,del /s /q C:\, fork bombs, drive formatting).
- Blocks access to sensitive paths (
- Prompt-Injection Dual-Boundary Defense (
PromptDefense):- Disarms instruction overrides, jailbreaks, and delimiter escapes.
- Sanitizes and isolates external web pages, emails, and external files inside strict
<untrusted_content>tags.
- Recursive Credential Redaction (
CredentialManager): Automatically detects and redacts secrets (Gemini, OpenAI, NVIDIA, Telegram, AWS, GitHub tokens, Bearer tokens) across all tool outputs, trace spans, and histories. - Multi-Provider Fallback: Automatic failover (e.g., Gemini ➔ NVIDIA NIM / OpenAI) on HTTP 429 rate limits, 500/503 outages, or connection resets with primary cooldown circuit breaker.
- Structured Failure Taxonomy & Recovery: Tailored backoff, retry, and recovery strategies for
rate_limit,provider_outage,network_reset,timeout,auth, andpolicy_violation.
8. Observability, Telemetry & Replay Debugger (Phase 8)
- OpenTelemetry & Langfuse Trace Alignment: Unified trace and span hierarchies linking Athena Core, child sub-agents, Coding Harness processes, and background workers into a single observability tree.
- Trajectory Replay Debugger (
TrajectoryReplayer):- Replay past run trajectories step-by-step from persisted events.
- Inspect timestamps, tool invocations, success/failure counts, and execution latency.
- Trajectory diffing (
/replay <runId> --diff <otherRunId>) to detect divergence between runs. - Markdown post-mortem export (
/replay <runId> --export <path>).
- Adversarial Security Evaluation Suite: Built-in benchmark harness (
npm run eval:adversarial) evaluating resilience against prompt injection, memory poisoning, directory traversal, and unauthorized tool invocation with defense scorecards.
9. Model Context Protocol (MCP) Integration
- Connects external tool servers (Gmail, Notion, Slack, GitHub, Postgres, Filesystem, Brave Search) seamlessly via
stdio,sse,http, orstreamable-http. - Automatic Gemini schema sanitization (
cleanGeminiSchema) converts raw JSON schemas into compliant function declarations. - Server-namespaced tool registration (e.g.
[MCP: filesystem]).
🛠️ Comprehensive Built-in Toolset
| Tool | Category | Description | Permissions | Risk Level |
|---|---|---|---|---|
delegate_task |
Orchestration | Spawns an isolated sub-agent with scoped tools, budget cap, and depth guards | system |
safe |
delegateCodingTask |
Coding | Delegates repository coding tasks to the Coding Harness with git snapshots and rollback | cmd:exec, system |
confirm |
browser |
Web | Headless Chromium web browsing, text extraction, and page navigation | browser |
safe |
browserNavigate |
Web | Interactive browser navigation to URLs | browser |
safe |
browserAction |
Web | Interactive browser DOM action (click, type, press, scroll) using element IDs | browser |
safe |
browserScreenshot |
Web | Captures full or viewport screenshots of web pages for visual verification | browser |
safe |
searchWeb |
Search | Live web search powered by DuckDuckGo and Yahoo fallback | browser |
safe |
terminal |
System | Shell command execution with timeout policies, maxBuffer, and cwd control | cmd:exec |
confirm |
writeFile |
Filesystem | Writes or overwrites file contents on the local filesystem | fs:write |
confirm |
deleteFile |
Filesystem | Deletes a file on the local filesystem | fs:write |
confirm |
listFiles |
Filesystem | Lists files and directories with depth limits and hidden file filters | fs:read |
safe |
replaceFileContent |
Filesystem | Surgical search-and-replace for existing files without whole-file rewrites | fs:write |
safe |
grepSearch |
Filesystem | Fast recursive regex codebase search with line numbers and file filters | fs:read |
safe |
readFile |
Filesystem | Reads file contents with line slicing (startLine, endLine) and output offloading |
fs:read |
safe |
executePython |
Execution | Executes Python code in a local subprocess sandbox | cmd:exec |
confirm |
calculate |
Utility | Mathematical expression evaluation | system |
safe |
cronjob |
Scheduler | Persistent scheduled tasks with IANA timezones, priorities, and one-shot/cron triggers | system |
safe |
skillManage |
Learning | Creates, lists, reads, and edits reusable procedural skills in skills/ |
fs:write, fs:read |
safe |
semanticMemory |
Memory | Queries, updates, reinforces, or resolves scoped memories across scopes | memory |
safe |
systemTime |
Utility | Returns current machine date, time, and timezone | system |
safe |
| Dynamic MCP Tools | Dynamic | Discovered dynamically from declared servers in mcp_servers.json |
Dynamic | Dynamic |
🏗️ System Architecture & Structure
📐 System Architecture Diagram

Athena MCP questions
What tools does Athena MCP provide?
It exposes 6 tools, including global, user, workspace, project, session.
What kind of local access does Athena have?
Athena can execute shell commands via terminal, manage the filesystem, run Python code in a sandbox, and automate browsers using Playwright.
Can I resume a task that was interrupted?
Yes, you can resume paused, failed, or interrupted runs using the /resume command with a specific run ID.
Does it support MCP?
Yes, Athena includes Model Context Protocol integration with support for various transport modes.