argus

Argus

Argus is a Python CLI framework for running LLM-powered coding agents with tool execution, configurable model backends, permission controls, hooks, skills, trajectory recording, and benchmark-oriented evaluation helpers.

The project is built as an extensible agent runtime rather than a single-purpose chatbot. It includes multiple agent personalities, provider adapters for OpenAI-compatible and Anthropic APIs, a shared tool registry, an interactive terminal experience, headless prompt execution, and evaluation workflows for BFCL and SWE-bench style tasks.

Problem and Goals

Modern coding agents need more than a prompt wrapper around an LLM. They need a runtime that can:

• Run interactive and non-interactive tasks from the terminal.
• Route work to different agent modes such as a general Argus agent, Claude-style agent, or Codex-style agent.
• Execute tools while respecting approval and permission modes.
• Capture trajectories for analysis, debugging, and evaluation.
• Support project-specific guidance through repository prompts and reusable skills.
• Integrate with external guardrails through hooks.
• Evaluate agent behavior against function-calling and software engineering benchmarks.

Argus addresses these goals with a modular Python package that separates CLI orchestration, agent logic, model adapters, tool execution, configuration, hooks, skills, memory, and evaluation code.

Key Features

• Multi-agent runtime: supports configured argus, claude, and codex agents through AgentManager.
• Provider adapters: includes OpenAI-compatible chat/responses streaming and Anthropic Messages streaming adapters.
• Interactive CLI: provides a prompt-toolkit based terminal session with status display, command routing, shell escape support, and keyboard bindings.
• Headless execution: supports prompt execution through argus -p "...".
• Tool registry: auto-discovers registered tools and exposes different tool sets per provider.
• Core tools: includes bash, file read/write/edit, glob, grep, ls, web search, web fetch, memory, read-many-files, MCP-backed tools, task, todo, think, update-plan, shell, and apply-patch tools depending on the active agent.
• Permission modes: configuration and CLI support locked, edit-only, planning, and yolo permission levels.
• Hooks: supports UserPromptSubmit, PreToolUse, PostToolUse, Stop, and session startup events through command-based hook configuration.
• Skills system: loads repository, user, system, and admin skills from SKILL.md files and injects relevant skill instructions into the agent context.
• Memory and context management: includes a memory monitor that can compact conversation history when configured thresholds are reached.
• Trajectory recording: records agent/model/tool interactions under the Argus home directory for debugging and evaluation.
• Benchmark helpers: includes BFCL and SWE-bench evaluation scripts, adapters, datasets, and result export paths.
• Container support: includes Dockerfiles for the Argus agent runtime and Claude Code CLI installation.

Architecture

Argus is organized around a CLI-driven agent loop:

1. argus.main parses CLI arguments and loads configuration.
2. ConfigManager resolves YAML, CLI overrides, and supported environment variables.
3. HookManager loads hook configuration and emits lifecycle events.
4. ToolManager auto-discovers registered tools from argus.tools.
5. AgentManager initializes the requested agent.
6. The active agent streams LLM events, executes tools, records trajectories, and returns events to the CLI.
7. InteractiveSession or HeadlessRunner renders events and manages turn lifecycle.

Tech Stack

• Language: Python 3.10 to Python 3.12, with .python-version set to 3.12.
• Packaging: pyproject.toml, Hatchling build backend, uv.lock.
• CLI and terminal UI: argparse, click, rich, prompt-toolkit, textual.
• LLM SDKs: openai, anthropic, google-genai, ollama.
• Configuration and validation: pyyaml, pydantic, python-dotenv.
• Tooling and parsing: tree-sitter, tree-sitter-languages, jsonpath-ng.
• Networking and integrations: aiohttp, mcp.
• Testing: pytest.
• Evaluation extras: sb-cli, docker, tqdm, datasets.
• Lint configuration: Ruff settings are present in pyproject.toml.

Important Folders and Modules

