Client Detection & Setup¶

lumen-argus can automatically detect which AI coding tools are installed on your machine, check whether they're configured to route through the proxy, and set them up in one command.

Overview¶

The detection and setup workflow has three layers:

Detect — read-only scan that finds installed tools and checks proxy status
Setup — interactive (or non-interactive) wizard that configures tools
Watch — background daemon that detects newly installed tools over time

All three share the same detection engine and client registry of 27 supported agents.

Detecting Installed Tools¶

lumen-argus detect

This scans your system using 8 detection layers (in priority order):

Layer	What it checks	Example
Binary	`shutil.which()` for CLI tools	`claude`, `aider`, `codex`
pip	`importlib.metadata` (no subprocess)	`aider-chat`
npm	Global `node_modules/package.json`	`@anthropic-ai/claude-code`
Homebrew	Cellar directory (macOS)	`aider` formula
VS Code extensions	8 IDE variants (VS Code, Insiders, VSCodium, Cursor, Windsurf, Kiro, Trae, Antigravity)	`github.copilot`
macOS app bundles	`/Applications/*.app` with Info.plist version	`Cursor.app`
JetBrains plugins	Product plugin directories	`github-copilot-intellij`
Neovim plugins	lazy.nvim, vim-plug, native pack directories	`copilot.vim`

First match wins — if a tool is found as a binary, later layers are skipped for that tool.

Output modes¶

StandardAuditJSONVersionsMCP Servers

lumen-argus detect

Detected AI tools (3):

  [+] Claude Code                 binary     proxied
  [-] Aider           0.50.1      pip        not configured
  [+] GitHub Copilot  1.200.0     vscode_ext proxied

