Guide

Dashboard walkthrough, integration setup, and configuration reference.

Quick Start

Get ARGUS monitoring on your pipeline in 5 steps. Heuristics work without login or an API key.

Install ARGUS — Run pip install argus-agents in your project. That ships the CLI, LangGraph adapter, and UI. The package name is argus-agents, not argus.

Write project skills — Run argus init. That writes Cursor and Claude skills at .cursor/skills/argus-debug/ and .claude/skills/argus-debug/. Commit them. The skill already contains the setup prompt — later chats can call ArgusWatcher.attach() and read .argus/runs JSON instead of guessing from logs.

Attach ARGUS — Ask your editor agent to wire ARGUS — after argus init that is enough. The AI Setup Prompt from the landing page (shown below) is a fallback. Happy path: ArgusWatcher.attach(graph) — heuristics on, judge off, no login, no TypedDict rewrite.

Click the AI Setup Prompt button on the landing page

Run your pipeline — Execute your LangGraph / LangChain pipeline as usual. ARGUS captures the run automatically. If something is wrong, a short [argus] finding prints in the terminal — clean runs stay silent. You do not need the dashboard for the first aha.

Inspect the run — Run argus show last in the terminal, or argus ui for the dashboard. The agent should read .argus/runs/<id>.json rather than guessing from terminal logs. If the dashboard table is empty, you opened it too early or from the wrong directory — the empty state shows which .argus/runs path is being served.

After setup

RUN PIPELINERun your LangGraph pipeline normally. A finding prints in the terminal when something is wrong; clean runs stay silent.

CHECK TERMINALargus show last — no browser needed. Then argus ui if you want the dashboard.

EMPTY DASHBOARDIf the table is empty, the UI is serving a different .argus or you opened it before the first run. Check cwd vs project root.

CLI Commands

All commands available from your terminal after installing ARGUS.

Setup

Write Cursor and Claude project skills

argus init

Writes .cursor/skills/argus-debug/SKILL.md and .claude/skills/argus-debug/SKILL.md. The skill already contains the setup prompt. Safe to re-run (skips unchanged files; pass --force to overwrite). Commit them so later chats can attach ARGUS and read .argus/runs JSON instead of guessing from logs.

Viewing runs

List all runs

argus list

Show the most recent run

argus show last

Show a specific run (full ID or 8-char prefix)

argus show <run-id>

Inspect raw input/output for a specific node

argus inspect <run-id> --step <node-name>

Dashboard

Open the web dashboard

argus ui

Starts a local server on port 7842 and opens the dashboard in your browser. Press Ctrl+C in the terminal to stop it. If the runs table is empty, ARGUS shows which .argus/runs path it is serving — run the graph first, try argus show last, or start the UI from the project root (cwd vs git / pyproject / $ARGUS_DIR).

Replay & compare

Replay from a specific node

argus replay <run-id> <node-name>

Replay with a graph factory

argus replay <run-id> <node-name> --app my_pipeline:build_graph

Replay just one node in isolation

argus replay <run-id> <node-name> --only

Diff two runs

argus diff <run-id-a> <run-id-b>

Account & diagnostics

Optional: hosted cloud sync (only if a hosted backend is configured)

argus login

Sign out and clear stored credentials

argus logout

Check current login status

argus whoami

Diagnose integration issues

argus doctor

Check for updates

argus update

AI Integration Prompt

This is the full prompt copied by the AI Setup Prompt button. After argus init, asking the editor agent to wire ARGUS is enough because the skill already contains the setup prompt. Paste this once only if you still want a one-shot wiring prompt (landing-page paste is a fallback, not required). It attaches ARGUS without rewriting your state types or node signatures.

prompt.txt

I want to add ARGUS monitoring to my LangGraph pipeline. Attach it with a small diff. Do not rewrite my state type or node signatures.

Heuristics, tool-failure scan, placeholders, empty outputs, and crashes work without TypedDict. Do not convert plain-dict state to TypedDict. Do not change node return shapes — returning {**state, ...} is fine. Type hints can be suggested after the first run; they are not a setup gate.

## STEP 1 — FIND THE GRAPH

Find the file where my StateGraph is defined (or the already-compiled app). Note whether nodes are sync or async. Linear, fan-out/fan-in, and cyclic graphs all persist automatically after the outermost invoke()/batch()/stream() returns — no finalize() call needed.

Print a short summary, then integrate. Do not "fix compatibility" by rewriting types first.

## STEP 2 — INTEGRATE ARGUS

