Setup

Install guide

First event in under 10 minutes. No accounts. No API keys. No cloud.

Requirements● Node.js 18+● curl + tar (macOS / Linux)● macOS / Linux / WSL / Windows

Install with one command

The installer downloads a pre-built binary for your OS and architecture, places it at ~/.argus/bin/argus, adds it to your PATH, and wires the Claude Code SessionStart hook (which starts the server itself). No Go, no pnpm, no build step.

macOS / Linux

bash

curl -fsSL https://raw.githubusercontent.com/ruydt/argus/main/install.sh | bash

Windows (PowerShell)

powershell

irm https://raw.githubusercontent.com/ruydt/argus/main/install.ps1 | iex

Start argus

Open a new Claude Code or Codex session — argus starts automatically via the SessionStart hook. You will see:

session

SessionStart hook (completed)
  hook context: ARGUS live @ http://127.0.0.1:10804

Or start it manually:

bash

argus

Configure agent hooks

The installer wires Claude Code automatically; add more event types with one-click presets on the dashboard's Hooks Config page. For manual setup, Argus accepts any JSON payload via POST /api/hook — it auto-detects the agent from the transcript path.

Claude Code

~/.claude/settings.json

{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -s -X POST http://127.0.0.1:10804/api/hook -H 'Content-Type: application/json' -d @-"
      }]
    }],
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -s -X POST http://127.0.0.1:10804/api/hook -H 'Content-Type: application/json' -d @-"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "curl -s -X POST http://127.0.0.1:10804/api/hook -H 'Content-Type: application/json' -d @-"
      }]
    }]
  }
}

Codex

codex hooks

# In your Codex settings or AGENTS.md:
ARGUS_URL=http://127.0.0.1:10804/api/hook

# Add to codex hooks config:
{
  "postToolUse": "curl -s -X POST $ARGUS_URL -H 'Content-Type: application/json' -d @-"
}

Open the dashboard

Open http://localhost:10804 in your browser. Start an agent session — events should appear within milliseconds of the first tool call.

localhost:10804 — events

✓ SSE stream connected

── waiting for events ──

▸ PreToolUse Bash

▸ PostToolUse Bash exit:0

▸ PostToolUse Write src/App.tsx

✓ Stop agent finished

Verify (optional)

Test the endpoint directly with curl to confirm argus is accepting payloads before running a full agent session.

bash

# Check the backend is live
curl -fsS http://127.0.0.1:10804/api/version

# Send a test event manually
echo '{"type":"Stop","session_id":"test"}'   | curl -s -X POST http://127.0.0.1:10804/api/hook     -H 'Content-Type: application/json' -d @-

From source (contributors only)

Building from source needs Go 1.25+ and pnpm 10.x. make build-local compiles the frontend, embeds the SPA into the Go binary, and installs to ~/.argus/bin/. End users never need this.

bash

git clone https://github.com/ruydt/argus
cd argus
make build-local
~/.argus/bin/argus

Troubleshooting

Common issues

Port 10804 already in use

Set ADDR=:9000 (or any free port) before running argus. Update the curl commands in your hook config to match.

Installer fails — curl or tar not found

Install curl and tar with your system package manager, then re-run the install one-liner.

Events not appearing in the dashboard

Confirm argus is running and the curl in your hook config points to the correct port. Send a test payload manually (step 5).

Argus did not auto-start with my session

Check the SessionStart hook exists in ~/.claude/settings.json (it runs argus-activate.js, which starts the server). Or start manually by running argus.

Dashboard shows blank / no SSE connection

Hard-refresh the browser (Cmd+Shift+R). If on WSL, ensure localhost resolves to 127.0.0.1 in your browser.

Binary not found after install

Check ~/.argus/bin is in your PATH. Add: export PATH="$HOME/.argus/bin:$PATH" to your shell profile.

Explore the dashboard

See what the dashboard can show you once events start flowing.

View features GitHub ↗