Guide

Quick Start

Five steps to attach; one more to gate CI. Heuristics work without login or an API key.

After setup

CLI Commands

All commands available from your terminal after installing ARGUS.

Setup

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

argus list

argus show last

argus fix <run-id>

argus show <run-id>

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

CI & testing

argus check last

argus check <run-id>

Exit code 0 when the run is clean; 1 on crash, silent failure, semantic fail, missing fields, or tool failures. Use after python my_agent.py in GitHub Actions or any CI job.

pytest --argus

Auto-wraps StateGraph.compile() for the test session. Clean pipelines stay passing tests; missing fields, tool failures, crashes, and semantic degradation fail that test. Tests that never invoke a graph are unchanged. Heuristics only (judge off).

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

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

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

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

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

Account & diagnostics

argus login

argus logout

argus whoami

argus doctor

argus update

AI Integration Prompt

After argus init, the skill already contains this AI setup prompt — asking your editor agent to wire ARGUS is enough. The copy below is just a fallback if you still want to paste a one-shot.

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 check last        # CI gate — exit 1 on crash / silent failure / semantic fail
  argus ui                # open the web dashboard (empty table = wrong dir or no runs yet)

For pytest, add --argus so silent failures fail the test (no ArgusWatcher in the test file required):
  pytest --argus

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

Table columns

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.

Metrics

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

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:

Compare

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

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.

From the CLI

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

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

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

Configuration Reference

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

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).

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.

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:

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