You built an AI agent. It runs 15 steps. Something breaks at step 9.
You have no idea why.
The LLM got a bad prompt? A tool returned garbage? A file permission failed silently? You add print() everywhere. You re-run it. You grep through 300 lines of logs. Forty minutes later, you find the bug.
This is the debugging dark age for AI agents. No step-by-step visibility. No tool call inspector. No way to see what the LLM was actually thinking at each decision point.
OpenJCK fixes this.
Two packages. One shared purpose.
pip install openjck ← instruments your Python agent
npx openjck ← opens the visual trace viewer
Step 1 — Instrument your agent (add 3 decorators, nothing else changes):
from openjck import trace, trace_llm, trace_tool
import ollama
@trace(name="research_agent")
def run_agent(task: str):
response = call_llm([{"role": "user", "content": task}])
results = web_search(response.message.content)
write_file("output.md", results)
@trace_llm
def call_llm(messages: list):
return ollama.chat(model="qwen2.5:7b", messages=messages)
@trace_tool
def web_search(query: str) -> str:
...Step 2 — Run your agent normally:
[OpenJCK] Run complete → COMPLETED
[OpenJCK] 8 steps | 2840 tokens | 4.2s
[OpenJCK] View trace → http://localhost:7823/trace/a3f9c1b2
Step 3 — Open the viewer:
npx openjckYou see this:
● ──── ● ──── ● ──── ● ──── ● ──── ● ──── ● ──── ✕
1 2 3 4 5 6 7 8
ERROR ↑
STEP 8 write_file [FAILED] 12ms
─────────────────────────────────────────────────
INPUT
path: "output.md"
content: "# Research Summary..."
ERROR
PermissionError: cannot write to output.md
File is open in another process
← Step 7: LLM decided to write the summary
→ Step 9: never reached
Bug found. Fixed in 30 seconds.
npx openjckOpen http://localhost:7823 to see:
- All agent runs — live as they happen
- Costs, success rate, avg duration at a glance
- Automatic root cause analysis on every failure
- Time filters: last 24h / 7 days / all time
When an agent run fails, OpenJCK automatically identifies the root cause:
- Which step made the run unrecoverable
- Why that step's output caused the downstream failure
- The last recovery point before the failure chain began
- Recurring failure patterns across multiple runs
No configuration. No API keys. Fires automatically on every failed run.
Your Agent Code
│
│ @trace / @trace_llm / @trace_tool (3 decorators)
▼
TraceCollector captures every event in-memory, per-thread
│
▼
~/.openjck/traces/ one JSON file per run — never leaves your machine
│
▼
Express server localhost:7823 (Node.js · npx openjck)
│
▼
Visual UI timeline + step inspector + token counts
Everything is local. No cloud. No accounts. No API keys. No data leaves your machine.
Both the Python library and the npm CLI read from the same folder — ~/.openjck/traces/. Run your agent from Python, view traces from any terminal with npx. Zero config between them.
npx openjck # start UI viewer (default)
npx openjck ui # start UI viewer
npx openjck traces # list all traces in terminal
npx openjck clear # delete all traces
npx openjck --version # show version
npx openjck --help # show helpGlobal install (optional — skip npx every time):
npm install -g openjck
openjck ui
openjck tracesWhat openjck traces looks like:
OpenJCK — Recorded Runs
ID Name Status Steps Duration Tokens
────────────────────────────────────────────────────────────────────────
a3f9c1b2 research_agent completed 8 4.20s 2840
9c4b1e3f failing_agent failed 6 2.41s 1345
✕ FileNotFoundError: File not found: config.txt
2 runs total · npx openjck ui to view in browser
| Field | Description |
|---|---|
| Full message history | Every message sent to the model |
| Model name | Which model + version was called |
| Response content | What the model replied |
| Tokens in / out | Prompt + completion token counts |
| Cost (USD) | Per-step cost based on model pricing |
| Latency | Execution time in ms |
| Error | Full traceback if the call failed |
| Field | Description |
|---|---|
| Function arguments | Exact values passed in |
| Return value | What the tool returned |
| Latency | Execution time in ms |
| Error | Full traceback including line number |
Marks the agent entry point. Starts a new trace for the entire run.
@trace # uses function name
@trace(name="my_agent") # explicit run name
@trace(name="agent", metadata={}) # attach custom metadata
@trace(auto_open=False) # don't auto-start UI serverSupports def and async def.
Wraps an LLM call. Captures prompt, response, tokens, model, latency, cost.
@trace_llm # auto-detects model from arguments
@trace_llm(model="gpt-4o") # explicit model labelAuto-detects token counts from Ollama, OpenAI, and Anthropic response formats.
Wraps a tool call. Captures input arguments, return value, and any exception.
@trace_tool # uses function name
@trace_tool(name="filesystem.write") # explicit name in the UIFor wrapping third-party code or dynamic dispatch:
from openjck import EventCapture
with EventCapture("tool_call", "database.query", input={"sql": query}) as cap:
result = db.execute(query)
cap.output = result.fetchall()
cap.metadata = {"rows": len(result)}from openjck import TraceStorage
traces = TraceStorage.list_all() # all trace summaries
trace = TraceStorage.load("a3f9c1b2") # full trace with all steps
TraceStorage.delete("a3f9c1b2") # remove one trace
TraceStorage.search(q="research", status="failed") # filter tracesOpenJCK is framework-agnostic. Wrap the functions. That's it.
# ✅ Raw Python agents
# ✅ LangChain
# ✅ LlamaIndex
# ✅ CrewAI
# ✅ AutoGen
# ✅ Smolagents
# ✅ Async agents (asyncio / anyio)
# ✅ Any custom agent loopimport openjck
openjck.patch_langchain() # instruments all LangChain LLM + tool calls
@trace(name="my_chain")
def run():
chain.invoke({"question": "..."}) # automatically traced@trace(name="crewai_research")
def run_crew(topic: str):
crew = Crew(agents=[researcher, writer], tasks=[...])
return crew.kickoff(inputs={"topic": topic})
@trace_tool(name="search.web")
def search_tool(query: str) -> str:
return SerperDevTool().run(query)@trace_llm
def call_llm(messages):
return ollama.chat(model="qwen2.5-coder:7b", messages=messages)All decorators work on async def with zero changes:
@trace(name="async_agent")
async def run_agent(task: str):
response = await call_llm(...)
result = await fetch_data(...)
@trace_llm
async def call_llm(messages):
return await async_client.chat(model="qwen2.5:7b", messages=messages)All traces are plain JSON at ~/.openjck/traces/<trace_id>.json.
~/.openjck/
└── traces/
├── a3f9c1b2.json # completed — 8 steps, 2840 tokens
├── 9c4b1e3f.json # failed — error at step 6
└── ...
Both the Python library and the npm CLI read and write to this same location. No sync needed.
pip install openjck # core library only
pip install "openjck[server]" # includes FastAPI UI server (alternative to npx)Requires: Python 3.10+
# No install — always runs latest:
npx openjck
# Or install once globally:
npm install -g openjckRequires: Node.js 18+
| OpenJCK | LangSmith | Helicone | Print statements | |
|---|---|---|---|---|
| Step-by-step visibility | ✅ | ✅ | ❌ | ❌ |
| Works with any framework | ✅ | ❌ | ✅ | ✅ |
| 100% local | ✅ | ❌ | ❌ | ✅ |
| Free forever | ✅ | Partial | Partial | ✅ |
| Visual UI | ✅ | ✅ | ✅ | ❌ |
| Token tracking | ✅ | ✅ | ✅ | ❌ |
| Cost tracking | ✅ | ✅ | ✅ | ❌ |
| Zero config | ✅ | ❌ | ❌ | ✅ |
OpenJCK is the only tool built specifically to debug agentic loops — the multi-step, tool-using, decision-making flows that break in ways traditional logging cannot explain.
New Features & Polish:
- Complete Dashboard UI rewrite (migrated from vanilla HTML to a modular React + Vite architecture).
- Deep aesthetic overhaul: Switched to a professional, flat dark-mode developer UI inspired by Vercel/Supabase.
- Hand-crafted CLI welcome banner (dropped figlet).
- Custom high-contrast scrollbars to replace clunky browser defaults.
- Overhauled timeline and detail mechanics for massive readability improvements of trace steps and JSON payloads.
New Features:
- Live dashboard with real-time updates at http://localhost:7823
- Agent drill-down view with patterns analysis
- Trace detail view with step timeline
- Failure Intelligence Engine — automatic root cause analysis
- Recovery point detection
- Dependency chain tracing
- SQLite database for persistent storage
- Non-blocking HTTP emit client
- SSE (Server-Sent Events) for live updates
- Mobile responsive design
- Time filters (24h, 7d, all)
- Dashboard documentation pages
Bug Fixes:
- Fixed intelligence endpoint subprocess handling
- Fixed FOREIGN KEY constraint on intelligence table
- Fixed version display inconsistencies
Python Package: openjck on PyPI
npm Package: openjck on npm
- Initial v0.2 release
- Initial release
- Core decorators:
@trace,@trace_llm,@trace_tool - JSON trace persistence
- Visual timeline UI
- Token/cost tracking
- npm CLI
v0.2.1 (completed)
- Live dashboard with real-time updates
- Failure Intelligence Engine
- SQLite database
- Agent drill-down view
- Trace detail view
- Mobile responsive design
v0.3.0 (current)
- Complete Dashboard UI rewrite (React + Vite)
- Hand-crafted CLI welcome banner
v0.4 (in development)
- Side-by-side run comparison
- Token waterfall chart
- CrewAI auto-instrumentation
- LlamaIndex auto-instrumentation
- CI/CD integration — fail build on regression
- VS Code extension
v1.0 (horizon)
- OpenJCK Cloud — share traces across your team
- Team dashboards + run history
- Slack / Discord alerts on agent failure
- Export trace as shareable HTML report
Built because debugging agents was making us insane.
git clone https://github.com/RavaniRoshan/openjck
cd openjck
# Python library
pip install -e ".[server]"
python examples/basic_agent.py # generates sample traces
# npm CLI
cd openjck-npm
npm install
node bin/openjck.js traces # verify traces from above
node bin/openjck.js ui # open UI at localhost:7823Before opening a PR:
- Open an issue first for non-trivial changes
- Add an example for new features
- Keep
collector.pyanddecorators.pydependency-free (stdlib only) - Keep
bin/openjck.jsworking without any build step
OpenJCK/
├── openjck/ ← Python library (pip install openjck)
│ ├── collector.py ← core event capture, thread-safe
│ ├── decorators.py ← @trace @trace_llm @trace_tool
│ ├── intelligence.py ← failure intelligence engine
│ ├── client.py ← HTTP emit client
│ ├── storage.py ← JSON persistence
│ ├── server.py ← FastAPI server (Python alternative)
│ ├── cli.py ← Python CLI entry point
│ └── ui/ ← web viewer UI
├── openjck-npm/ ← npm package (npx openjck)
│ ├── bin/openjck.js ← CLI entrypoint
│ ├── src/
│ │ ├── server.js ← Express server
│ │ ├── db.js ← SQLite database
│ │ ├── commands/ ← ui, traces, clear
│ │ └── ui/index.html ← dashboard UI
│ └── package.json
├── openjck-site/ ← docs site (Astro + Starlight)
├── examples/
│ ├── basic_agent.py ← demo agent
│ └── dashboard_demo.py ← dashboard demo
├── tests/
│ └── test_intelligence.py ← intelligence tests
└── README.md
MIT — use it, fork it, ship it.
If this saved you an hour of debugging — star the repo.
That's the only metric that matters right now.
Made with frustration and Python + Node.js · GitHub · npm · PyPI · Docs