Chrome DevTools for AI cognition. Watch AI agents think in real-time, inspect reasoning trees, replay traces offline, auto-trace OpenAI, LangChain, LangGraph, CrewAI, AutoGen, & LlamaIndex, and debug hallucinations inside VS Code with secure enterprise cloud synchronization.
Observe how Aether isolates cognitive branching, intercepting security violations. The active node glows with a strong pulsing rose flare, pausing playback to guide visual debugging:
# 1. Install our SDK & CLI runner
pip install aether-observe
# 2. Launch the offline Observatory Replay Visualizer
aether replay
# 3. Instrument your agent in 1 line
from aether import AgentTracer- What is Aether?
- Why Observability Matters
- Architecture Overview
- The Replay Engine & Graph Architecture
- VS Code Extension Platform
- SDK Quickstart
- Pricing & Plan Comparisons
- Onboarding Workflow
- OAuth Authentication Setup
- Trace JSON File Schema
- Integrations & CLI Tooling
- Security Guarantees
- Enterprise Architecture
- Troubleshooting & FAQ
Aether is a next-generation Local-First Cognition Debugger for AI Agents built to give developers complete, human-readable insights into agentic decision-making.
Just like traditional debuggers let you step through assembly or source code execution line-by-line, Aether enables you to scrub through agent thoughts, memory lookups, tool calls, and API responses on an interactive, time-synchronized graphical canvas.
Aether consists of:
- The Python SDK (
aether-observe): A low-overhead telemetry package that hooks into frameworks (LangChain, OpenAI) to capture agentic cycles. - The Next.js SaaS Web App (
Aether_Web): A cloud dashboard providing central organization, shared team workspaces, pricing management, and persistent trace databases. - The VS Code Extension (
aether-vscode): An IDE sidebar visualizer that connects seamlessly to the SaaS auth server, gates quotas dynamically, and renders beautiful carbon-dark replay timelines right next to active source code.
Debugging LLM chains and autonomous agents using plain console output (stdout) is incredibly painful:
- Non-Linear Thoughts: Autonomous agents branch out, retrieve context, hallucinate, recover, and spin up sub-agents. Flat textual logs cannot convey these multidimensional relationships.
- Telemetry Desync: Long-running loops lose historical tracing context, making it extremely hard to analyze where an agent deviated or hallucinated in a sequence of 50+ tool calls.
- Security Risks: Unmonitored agents may execute dangerous commands (like wildcard deletions). Observing and intercepting these branching decisions via visual guardrails is critical before shipping to production.
Aether solves this by converting textual traces into an explicit Directed Acyclic Graph (DAG) of agent cognition, ensuring absolute transparency.
Aether operates on a hybrid local-first with cloud-sync scaling model.
+--------------------------------------------+
| Target Agent Workflow |
+---------------------+----------------------+
| Writes Local Traces
v
+-------------+-------------+
| .aether/traces/*.json |
+-------------+-------------+
|
+-------------------+-------------------+
| |
v v
+--------+--------+ +--------+--------+
| VS Code Sidebar | | Aether SaaS |
| IDE Extension | <=================> | Cloud Platform |
| (Local/Cached) | OAuth & Sync | (Supabase RLS) |
+-----------------+ +-----------------+
- Local-First Isolation: By default, Aether stores telemetry files locally under
.aether/traces/as standard, compact JSON. If the user is offline, the system remains 100% functional. - Dynamic SaaS Coupling: When signed in, the VS Code extension queries the Aether SaaS API to fetch active subscription levels, synchronize trace databases safely to the cloud via Supabase RLS, and toggle advanced rendering elements.
Aether features a highly optimized React Flow DAG visualizer with custom shaders designed to illustrate how LLMs formulate trajectories:
- Node Categories:
thought(Cyan): The agent's raw internal rationale or planning step.tool_call(Gold): Execution hook of an external function (e.g. filesystem edits, web searches).tool_result(Emerald): The parsed response returned by the environment.memory(Purple): High-confidence semantic vector lookups retrieved from vector stores (Pinecone/pgvector).hallucination(Rose Red): Critical safety warnings triggered when execution deviates or violates guardrails.
- Visualizer Capabilities:
- Time-Synchronized Scrubber: A foot timeline slider to rewind, fast-forward, and single-step through nodes.
- Typewriter Stream: Side-by-side terminal log streaming token-by-token alongside active node selections.
- Trajectory Forking: Visually inspect the path taken during a self-correction branch versus the dangerous path originally calculated.
The VS Code extension transforms the IDE into a dedicated AI cockpit:
- Secure Auth Integration: Utilizes VS Code's native
SecretStorageAPI to store JWT and refresh tokens isolated within the operating system's Keychain (macOS Keychain, Windows Credential Manager, or Linux Keyring). - Deep-Link Integration: Supports standard custom protocols (
vscode://aether.aether-vscode/auth-callback) to sync browser-based web dashboard sessions instantly back to the editor. - Cinematic Sidebar: A premium carbon-dark sidebar showing signed-in user stats, real-time quota progress indicators, and an onboarding progress checklist.
# Move to vscode application workspace
cd apps/vscode
# Install dependencies
npm install
# Compile the typescript files
npm run compile
# Package the extension into a portable VSIX file
npx @vscode/vsce package --no-dependenciesThis generates aether-vscode-0.1.0.vsix in the directory, which can be installed in VS Code via Cmd + Shift + P -> "Extensions: Install from VSIX".
Create clean nodes programmatically using our Python context manager:
import time
from aether import AgentTracer
tracer = AgentTracer(project="custom-agent")
with tracer.session(session_id="agent-run-101", agent_name="SupportGPT") as session:
# 1. Start a reasoning block
t1 = session.thought("Analyzing user database lookup request...", confidence=0.98)
time.sleep(0.5)
# 2. Invoke database tool call
tc = session.tool_call(
tool_name="db_query",
args={"user_id": 9928},
parent_id=t1
)
time.sleep(0.3)
# 3. Inject tool output
session.tool_result(
tool_call_id=tc,
result={"email": "[email protected]", "plan": "enterprise"},
latency_ms=180
)Aether provides parameterless instrumentation. The SDK will automatically instantiate a thread-safe, local-first global tracer behind the scenes—no config hell, no databases, and zero setup nightmare:
from aether.integrations.openai import instrument_openai
import openai
# Magical 1-line parameterless setup
client = instrument_openai(openai.OpenAI())Aether offers four robust SaaS plans configured with clear visual and functional feature gates inside both the SaaS application and the VS Code webview sidebar:
| Feature Capability | Free Core | Pro Tier | Premium | Enterprise |
|---|---|---|---|---|
| Monthly Traces Quota | 25 Traces / mo | Unlimited | Unlimited | Unlimited |
| Telemetry History | 7 Days | Persistent | Unlimited | Customizable |
| Offline local replay | Yes | Yes | Yes | Yes |
| Cloud Sync & Share | ❌ None | ✔️ Unlimited | ✔️ Unlimited | ✔️ Private VPC / Air-Gapped |
| Visualizer Watermark | ❌ Disabled | ❌ Disabled | ❌ Disabled | |
| Advanced Graph Nodes | Basic | Advanced | Multi-Agent | ComplianceRBAC |
| Pricing Rate | $0 / mo | $29 / mo | $79 / mo | Custom Quote |
The Aether platform leads developers through a high-fidelity 6-step onboarding progression:
- Welcome Dashboard: Shows progress gauges detailing active SDK install states.
- Session Pairing: Instant click-to-sync button which deep-links the SaaS user state with the editor.
- Command Center: Quick one-click copy targets for the
pip installcommands. - SDK Setup: Ready-to-go Python quickstart scripts.
- First Cache Trace: Generating local traces inside
.aether/traces/on the local machine. - Interactive Exploration: Selecting the newly compiled cache row in the explorer side-pane to reveal full timeline control inside VS Code.
Aether routes session tokens through safe OAuth standard mechanisms.
+------------+ Open Browser +------------+
| VS Code | ========================> | Aether SaaS|
| Extension | | Dashboard |
+------------+ +-----+------+
^ |
| Redirect with Session JWT Tokens |
| (vscode://aether.aether-vscode/...) |
+----------------------------------------+
- Click "Connect Aether Account" in the sidebar.
- This directs the default browser to
http://localhost:3000/dashboardcontaining the authenticated web session. - Clicking "Sync Session with VS Code" issues a callback deep-link containing
accessToken,refreshToken,email, anduserIdpayload attributes. AetherUriHandlerinterceptor registers the credentials, synchronizes database checks dynamically, and unlocks the explorer state immediately.
Traces are serialized into portable JSON. Developers can share, store, and analyze these caches.
{
"events": [
{
"id": "node-101",
"sessionId": "agent-session-x",
"timestamp": "2026-05-20T12:00:00.000Z",
"type": "thought",
"parentId": null,
"content": "Synthesizing cluster deployment roadmap.",
"metadata": {
"confidence": 0.98,
"agentName": "ArchitectGPT"
}
},
{
"id": "node-102",
"sessionId": "agent-session-x",
"timestamp": "2026-05-20T12:00:01.000Z",
"type": "tool_call",
"parentId": "node-101",
"content": "Issuing pod list verification.",
"metadata": {
"toolName": "kubectl",
"command": "kubectl get pods"
}
}
]
}The PyPI package installs the universal aether binary:
- Doctor Diagnosis (
aether doctor): Scans folder system permissions, ensures directories are writable, and checks for port conflicts. - ASCII Summaries (
aether inspect [session_id]): Builds full colored hierarchy DAG paths directly inside terminal streams. - Performance Metrics (
aether summarize [session_id]): Renders latency distribution curves, total token metrics, and safety flags.
Aether values database isolation:
- Row Level Security (RLS): Row-level security is enforced at the core Supabase schema. Every sync write validates the
Authorization: Bearer <JWT>header, ensuring users can only read/write their own workspace records. - Zero-Plaintext Store: No passwords, access keys, or secrets are ever cached in raw text file databases. VS Code's
SecretStoragehandles absolute encryption natively.
Built for serious deployment requirements:
- Air-Gapped Operation: Run 100% offline with zero external network attempts.
- Auditing and Controls: Complete history retention, team workspace authorization roles, and customizable retention periods.
- Dedicated Deployments: Fully compatible with AWS VPCs, Google Cloud Kubernetes, and custom PostgreSQL/pgvector cluster stores.
Ensure your operating system supports deep-link association. If the link is blocked, run:
# Manual refresh in command line
aether refreshExplorerOr check if another VS Code instance has locked the handler socket.
By default, the replay server uses port 3000. If this is occupied, specify a custom port:
aether replay --port 8080Click the badge inside the profile header to open Aether's central subscription settings page directly.
Engineered for premium AI Reasoning Observability.