Argus Documentation

Table of Contents

Argus is a desktop monitoring and control center for Claude Code CLI instances. Named after Argus Panoptes, the hundred-eyed giant of Greek mythology, it gives you complete visibility and control over every Claude instance running on your machine.

Built with Python and pywebview, Argus reads Claude's session files in real-time and provides a rich GUI for monitoring, prompting, collaborating, and analyzing your AI workflow.

Getting Started

System Requirements

• •Windows 10/11 or macOS 12+
• •Claude Code CLI installed and in PATH
• •Python 3.10+ (only if running from source)

Installation

Windows

1. Download Argus-{tier}.exe from the releases page
2. Place it anywhere on your system
3. Run the executable — Argus auto-creates its data directory at ~/claude-monitor/

Mac

1. Download Argus-Mac.zip from releases
2. Unzip and move Argus.app to Applications
3. Launch from Applications

Support Scripts

1. Download Argus-Scripts.zip from the same release
2. Extract all .py files to ~/claude-monitor/
3. These scripts enable Task Queue signaling and inter-instance messaging

First Launch

When you first open Argus, it will:

• •Create ~/claude-monitor/ with default configuration
• •Automatically detect all running Claude Code instances
• •Display them as live cards on the Dashboard

No login, no account, no configuration needed. Just run it.

Tiers

Argus comes in four versions, each unlocking more capabilities:

Dashboard

The Dashboard is the home screen of Argus. Each running Claude instance appears as a live card that updates every 1.5 seconds.

Instance Cards

Each card displays:

• •Instance name (click to rename)
• •Current tool being used (Bash, Edit, Read, Grep, etc.) with color coding
• •Working directory path
• •Model (Opus, Sonnet, Haiku)
• •Cost accumulated in the session
• •Context window usage percentage with color bar
• •CPU usage percentage
• •Message count and subagent count
• •Last active timestamp
• •Uptime duration

Quick Prompt

Click the prompt icon on any card to open a quick prompt input. Type your message and press Enter — it's injected directly into that instance's terminal, even if that tab isn't focused.

Instance Management

• •Rename — Click the instance name to give it a custom label
• •Spawn — Click "Deploy Instance" to launch a new Claude in a fresh terminal window
• •Archive — Dead instances auto-archive after the configured retention period

Metrics SCOUT+

Deep per-instance analytics with an "All Instances" aggregate view.

Overview Metrics

• •Total cost with dollar formatting
• •Token usage — Input, output, cache read, cache create
• •Context window — Usage bar with color coding (blue < 50%, yellow < 80%, red > 80%)
• •Model identifier

Rate Limits

Real-time gauges showing:

• •Requests per minute (RPM) with limit
• •Input tokens per minute with limit
• •Output tokens per minute with limit

Tool Usage

Breakdown of every tool call count: Bash, Read, Edit, Write, Grep, Glob, Agent, WebSearch, etc.

File Activity

Lists of files edited, created, and read during the session.

All Instances View

Select "All Instances" to see aggregated totals across every active instance — combined cost, tokens, tool counts, and file lists.

Task Queue SCOUT+

Queue prompts for instances and manage execution order.

Creating Tasks

1. Click "+ Add Task"
2. Write your prompt in the text area
3. Select which instance to assign it to
4. Click "Add to Queue"

Task Lifecycle

• •Pending — Waiting to be sent
• •In Progress — Currently being executed
• •Completed — Successfully sent and processed
• •Failed — Send failed (instance offline, etc.)

Auto-Run

Tasks are sent to instances via direct console injection — no manual tab switching needed.

Task Signaling

Claude instances can signal task progress using argus_ping.py:

Sessions COMMAND+

Browse and inspect all Claude Code sessions.

Active Sessions

View every currently running session with:

• •Session ID, project directory, start time
• •Message count and current status
• •Click to expand and view conversation log

Archived Sessions

Browse past sessions with their summaries. Configure retention period in Settings.

History COMMAND+

Searchable log of every prompt sent through Claude Code.

Search

Filter prompts by keyword, date range, or instance. Results show the prompt text, timestamp, and which instance received it.

Analytics COMMAND+

Performance visualization and trend analysis.

Performance Graph

Interactive line chart with multiple views:

• •Per Message — Token usage, amplification ratio, tool count per message
• •Today (Hourly) — Activity breakdown by hour (local timezone)
• •7/14/30 Day — Daily trends over time

Features:

• •Mouse wheel to scroll through data
• •Hover over legend items to highlight individual metrics
• •Scrollbar indicator for large datasets

Deployment Markers

Add date markers (e.g., "Shipped v2.0") to track how changes affect performance over time.

Trend Interval

Configure in Settings — analyze metrics in windows of 10, 25, 50, or 100 messages.

Prompt Lab OMNISCIENT

A full GUI version of the Claude Code CLI with all options exposed visually.

Editor

Large monospace text area (JetBrains Mono) for composing prompts. Multi-line support with comfortable line height.

Model Selector

Switch between models with color-coded buttons:

• •Current — Keep the instance's current model
• •Opus — Orange accent
• •Sonnet — Sky blue accent
• •Haiku — Emerald accent

Selecting a model sends /model <name> to the instance before your prompt.

Effort Level