Install: pip install argus-agents
(The PyPI package is argus-agents, not argus. Default install includes the CLI, LangGraph adapter, and UI. LLM judge is off by default — heuristics only. Optional later: argus key set, then pass semantic_judge=True.)

Also run: argus init
This writes project skills for Cursor and Claude:
  .cursor/skills/argus-debug/SKILL.md
  .claude/skills/argus-debug/SKILL.md
Commit them. Later chats will read .argus/runs JSON instead of guessing from logs.

Add ArgusWatcher to the file where the graph is built. Keep my existing state and node functions as-is:

from argus import ArgusWatcher

watcher = ArgusWatcher()
app = watcher.attach(graph)            # StateGraph OR already-compiled app
result = app.invoke(initial_state)     # run persists automatically
print(watcher.run_id)

If you prefer compiling yourself:

watcher = ArgusWatcher(graph)          # uncompiled StateGraph
app = graph.compile()
result = app.invoke(initial_state)

If node functions are async, use await app.ainvoke().

## STEP 3 — OPTIONAL CONFIG

Defaults are heuristics-first: semantic_judge is off. record_http and persist_state are on. Do not enable semantic_judge unless I already ran argus key set.

Only add extra kwargs if needed (redact_keys, validators, strict=True). Do not add a large config block by default.

After running the pipeline:
  argus show last         # first aha is in the terminal if something is wrong
  argus list              # see all recorded runs
  argus show <id>         # inspect a specific run by ID
  argus ui                # open the web dashboard (empty table = wrong dir or no runs yet)

After the first run, the dashboard may suggest type hints to catch field-drop bugs. That is optional follow-up, not part of this integration.

Runs List

Your pipeline execution history. Every run with ARGUS attached shows up here automatically. An empty table means this UI is reading a different .argus than the project that just ran, or you have not invoked the graph yet — use argus show lastand check cwd vs project root.

Summary cards

Total Runs

Pipeline executions recorded in your workspace.

Clean

Runs where every node passed.

Failed

Runs with at least one failure or crash.

Pass Rate

Clean runs as a percentage of total.

Table columns

RUN IDUnique identifier. Click to open the detail view.

STATUSOverall result: clean, silent failure, crashed, or semantic fail.

GRAPHNode execution path shown as a chain.

STEPSNumber of nodes that executed.

FIRST FAILUREFirst node that produced bad output — the likely root cause.

SHAPEWhether all expected nodes ran (full) or the run was cut short (partial).

The Evaluation panel lets you filter runs by constraints like overall_status == clean.

Run Detail

Full picture of a single pipeline execution — metrics, execution trace, AI analysis, and initial state.

Header

Run ID, status, timestamp, duration, step count, and ARGUS version.

Root Cause Chain

Traces failures back to the originating node, not the node that complained.

Metrics

Duration

Wall-clock time for the full run.

Success Rate

Percentage of nodes that passed.

Failures

Nodes with any failure status.

Severity

Worst level seen: ok, warning, or critical.

Completed

Whether the pipeline reached the final node.

Execution timeline

Nodes listed in execution order with name, output type, duration, and status. Failed nodes show a root cause annotation — which field was missing and which upstream node dropped it. Expand any row to see full I/O JSON.

Node statuses

PassNode executed successfully with no issues detected.

FailStructural problem — missing fields, tool errors, or silent failures.

CrashedNode threw an exception during execution.

Semantic failOutput passes structural checks but fails LLM quality review.

Degraded inputNode ran but received incomplete state from a failed upstream node.

SkippedNode was on an unchosen conditional branch — never activated. Shown as gray dashed boxes in the graph.

InterruptedExecution was interrupted (e.g. GraphInterrupt).

RetriedNode ran multiple times in a loop — earlier iterations marked retried when the final pass succeeded.

AI Analysis

When a provider key is set (OpenAI, Anthropic, or Google — via argus key set), ARGUS investigates non-clean runs automatically. The analysis panel has three sections:

Root Cause NodeThe node that first produced broken state.

ReasonWhy the node failed and how it propagated downstream.

How to FixNumbered action items targeting specific nodes.

Correlation

Confirms the true origin node with failure signals and a confidence score.

Behavior

Raw initial state your pipeline received — the exact input at invocation time.

Compare

Side-by-side diff of two runs. Useful for verifying fixes, catching regressions, or understanding performance differences.

Open Compare — Sidebar link, or the Compare button on any run detail page.

Enter two run IDs — Run A is typically the broken run, Run B is the fix.

Read the verdict — Winner banner shows which run performed better and why.

