loopscope.stub

---

id: loopscope name: loopscope repo_path: ~/Documents/sw30labs/repos/loopscope remote_url: https://github.com/sw30labs/loopscope.git primary_language: Python framework: FastAPI + uvicorn + websockets (LangGraph optional) category: agentic-frameworks stacks: [langgraph, agentic, cli] ingested: 2026-08-22 last_commit_date: 2026-08-21

loopscope

Purpose

A local live dashboard for LangGraph state graphs and Ralph loops — the retry-until-done pattern of plan / edit / test until a number reaches zero. loopscope runs inside the agent's own process, serves http://127.0.0.1:7788, and shows the run as it happens: which node is hot, how the graph is wired, whether this pass improved on the last, and a colour-coded feed of tools and models. One hook, no collector, no database, no accounts. v0.1.0b1, Apache-2.0.

The non-invasive contract

The repo's distinguishing stance is that observability must not be able to break the thing it observes:

• attach() publishes the topology and appends a callback handler to whatever LangChain config it is given — it does not rewrite the graph or wrap nodes.
• Forget the hook and the agent still runs; the dashboard just stays empty.
• raise_error = False on the handler, and publish() swallows its own exceptions, so a broken dashboard cannot take down the run.
• Installing the package is optional — the bundled examples add the repo root to sys.path.

Architecture

your code ──► EventBus ──► websocket ──► dashboard
              (ring buffer, thread-safe, optional JSONL)

• bus.py (197 lines) — thread-safe ring buffer, 4000 events, topology pinned and never evicted so a browser opening mid-run still draws the graph and recent history.
• server.py (213) — uvicorn on its own thread with its own event loop, so start() returns immediately and publishing is safe from any thread (sync .invoke() on main, an async app on its own loop, a worker pool).
• langgraph.py (736, the largest module) — callback handler and topology extraction.
• ralph.py (440) — RalphLoop, the @ralph decorator, phases, signals, stall detection.
• layout.py (283) — layering, cycle-breaking, hub detection, orbit placement and colour assignment computed in Python; the browser only draws coordinates.
• replay.py (87) — python -m loopscope.replay runs/tonight.jsonl --speed 8.
• static/dashboard.html — single-file frontend, no build step.

Ralph loop semantics

RalphLoop terminates on done(), max_iters, max_seconds, or stall — the driving signal failing to improve for stall_after passes, which the README names as the failure mode a Ralph loop actually has. it.done() sets a flag rather than raising, because an exception thrown in a for body never reaches the generator that yielded it and would skip the loop's own bookkeeping. A Ralph loop can also attach_graph(app) so an outer loop and an inner graph share one timeline.

Known measurement limits

Documented rather than hidden: node identity comes from metadata["langgraph_node"] filtered to runs tagged graph:step:N (without the filter, routers and chains inside a node double-count); edge traversal is inferred from execution order, exact for sequential graphs and approximate under parallel fan-out; state deltas are truncated for the wire (600 chars, 40 keys, 12 list items) with secret-shaped keys redacted — "for watching, not for auditing".

Dependencies

fastapi ≥0.110, uvicorn ≥0.27, websockets ≥12. Optional extras: langgraph (langgraph ≥0.2, langchain-core ≥0.3), dev (pytest ≥8). Python ≥3.10. Console script: loopscope-replay.

CI/CD

No CI workflows. 6 pytest modules under tests/ (bus, events, ralph, layout, replay+server, langgraph helpers); setup_and_run.sh builds a venv, runs the tests, then launches a demo (--langgraph, --combo, --help). Ships a loopscope-hook skill under skills/ for wiring it into an existing project from the editor.

Security posture

Loopback only, no auth — stated plainly as a 0.1 Beta limitation. Binding 0.0.0.0 prints a warning; the websocket accepts same-origin browsers and loopback clients only.

Entities and topics

• langgraph-checkpoints-vs-stores — the other runnable LangGraph reference here; both teach graph mechanics without LLM calls
• ralph-dgx — a Ralph goal loop driven from logs and exit codes; the obvious candidate to hook
• cleanroom — a four-agent LangGraph pipeline whose phases would render as a linear tape
• Tags: [python, langgraph, agentic, cli, fastapi, benchmark]