Open source · MIT license · one-command install

The watchman whose
eyes never all close.

Argus is the hook control center for Claude Code and Codex — manage configs with one-click presets, test any hook in the simulator before an agent fires it, and install or publish guardrails through the community script registry. No cloud. Your machine, your SQLite file.

View on GitHubRead docs
curl -fsSL https://raw.githubusercontent.com/duytrandt04-afk/argus/main/install.sh | bash

Windows (PowerShell): irm https://raw.githubusercontent.com/duytrandt04-afk/argus/main/install.ps1 | iex

argus · event feedrec
14:02:09 ✓ SQLite ready ~/.argus/argus.db
14:02:09 ✓ SSE stream open :10804
14:02:09 ✓ Dashboard serving :10804
 
14:02:11 ▸ SessionStart claude-code · ~/work/api
14:02:14 ▸ PreToolUse Bash go test ./...
14:02:21 ▸ PostToolUse Bash exit 0 · 6.8s
14:02:24 ▸ PostToolUse Edit internal/handler/hook.go
14:02:30 ▸ Stop agent finished · 4 tools · 19s
 
watching

The three duties

Manage. Test. Ship.

01 · Manage

Hook management

One-click presets wire Claude Code or Codex hooks from the dashboard. Every argus-managed entry is tagged, additive, and reversible — no JSON surgery, no orphaned config.

See how presets work →

02 · Test

Hook simulator

Fire a realistic synthetic payload at any hook command and read stdout, stderr, exit code, and duration — before a live agent ever runs it. The missing debugger for the hook ecosystem.

Tour the simulator →

03 · Ship

Script collection

Battle-tested, zero-dependency guardrails, free for everyone — and a community registry built in: browse, one-click install, and publish your own scripts straight from the dashboard.

Browse the scripts →

The name

In the old story, Hera set a watchman over what she valued most: Argus Panoptes, a giant with a hundred eyes. Sleep never took all of them at once — some part of him was always watching. When his watch ended, she set his eyes into the peacock's tail, where they outlived him. A watcher whose record outlasts the watch: more or less the job description.

All of it stays on your machine. ~/.argus/argus.db

The instruments

Six instruments, one panel.

01 · Hooks

Manage and test hooks before agents run them

Presets, a structured editor, and the simulator — fire synthetic payloads at any hook command and read the result without waiting for a live session.

  • ▸ One-click presets, tagged and reversible
  • ▸ Synthetic payloads for every event type
  • ▸ stdout, stderr, exit code, duration
hooks — config & simulator
▸ PreToolUse ✓ active
▸ PostToolUse ✓ active
▸ Stop ✓ active
▸ Notification ○ inactive
 
── simulate ──
payload PreToolUse/Bash
exit 0 · 8ms · stdout {}

02 · Events

Every tool call, the moment it happens

A live feed of normalized events streamed over SSE — sub-100ms from hook to browser.

  • ▸ Filter by tool, agent, project, time
  • ▸ Expand any event to the raw payload
  • ▸ Permission allow/deny tracked separately
events — live feed
12:34:01 ▸ PreToolUse Bash
cmd: npm run test
12:34:02 ▸ PostToolUse Bash
exit: 0 duration: 1.2s
12:34:03 ▸ PostToolUse Write src/App.tsx
12:34:05 ▸ PostToolUse Edit src/index.css
12:34:09 ✓ Stop agent finished
 
$

03 · Sessions

Every session, per project

Each project lists its sessions in a table — duration, tokens, agent, timing. Click one to open its file-change drawer with the diffs.

  • ▸ Session, agent, duration, tokens, started, updated
  • ▸ Running sessions flagged live
  • ▸ File-change drawer with per-edit diffs
sessions — ~/projects/argus
session · agent · duration · tokens
 
a1b2c3d4e5f6 ● running claude-code 4m 12s · 18.4k
9f8e7d6c5b4a codex 2m 03s · 7.1k
3c2b1a0f9e8d claude-code 11m 38s · 42.0k
 
└ click a row → file-change drawer
▸ internal/handler/hook.go edit ×3
▸ src/index.css write ×1

04 · Dashboard

See how much your agents use

Token usage rolled up across sessions and charted over time and by model — computed locally, nothing leaves your machine.

  • ▸ Input / output / cache-read / cache-write breakdown
  • ▸ Usage over time and by model (Recharts)
  • ▸ Daily and weekly date ranges
dashboard — token usage
last 7 days
input 142,831
output 18,440
cache read 9,210
cache write 31,602
 
by model
claude-sonnet-4 ▇▇▇▇▇▇
codex ▇▇

05 · Projects

Every repo your agents touch

Project cards group sessions by working directory, searchable, with cascade delete when a project retires.

  • ▸ Session count, total tokens, and agents per project
  • ▸ Client-side search by name or path
  • ▸ Delete with full cascade
projects
~/work/api
42 sessions · 1.2M tokens · claude-code, codex
 
~/oss/argus
17 sessions · 480k tokens · claude-code
 
search: api

06 · Diagnostics

The instrument checks itself

Health, storage, hook-script inventory, and log tails — the watcher proves it is awake.

  • ▸ Backend, DB, and preset status
  • ▸ ~/.argus file system inventory
  • ▸ Compact the database to reclaim disk (payloads are gzip-stored; retention optional)
diagnostics
✓ backend healthy :10804
✓ db ~/.argus/argus.db · 12.4 MB
✓ hooks preset Medium (14/30)
✓ ~/.argus/hooks 6 scripts
 
log tail
argus.log · build.log · hook-scripts.log

Why this exists

  • 01Hook configs are hand-edited JSON — one typo and the guardrail silently never fires.
  • 02The only way to test a hook is to wait for a live agent to trip it. There is no debugger.
  • 03Good guardrail scripts exist — scattered across a thousand gists, unmaintained, untested.
  • 04Agents run for hours unobserved. You find out what they did from the git diff, after the fact.

Hooks are the control plane of coding agents. The control plane deserves an instrument.

03 · Install

Up and running in minutes

No accounts, no API keys, no build tools. One command installs the binary and wires your first hook — building from source is only for contributors.

bash
# One command — downloads the binary for your OS, wires the
# Claude Code SessionStart hook, installs to ~/.argus/bin

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/duytrandt04-afk/argus/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/duytrandt04-afk/argus/main/install.ps1 | iex

04 · Data handling

Private by default.

No telemetry

Zero analytics, zero tracking, zero phoning home. The binary never makes outbound connections.

Local SQLite

All events land in a single SQLite file on your machine. No external database, no SaaS.

You control exports

Export your event history anytime via the dashboard. Delete it anytime with rm.