Control reasoning effort with a heat-scale selector:

• •Current — Keep current setting
• •Low — Gray (fast, minimal reasoning)
• •Medium — Yellow
• •High — Orange
• •Max — Red (deep reasoning, slower)

Sends /effort <level> before your prompt.

Send Modes

• •Send (blue) — Normal prompt execution
• •Plan (light blue toggle) — Activates /plan mode before sending
• •Edit (purple toggle) — Sends with auto-accept edit permissions

Slash Commands

All 74 Claude Code slash commands available in a library:

• •Quick bar shows your pinned commands — click to send directly to the instance
• •Library button opens the full command catalog
• •Click commands in the library to add/remove from your quick bar
• •Add custom commands via the input field

Recent Prompts

Last 20 prompts automatically saved. Click any to reload it into the editor.

Templates

Save frequently used prompts as named templates. Load with one click, delete when no longer needed.

Status Bar

Always-visible bar showing: selected instance, current model, effort level, and send mode.

Collaborate OMNISCIENT

Visual workspace for connecting and communicating between Claude instances.

Instance Graph

Interactive node graph where each running instance appears as a circle:

• •Green dot — Instance is alive
• •Color coding — Connected groups share a color
• •Click a node then click another to create/remove a connection
• •Drag nodes to rearrange the layout (positions persist)

Navigation Tools

• •V SELECT — Pointer mode for clicking and dragging nodes
• •H GRAB — Hand mode for panning the canvas
• •Keyboard shortcuts: V for pointer, H for hand

3000x3000 pannable dotted grid canvas.

Team Chat

Click "Open Chat" on a connected node to open the group chat panel:

• •Send messages to all connected instances at once
• •Use @InstanceName to target a specific instance
• •Messages are injected with [Collab with: ...] prefix

Connections

Connections are saved persistently. Only connections between online instances are displayed — offline instances and their connections are hidden automatically.

Ideas OMNISCIENT

Brainstorm ideas and send them to Claude instances for execution.

Creating Ideas

1. Click "+ Add Idea"
2. Write the idea description
3. Optionally add notes
4. Optionally assign to an instance
5. Click "Save Idea"

Executing Ideas

Click the Build button on any idea:

• •If an instance is assigned, it confirms then sends
• •If no instance is assigned, a picker modal appears
• •The idea text (+ notes) is injected as a prompt into the selected instance

Deleting Ideas

Click Delete — confirms with "Are you sure?" before removing.

Settings

Data Retention

Configure how long archived session data is kept (1 day to 1 year, or never delete).

Display

• •Dashboard refresh interval — 1s, 1.5s, 2s, 3s, or 5s

Analytics

• •Trend interval — Messages per analysis window (10, 25, 50, or 100)

Inter-Instance Communication

Shared Inbox

Instances can exchange messages and files using argus_inbox.py:

Messages are formatted as @sender -> @recipient: text so instances can see the full conversation context.

CLAUDE.md Setup

Add the inbox instructions to ~/.claude/CLAUDE.md so all Claude instances know how to use the messaging system. See the README for the full CLAUDE.md template.

Architecture

How It Works

Argus reads Claude Code's session files from ~/.claude/projects/*/sessions/*/ every 1.5 seconds. These JSON files contain:

• •Session metadata (model, cost, context usage)
• •Conversation messages and tool calls
• •Token usage and rate limit data

Console Injection

The core technology powering all prompt features. Argus uses the Windows kernel32 API:

1. AttachConsole(pid) — Attach to the target Claude process's console
2. CreateFileW("CONIN$") — Open the console input buffer
3. WriteConsoleInputW() — Write key events directly into the buffer
4. FreeConsole() — Detach

This sends text to any Claude terminal tab without needing window focus, tab switching, or clipboard manipulation. Each instance gets its own console buffer, so messages always reach the correct target.

Data Storage

All Argus data lives in ~/claude-monitor/:

• •Configuration: settings.json, instance_names.json
• •Features: task_queue.json, ideas.json, teams.json, prompt_lab.json
• •Analytics: analytics_cache.json, analytics_markers.json
• •Communication: shared_inbox.json, inbox/ directory

Tech Stack

• •Python 3.12 + pywebview (native desktop window with embedded web UI)
• •psutil for process monitoring
• •pyautogui + pyperclip for fallback input methods
• •pywin32 for Windows API access
• •PyInstaller for standalone executable packaging
• •Single file architecture: claude_monitor_gui.py (~315KB, ~6700 lines)

Keyboard Shortcuts

Troubleshooting

Argus doesn't detect my Claude instances

• •Ensure Claude Code CLI is installed and running (claude in your terminal)
• •Check that ~/.claude/projects/ exists and contains session directories
• •Restart Argus after starting Claude instances

Prompts aren't reaching the right instance

• •This uses direct console injection which targets processes by PID
• •If you restart a Claude instance, it gets a new PID — Argus detects this automatically
• •Ensure the target instance is alive (green dot on Dashboard)

Analytics shows wrong times

• •Argus converts all timestamps from UTC to your local timezone
• •If times still seem off, check your system clock settings

High CPU usage

• •Increase the refresh interval in Settings (default 1.5s, try 3s or 5s)
• •Close the Metrics tab when not actively monitoring — it does extra calculations

Version History