2/3 configured for proxy (http://localhost:8080)
Run 'lumen-argus-agent setup' to configure remaining tools.

lumen-argus detect --audit

AI Tool Proxy Compliance Audit:

  [OK]   Claude Code           Proxied (~/.zshrc:42)
  [FAIL] Aider          0.50.1 NOT PROXIED — OPENAI_BASE_URL not configured
  [OK]   GitHub Copilot 1.200.0 Proxied (settings.json)

Summary: 2/3 tools routed through proxy
Action required: run 'lumen-argus-agent setup' to configure uncovered tools.

lumen-argus detect --json

Full JSON output suitable for CI pipelines and automation scripts.

lumen-argus detect --versions

Runs --version subprocesses for CLI tools and reads Info.plist for app bundles. Slower but gives exact version numbers.

lumen-argus detect --mcp

Discovers MCP servers from 8 AI tools plus Claude Code plugins:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code — ~/.claude.json (user-configured servers), ~/.claude/settings.json, .mcp.json (project)
Claude Code plugins — reads ~/.claude/plugins/installed_plugins.json, only enabled plugins
Cursor — ~/.cursor/mcp.json
Windsurf — ~/.windsurf/mcp.json
VS Code — ~/Library/Application Support/Code/User/mcp.json (global), .vscode/mcp.json (workspace)
Cline — ~/.cline/mcp_servers.json
Roo Code — ~/.roo-code/mcp.json

Shows transport type (stdio/http/ws), source tool, and whether the server is already wrapped through lumen-argus mcp for scanning. Combine with --json for machine-readable output.

Cloud MCP servers (e.g., claude.ai Gmail) are Anthropic-hosted and have no local config — they are not detectable.

MCP server wrapping¶

Once you've detected MCP servers with --mcp, you can wrap them through lumen-argus mcp for scanning:

# Interactive — prompts for each server
lumen-argus-agent setup --mcp

# Wrap all detected stdio servers without prompting
lumen-argus-agent setup --mcp --non-interactive

# Wrap a specific server
lumen-argus-agent setup --mcp --server filesystem --source claude_desktop

# Undo — restore original config
lumen-argus-agent setup --mcp --undo

Wrapping rewrites the config file so {"command": "npx", "args": [...]} becomes {"command": "lumen-argus", "args": ["mcp", "--", "npx", ...]}. The original config is backed up to ~/.lumen-argus/setup/backups/.

Both stdio and HTTP/WS MCP servers can be wrapped:

Stdio servers: config rewrites command to lumen-argus mcp -- <original-command>
HTTP/WS servers: config converts URL to stdio bridge: lumen-argus mcp --upstream <original-url> — the AI tool manages the bridge process lifecycle

When enrolled with a Pro proxy, fleet policies from ~/.lumen-argus/mcp_policies.json are enforced during wrapping:

blocked servers are skipped with a warning
must_scan servers are auto-wrapped without prompting
allowed and review servers follow normal interactive/non-interactive flow

Proxy configuration check¶

Detection checks two sources to determine if a tool is routed through the proxy:

Shell profiles — scans ~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish, and PowerShell profiles for export OPENAI_BASE_URL=... (or the tool's specific env var)
IDE settings — loads settings.json for each VS Code variant and checks tool-specific proxy keys (http.proxy, cody.proxy, continue.proxy, etc.)

CI/CD environment detection¶

When running in CI or containers, detection automatically identifies the platform:

Environment	Detected via
GitHub Actions	`GITHUB_ACTIONS` env var
GitLab CI	`GITLAB_CI` env var
CircleCI	`CIRCLECI` env var
Jenkins	`JENKINS_URL` env var
Travis CI	`TRAVIS` env var
Buildkite	`BUILDKITE` env var
AWS CodeBuild	`CODEBUILD_BUILD_ID` env var
Azure Pipelines	`TF_BUILD` env var
Bitbucket Pipelines	`BITBUCKET_BUILD_NUMBER` env var
TeamCity	`TEAMCITY_VERSION` env var
Kubernetes	`KUBERNETES_SERVICE_HOST` env var
Docker	`/.dockerenv` file
Generic CI	`CI=true` env var

In CI environments, you typically don't need detection — just set the proxy env vars directly in your CI config:

# GitHub Actions example
env:
  OPENAI_BASE_URL: https://proxy.corp.io:8080
  ANTHROPIC_BASE_URL: https://proxy.corp.io:8080

Setting Up Tools¶

lumen-argus-agent setup

The setup wizard:

Detects installed tools (calls detect internally)
Filters to tools that are installed but not yet routed through the proxy
For each unconfigured tool, asks whether to configure it
Applies the configuration (shell profile or IDE settings)
Creates timestamped backups before every modification

What gets modified¶

The setup wizard uses a two-layer approach for toggleable protection:

1. Shell profile — a source block is written once and never touched again:

# In your .zshrc / .bashrc (written by lumen-argus-agent setup):
# lumen-argus:begin
[ -f "$HOME/.lumen-argus/env" ] && source "$HOME/.lumen-argus/env"
# lumen-argus:end

2. Env file — the actual env vars are written to ~/.lumen-argus/env:

export OPENAI_BASE_URL=http://localhost:8080  # lumen-argus:managed client=aider
export ANTHROPIC_BASE_URL=http://localhost:8080  # lumen-argus:managed client=claude_code

The file has two body shapes, picked by whoever invoked protection enable:

--managed-by cli (default) — unconditional exports. Right when you are running the binary yourself from a terminal (source install, pip, brew).
--managed-by tray — exports wrapped in a pure-shell liveness guard (.app-path for local mode, enrollment.json + relay.json PID for dedicated mode), zero subprocesses, sub-millisecond cost. The desktop tray app and the enrollment flow pass this flag so dragging-to-Trash does not leave AI tools pointed at a dead proxy.

See the Protection Env File reference for both body shapes, the activation matrix, and the full guard semantics.

This separation lets the tray app toggle protection by writing or truncating the env file, without ever touching your shell profile.

IDE extensions (VS Code, JetBrains) get their proxy setting updated in settings.json:

{
    "http.proxy": "http://localhost:8080"
}

Every managed line is tagged with # lumen-argus:managed for clean identification and removal. The env file is secured with 0o600 permissions (owner-only) because it is sourced by the shell.

Modes¶

# Interactive (default) — prompts for each tool
lumen-argus-agent setup

# Configure a specific tool only
lumen-argus-agent setup aider

# Non-interactive — auto-configure everything
lumen-argus-agent setup --non-interactive

# Dry run — show what would change, don't touch files
lumen-argus-agent setup --dry-run

# Custom proxy URL
lumen-argus-agent setup --proxy-url http://localhost:9090

Backups and undo¶

Every file modification creates a timestamped backup in ~/.lumen-argus/setup/backups/. A manifest tracks all changes.

To revert everything:

lumen-argus-agent setup --undo

This removes source blocks and managed lines from shell profiles, truncates the env file, restores IDE settings from backups, and clears forward proxy aliases.

Forward proxy tools¶

Some tools (e.g., Copilot CLI with GitHub auth) can't use custom base URLs. The setup wizard detects these (forward_proxy: true in the client registry) and offers step-by-step forward proxy configuration.

Forward-proxy setup is owned by the agent CLI (lumen-argus-agent setup) — CA generation depends on mitmproxy, which ships with the agent package. Running lumen-argus-agent setup copilot_cli from a proxy-only install prints a clear pointer to the correct command:

$ lumen-argus-agent setup copilot_cli

-- GitHub Copilot CLI ----------------------
  This tool requires forward proxy mode (TLS interception via mitmproxy).

  Step 1/4: Set up forward proxy for GitHub Copilot CLI? [Y/n]: y
  CA certificate generated: ~/.lumen-argus/ca/ca-cert.pem
  Step 2/4: Create shell alias for 'copilot'? [Y/n]: y
  Aliases written to ~/.lumen-argus/forward-proxy-aliases.sh
  Step 3/4: Add source line to ~/.zshrc? [Y/n]: y
  Added source line to ~/.zshrc
  Step 4/4: Install CA cert to system trust store? (requires admin) [Y/n]: n
  Skipped. For Node.js tools, the alias already sets NODE_EXTRA_CA_CERTS.

  To start the forward proxy:
    lumen-argus-agent relay --forward-proxy-port 9090

The alias wraps only the specific tool — other terminal commands are unaffected:

Shell Hook¶

For ongoing monitoring, you can install a shell hook that warns about unconfigured tools every time you open a new terminal:

# Add to your .zshrc / .bashrc
eval "$(lumen-argus detect --check-quiet 2>/dev/null)"

This runs in under 100ms and only prints a warning to stderr if unconfigured tools are found:

[lumen-argus] 1 unconfigured tool(s): Aider — run 'lumen-argus-agent setup'

If all tools are configured, it produces no output.

The setup wizard can install this hook for you via install_shell_hook(), and setup --undo removes it along with everything else (it uses the same # lumen-argus:managed tag).

Watch Daemon¶

For hands-free monitoring, the watch daemon periodically rescans the system and optionally auto-configures new tools:

# Run in the foreground (Ctrl+C to stop)
lumen-argus-agent watch

# Auto-configure new tools without prompting
lumen-argus-agent watch --auto-configure

# Custom scan interval (default: 300 seconds)
lumen-argus-agent watch --interval 600

How it works¶

On startup, runs a detection scan and saves the list of known tools
Every interval (default 5 minutes), rescans and compares against the known list
If a new tool appears, logs it (and auto-configures if --auto-configure is set)
State is persisted in ~/.lumen-argus/watch/state.json across restarts

Installing as a system service¶

Instead of running in the foreground, you can install the watch daemon as a system service that starts on login:

macOS (launchd)Linux (systemd)

# Install
lumen-argus-agent watch --install --auto-configure

# Start
launchctl load ~/Library/LaunchAgents/io.lumen-argus.watch.plist

# Check status
lumen-argus-agent watch --status

# Stop and remove
launchctl unload ~/Library/LaunchAgents/io.lumen-argus.watch.plist
lumen-argus-agent watch --uninstall

# Install
lumen-argus-agent watch --install --auto-configure

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now lumen-argus-watch

# Check status
lumen-argus-agent watch --status

# Stop and remove
systemctl --user stop lumen-argus-watch
lumen-argus-agent watch --uninstall

Logs go to ~/.lumen-argus/logs/watch.log (launchd) or the journal (systemd).

Protection Toggle¶

The protection command provides a VPN-like toggle for the tray app (or CLI):

# Enable — write all tool env vars to ~/.lumen-argus/env
lumen-argus-agent protection enable

# Disable — truncate the env file (tools connect directly to providers)
lumen-argus-agent protection disable

# Check status (JSON output for tray app consumption)
lumen-argus-agent protection status

Output:

{
  "enabled": true,
  "env_file": "/Users/you/.lumen-argus/env",
  "env_vars_set": 7
}

How it works:

enable writes env vars for ALL CLI tools (not just installed ones) to ~/.lumen-argus/env
disable truncates the file to empty — new terminal sessions connect directly
Existing terminal sessions are not affected until restarted (inherent OS limitation)
For instant effect on running sessions, combine with passthrough mode (see Proxy Guide)

The env file uses atomic writes (temp file + rename) and file locking (fcntl.flock) to prevent corruption from concurrent access.

Supported Agents¶

All 27 agents in the built-in registry, with their proxy configuration and detection methods:

Agent	Proxy Config	Setup Mechanism	Detection
Claude Code	`ANTHROPIC_BASE_URL`	env var	binary, npm
GitHub Copilot CLI	`COPILOT_PROVIDER_BASE_URL`	env var	binary, brew
Aider	`OPENAI_BASE_URL`	env var	binary, pip, brew
Codex CLI	`OPENAI_BASE_URL`	env var	binary, npm
OpenCode	env vars + `opencode.json` per-provider `baseURL`	env var + config file	binary, npm
Gemini CLI	`GEMINI_BASE_URL`	env var	binary, npm, brew
Cursor	Manual (IDE settings UI)	manual	binary, app bundle
GitHub Copilot	`http.proxy` (forward proxy)	IDE settings	VS Code, JetBrains, Neovim
Continue	`~/.continue/config.json`	config file	VS Code, Neovim
Cody	`cody.serverEndpoint`	IDE settings	VS Code, JetBrains, Neovim
Cline	Manual (extension UI)	manual	VS Code
Roo Code	Manual (extension UI)	manual	VS Code
Aide	Manual (IDE settings UI)	manual	binary, app bundle
Droid	Manual (BYOK settings)	manual	binary, npm, VS Code
CodeBuddy	Manual (models.json)	manual	binary, npm, VS Code, JetBrains
Kilo Code	Manual (extension UI)	manual	npm, VS Code
Windsurf	Not supported	—	binary, app bundle
Amazon Q	Not supported	—	binary, VS Code, JetBrains
Tabnine	Not supported	—	VS Code, JetBrains
Augment Code	Not supported	—	VS Code
Gemini Code Assist	Not supported	—	VS Code
Antigravity	Not supported	—	binary, app bundle
Kiro	Not supported	—	binary, app bundle
Kiro CLI	Not supported	—	binary
Trae	Not supported	—	app bundle
Qoder	Not supported	—	app bundle
Warp	Not supported	—	binary, app bundle

Run lumen-argus clients to see the full list with setup instructions.

Platform Support¶

macOS and Linux¶

Full support for all detection layers, shell profiles (zsh, bash, fish), IDE settings, and service installation.

Windows¶

Detection and setup support includes:

PowerShell profiles — both PowerShell 7 (Documents/PowerShell/) and Windows PowerShell 5.1 (Documents/WindowsPowerShell/)
PowerShell syntax — uses $env:VAR = "value" instead of export
VS Code settings — checks %APPDATA%/Code/User/settings.json (and variants for Cursor, Windsurf, Kiro, Trae, Insiders, VSCodium)
JetBrains plugins — checks %APPDATA%/JetBrains/
npm global packages — checks %APPDATA%/npm/node_modules/

Node Version Managers¶

The npm scanner checks paths managed by popular Node version managers:

nvm — NVM_DIR/current/lib/node_modules
fnm — FNM_DIR (or default platform path), FNM_MULTISHELL_PATH, aliases/default
volta — VOLTA_HOME/tools/image/packages, VOLTA_HOME/tools/image/node/<version>/lib/node_modules