A local-first, time-travel debugger and observability engine for multi-agent LLM systems.
fork • edit • replay
No account. No cloud fees. No vendor lock-in. Just SQLite on disk, a sleek local web UI, and instantaneous time-travel replays.
If you have built anything beyond a single-prompt toy, you've encountered this nightmare:
Your multi-agent loop fails on step 6 of 10. You add a
print()statement, re-run the entire pipeline, burn hundreds of thousands of tokens, wait 45 seconds, and... it succeeds this time because LLMs are stochastic.
Existing observability platforms (LangSmith, Phoenix, Langfuse) solve logging—you can see what went wrong after the fact. None of them solve interactive debugging:
- ❌ Re-running from scratch burns money and wastes time.
- ❌ SaaS observability platforms require sending private prompts, embeddings, and customer data to external cloud vendors.
- ❌ You cannot easily mutate the state at step 4 and test “what if the tool returned X instead?”.
Athar records every execution step (prompts, tool calls, tool results, state snapshots) into a local SQLite database using Write-Ahead Logging (WAL).
When an agent goes off track:
- Scrub through the execution timeline in the local web UI.
- Select the exact step where things went wrong.
- Mutate the prompt, tool output, or agent state in the inspector.
- Hit Replay: Athar resumes execution from that step forward. Prior steps are never re-executed, saving your API credits and minutes of wait time.
- Athar creates a new branch in the trace graph, letting you compare the original vs. mutated paths side-by-side.
Install via PyPI:
pip install atharOr install from source for development:
git clone https://github.com/Abdur-Rafay-AR/athar.git
cd athar
pip install -e ".[dev]"Wrap any agent or tool function with @traced:
import asyncio
from athar import traced, TracerContext
@traced
async def search_tool(query: str):
# Simulating a search tool or API lookup
await asyncio.sleep(0.2)
return {"results": f"Found latest data for: {query}"}
@traced
async def research_agent(topic: str):
print(f"Researching: {topic}")
data = await search_tool(topic)
return f"Synthesized report based on {data['results']}"
async def main():
# Bundle execution inside a named trace session
async with TracerContext(name="Market Intelligence Run"):
report = await research_agent("Autonomous Coding Agents")
print("Done:", report)
if __name__ == "__main__":
asyncio.run(main())Start the local server:
athar(Or run run-local.cmd on Windows).
Open http://localhost:4173 to scrub through steps, inspect inputs/outputs, and initiate time-travel replays!
flowchart TD
subgraph AgentApp["Your Agent Application"]
A["Agent Orchestrator"] --> B["Tool Calls & LLM Queries"]
end
subgraph AtharSDK["Athar SDK (Instrumentation)"]
T["@traced / TracerContext"]
H["SHA-256 Content Hasher"]
C["ContextVar Call Tree Tracker"]
end
subgraph Storage["Local Storage Layer"]
DB[("SQLite WAL Store\nagent_traces.db")]
end
subgraph WebUI["Athar Web UI (FastAPI)"]
UI["Interactive Timeline & DAG Inspector"]
FR["Fork & Replay State Mutator"]
end
AgentApp -->|wraps execution| AtharSDK
AtharSDK -->|async WAL writes| Storage
Storage <-->|reads & branches| WebUI
FR -.->|re-executes branch| AgentApp
- SQLite WAL Mode: Thread-safe, non-blocking concurrent writes from high-throughput agent loops while the Web UI live-polls data.
- Deterministic Content Hashing: Every step generates a SHA-256 fingerprint based on inputs, state, and function signatures.
- ContextVar Hierarchy Chaining: Automatically preserves parent-child relationships across nested agent calls and async tasks without messy manual span propagation.
- 🌿 Time-Travel Fork & Replay: Edit inputs or state snapshots at any node and live-execute real Python code without re-running earlier nodes.
- 🔬 Semantic Branch Diffing: Compare two execution branches side-by-side with
$\Delta\text{cost}$ ,$\Delta\text{latency}$ , and unified JSON/text diffs. - 🦜 Universal LangChain & LangGraph Support: Drop-in
AtharCallbackHandlerinstruments any chain or graph in one line of code. - 🔌 Native Framework Adapters: First-class adapters for LangChain, LangGraph, CrewAI, and the Crucible multi-agent engine.
- 🔒 100% Local & Private: No cloud credentials, zero telemetry, no external database dependencies. Your sensitive prompts and proprietary agent code never leave your machine.
- ⚡ Zero-Overhead Instrumentation: Drop-in
@traceddecorator andTracerContextcontext manager with negligible runtime impact. - 📊 Step Inspector: Real-time view of inputs, arguments, outputs, errors, latency, and cost per step.
- 🎨 Modern Dark-Mode UI: Built with a clean aesthetic, interactive timeline cards, live callable indicators, and branch comparison modal.
If you use LangChain, LangGraph, or CrewAI, instrument your application with zero code modifications:
from athar import AtharCallbackHandler
handler = AtharCallbackHandler(trace_name="Market Analysis Chain")
# Pass to any LangChain invocation:
chain.invoke({"topic": "AI Trends"}, config={"callbacks": [handler]})All chain steps, tool invocations, prompts, and token usages are automatically streamed into Athar.
# Launch Athar UI on default port 4173
athar
# Launch on custom port and host
athar --port 8080 --host 0.0.0.0
# Point to a custom SQLite database file
athar --db ./path/to/my_traces.dbWe welcome contributions! Run the automated test suite with Python's built-in unittest or pytest:
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
python -m unittest discover -s testsSee CONTRIBUTING.md for details on development workflows, adapters, and style guidelines.
- v0.1: Local-first tracer SDK, SQLite WAL store, FastAPI server, interactive timeline UI, dynamic replay runtime.
- v0.2: Side-by-side branch diff visualizer (compare outputs, cost differences, and token latency between two forks).
- v0.3: Universal LangChain & LangGraph callback adapter (
AtharCallbackHandler). - v0.4: Live trace streaming via WebSockets / Server-Sent Events (SSE).
- v1.0: Stable SDK API, export traces to OpenTelemetry, and team sharing utilities.
Athar (أثر) is an Arabic word meaning trace, imprint, or footprint. In agentic AI systems, understanding the exact trace left behind by an agent's reasoning process is the key to mastering reliability, interpretability, and deterministic debugging.
Distributed under the MIT License. Copyright © 2026 Abdur Rafay.