Read the node diff — Status in A vs B per node. Missing nodes labelled only in A / only in B.

Approvals

Gate deployments on ARGUS results. Runs that meet your criteria get approved; everything else is held for review.

Rerun

Re-execute from a specific node using the frozen input state from a previous run. Test a fix without re-running the full pipeline or making upstream LLM calls. Use record_http=True for fully deterministic reruns from disk.

Open the failing run — Click the run ID to open its detail page.

Find the root cause node — Red banner at the top names the originating node.

Click the rerun icon — Each node row has a rerun icon. Click it on the root cause node.

Wait for the new run — ARGUS re-executes from that node forward, creates a new run.

Compare to confirm — Diff the original against the rerun — broken nodes should now pass.

From the CLI

Rerun from a specific node

argus replay <run-id> <node-name>

With graph factory

argus replay <run-id> <node-name> --app my_pipeline:build_graph

Diff the results

argus diff <original-run-id> <rerun-run-id>

Configuration Reference

All ArgusWatcher parameters. Graph is the only positional argument — everything else is keyword-only.

ArgusWatcher(graph, **kwargs)

watcher = ArgusWatcher(
    graph,                  # uncompiled StateGraph — or omit and call attach()

    # --- Output control ---
    max_field_size=50_000,  # max chars per field before truncation (default: 50k)
    redact_keys={"token", "api_key"},  # field names to scrub from stored outputs
    persist_state=True,     # save run records to .argus/runs/ (default: True)

    # --- Detection strictness ---
    strict=True,            # extra checks: nested error keys, rate-limit responses,
                            # empty lists, type mismatches. recommended for CI/staging.

    # --- Semantic validators ---
    validators={
        "summarize": lambda o: (len(o.get("summary","")) > 10, "Summary too short"),
        "*": lambda o: ("error" not in o, "error key present"),  # runs on every node
    },

    # --- LLM investigation ---
    investigate=True,       # LLM root-cause analysis on failures (default: True)
                            # set to "always" for every node, False to disable

    # --- Deterministic rerun ---
    record_http=True,       # saves every outbound API call to disk. (default: True)
                            # reruns replay from disk — zero extra cost.

    # --- LLM semantic judge ---
    semantic_judge=True,    # LLM reviews every node's output for subtle quality issues.
                            # (default: False) opt in after 'argus key set'.
    judge_model="gpt-4o",  # tier hint: capable model. Auto-mapped to your active
                            # provider (Claude/Gemini). "gpt-4o-mini" = cheaper tier.

    # --- Latency thresholds ---
    config=ArgusConfig(
        node_timeout_ms=30_000,  # flag nodes that take >=95% of this (likely truncated)
        min_expected_ms=500,     # flag LLM nodes completing faster (likely cached/stale)
    ),
)

app = watcher.attach(graph)
result = app.invoke(initial_state)

Access watcher.run_id after the run. record_http,investigate, and persist_state default to True.semantic_judge defaults to False (heuristics-only until you opt in).

Use watcher.attach(graph) — one call for StateGraph or compiled apps. Runs persist when the outermost invoke() / batch() / stream() returns, including cyclic graphs.finalize() is an optional idempotent flush, not required.

record_http

Captures every HTTP request/response during the original run. On rerun, serves recorded responses back — same data, zero cost, fully reproducible.

Enable when nodes call paid APIs and you want cheap, identical reruns. Skip when you want the rerun to hit the real API.

semantic_judge

ARGUS catches ~80% of production failures deterministically — missing fields, empty results, type mismatches, placeholder outputs. The remaining ~20% are subtle: wrong tone, unhelpful responses, outdated info. The semantic judge covers those.

Deterministic firstStructural checks run first — free, instant, reproducible.

LLM secondJudge only reviews what structural checks couldn't decide.

Per-nodeEach output evaluated in context of its input and the pipeline's purpose.

Requires a provider key (OpenAI, Anthropic, or Google) — set via argus key set. Enable for complex multi-agent pipelines. Skip for simple pipelines or zero-cost monitoring.

Latency Thresholds

Detects timing-correlated degradation — no LLM calls, purely algorithmic. Pass thresholds via ArgusConfig:

Near timeoutnode_timeout_ms — flags nodes that take ≥95% of the timeout (likely truncated output).

Suspiciously fastmin_expected_ms — flags LLM nodes that complete too quickly (likely cached or stale).

Fast + failedCombines both: fast completion with existing quality issues = cached failure.

Both thresholds are optional and None by default — latency checks only run when configured.