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, and adds it to your PATH. It does not touch any agent's config — you wire hooks from the dashboard in step 3. 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

Run argus start — it launches the local server and opens the dashboard at http://127.0.0.1:10804. argus stop shuts it down. Once you apply a preset (step 3), argus also auto-starts on your agent's next session.

bash

argus start          # launch the server + open the dashboard
argus stop           # stop the server

output

$ argus start
argus · http://127.0.0.1:10804
SQLite ready · dashboard serving · opening browser…

Wire your agent's hooks

Open the Hooks page, pick your agent — Claude Code, Codex, and 9 more are supported — and click Apply preset. Argus wires the hooks for you; every entry it adds is tagged and reversible. Prefer to do it by hand? Argus accepts any JSON payload via POST /api/hook:

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

# 1) Enable hooks in ~/.codex/config.toml
[features]
codex_hooks = true

# 2) Add to ~/.codex/hooks.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "curl -s --max-time 2 -X POST http://127.0.0.1:10804/api/hook -H 'Content-Type: application/json' -d @- || true",
        "timeout": 5
      }]
    }]
  }
}

# 3) Run codex, open /hooks, trust the new hashes

Watch events flow

The dashboard is already open at http://127.0.0.1:10804. 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 start

Uninstall

Stops the server, removes the argus SessionStart hook from ~/.claude/settings.json, strips ~/.argus/bin from your PATH, and deletes ~/.argus. This also deletes argus.db — back it up first if you want to keep your event history. Ingest hooks and non–Claude Code agents stay put; clear those from the Hooks page first.

bash

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ruydt/argus/main/uninstall.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ruydt/argus/main/uninstall.ps1 | iex

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

Auto-start only happens after you Apply a preset (step 3), which wires the argus-activate.js SessionStart hook. Until then, run argus start yourself.

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 ↗