argus/
  main.py                     CLI entry point and argument parsing
  agents/                     Agent implementations and agent event models
  agents/argus/               Default Argus chat/tool-calling agent
  agents/claude/              Claude-style agent runtime and context manager
  agents/codex/               Codex-style Responses API agent runtime
  cli/                        Interactive session, command processor, console UI
  config/                     AppConfig models, config manager, example YAML
  hooks/                      Hook models, matcher, runner, middleware, examples
  llm/                        LLM client and OpenAI/Anthropic adapters
  memory/                     Memory monitor and file restoration helpers
  skills/                     Skill loader, renderer, manager, and docs
  tools/                      Tool base class, registry, and concrete tools
  utils/                      Permissions, tokens, stats, key bindings, trajectories
evaluation/
  bfcl/                       BFCL dataset, adapter, evaluator, and runner
  swebench/                   SWE-bench runner and related docs
docs/                         Architecture notes, UML, and project structure docs
tests/                        Unit tests for config, tools, bash, and skills

Installation

Create and activate a virtual environment, then install the project in editable mode:

python -m venv .venv
source .venv/bin/activate
pip install -e .

The repository also includes uv.lock, and the project docs reference uv workflows:

uv venv
uv sync --all-extras

For benchmark/evaluation dependencies:

uv sync --extra evaluation

or:

pip install -e ".[evaluation]"

Configuration

Argus looks for its default configuration at:

~/.argus/argus_config.yaml

An example configuration is provided at:

argus/config/argus_config.example.yaml

The configuration defines:

• default_agent: active agent name.
• agents: agent entries with agent_name, provider, wire_api, model, api_key, and base_url.
• permission_level: one of locked, edit-only, planning, or yolo.
• max_turns: maximum agent turns per task.
• enable_logging and log_level.
• memory_monitor: token/capacity thresholds for context compaction.
• mcp: optional MCP server configuration.
• runtime: runtime metadata populated by the app.

CLI arguments can override model settings:

argus \
  --config ~/.argus/argus_config.yaml \
  --agent argus \
  --model "your-model" \
  --api_key "your-api-key" \
  --base_url "https://api.example.com/v1" \
  --permission-mode locked

Environment variables can fill missing model fields. For an agent named argus, the manager checks:

export ARGUS_MODEL="your-model"
export ARGUS_API_KEY="your-api-key"
export ARGUS_BASE_URL="https://api.example.com/v1"

For other configured agent names, use the uppercased agent name as the prefix, such as CODEX_MODEL, CODEX_API_KEY, or CLAUDE_BASE_URL. Generic fallback variables MODEL, API_KEY, and BASE_URL are also checked for supported fields.

The web search tool requires:

export SERPER_API_KEY="your-serper-key"

The bug-report command expects:

export GITHUB_TOKEN="your-github-token"

Usage

Show CLI help:

argus --help

Start the interactive CLI:

argus --config ~/.argus/argus_config.yaml --agent argus

Run a one-off headless prompt:

argus --config ~/.argus/argus_config.yaml --agent argus -p "Summarize this repository"

Switch agents at startup:

argus --config ~/.argus/argus_config.yaml --agent codex

Use a different permission mode:

argus --permission-mode yolo

Common interactive commands include:

• /help: show CLI help.
• /tools: list tools available to the current agent.
• /agent <name>: switch between configured agents.
• /model: list configured model entries and show the current default.
• /stats: show session statistics.
• /memory: inspect or update memory-related state.
• /clear: clear the screen and reset conversation history.
• /bug <description>: create a GitHub issue when GITHUB_TOKEN is configured.
• /quit: exit the CLI.
• !<command>: run a shell command from inside the CLI.

Some placeholder commands exist in the command processor; use /help in the running CLI to confirm current behavior.

Hooks

Hooks are loaded from:

~/.argus/argus_hooks.yaml

The current loader reads JSON-formatted hook content from that path. Hook groups can target lifecycle events such as:

• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop
• SessionStart

Hooks execute external commands, receive JSON on stdin, and can allow, deny, block, or add context depending on the event and output payload. See argus/hooks/README.md for examples and event payload notes.

Skills

Argus loads skills from multiple roots with the following priority:

1. Repository skills in .argus/skills/.
2. User skills in ~/.argus/skills/.
3. System skills in ~/.argus/skills/.system/.
4. Admin skills in /etc/argus/skills/.

Skills are Markdown files named SKILL.md with YAML frontmatter. The skills manager discovers relevant skills for the current working directory and injects a rendered skills section into agent context.

Testing

Run the test suite with:

pytest

Current tests cover configuration resolution, configuration loading, tool auto-discovery, bash tool behavior, and skill loading.

Evaluation Workflows

BFCL

Install evaluation dependencies, then run a small BFCL sample:

python evaluation/bfcl/run_bfcl_evaluation.py \
  --category simple_python \
  --samples 5 \
  --config ~/.argus/argus_config.yaml

The BFCL runner supports categories documented in evaluation/bfcl/README.md and writes result files under evaluation/bfcl/results by default.

SWE-bench

The SWE-bench docs reference this Docker build command:

docker build -f Dockerfile.argus-agent -t argus/agent:0.1 .

Example evaluation command from the repository docs:

python evaluation/swebench/run_evaluation.py \
  --config ~/.argus/argus_config.yaml \
  --limit 2 \
  --mode e2e

The SWE-bench runner supports dataset, agent, instance ID, pattern, limit, worker, mode, run ID, and force options. See evaluation/swebench/README.md and evaluation/swebench/run_evaluation.py.

Deployment and Containers

The repository includes:

• Dockerfile.argus-agent: Ubuntu-based runtime that installs uv, copies the Argus package, and prepares the agent environment.
• Dockerfile.claude-code-agent: Node-based image that installs @anthropic-ai/claude-code.

The Dockerfiles are primarily used by evaluation workflows and agent runtime packaging. Review them before production use because repository filenames and copied assets should match the current tree.

Security and Reliability Notes

• API keys should be supplied through user-specific config files, CLI arguments, or environment variables, not committed to the repository.
• The config manager treats placeholder values such as placeholder, changeme, and your-qwen-api-key-here as missing required fields.
• Permission modes are designed to control tool execution behavior.
• PreToolUse and PostToolUse hooks can be used to add guardrails around risky tools such as shell commands or file edits.
• Tool calls are mediated through ToolManager, which emits hook events and asks the CLI permission manager before executing tools.
• Conversation trajectories are recorded for debugging and evaluation; avoid storing sensitive prompts in shared environments.
• Web search depends on the external Serper API and should be configured with a scoped key.

Performance and Observability Notes

• Streaming adapters are used for supported OpenAI-compatible and Anthropic calls.
• Session statistics track current agent activity.
• Token limits are model-aware through argus/config/token_limits.py.
• MemoryMonitor can compact conversation history based on configured thresholds.
• Trajectory files provide a structured audit trail of prompts, model responses, tool calls, providers, and models.
• SWE-bench helpers cache the Argus agent image workspace and uv assets to reduce repeated setup work.

Known Gaps and Future Improvements

• Align older docs under docs/, argus/hooks/README.md, and argus/skills/README.md with the current package layout and English wording.
• Review Dockerfile.argus-agent copy targets against the current repository filenames before relying on it in CI.
• Add a checked-in .env.example or documented config template at the project root.
• Add CI workflow files for tests, linting, and package build verification.
• Expand tests around LLM adapter streaming, hook execution, MCP synchronization, and evaluation runners.
• Clarify whether hook configuration should use a .yaml or .json extension, since the loader currently parses JSON from the default hook path.
• Add screenshots or terminal recordings for portfolio presentation.

License

This project is licensed under the MIT License. See LICENSE.