Metadata-Version: 2.4
Name: argus-review
Version: 0.1.1
Summary: Local multi-agent technical deliberation tool.
Project-URL: Homepage, https://github.com/MingLu0/Argus
Project-URL: Repository, https://github.com/MingLu0/Argus
Project-URL: Issues, https://github.com/MingLu0/Argus/issues
Author: MingLuo
License: MIT License
        
        Copyright (c) 2026 MingLuo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,cli,code-review,decision-support,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.4
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: textual>=0.89.0
Requires-Dist: typer>=0.12.3
Description-Content-Type: text/markdown

# Argus

Argus is a local multi-agent technical deliberation tool: many eyes on hard technical decisions.

It coordinates locally installed agent backends such as `claude`, `opencode`, and `codex`, runs independent reviewer roles in parallel, captures structured artifacts, groups disagreement, and produces a recommendation with explicit human decision gates for high-risk cases.

## Install

From PyPI:

```bash
uv tool install argus-review
argus version
```

From a local checkout:

```bash
uv tool install .
argus version
```

For development without installing the tool globally:

```bash
uv sync
uv run argus doctor
```

## MVP Commands

```bash
argus version
argus doctor
argus agents
argus run topic.md --mode tech-stack --backends auto
argus status
argus show <run-id>
argus respond <run-id> --action approve
argus tui <run-id>
```

### `argus run` options

- `--mode` — reviewer role set to use. Supported: `architecture`, `tech-stack`, `debugging`.
- `--backends` — which backends to fan out to. Accepts:
  - `auto` (default) — pick the first available real backend.
  - `auto-pool` — use every available real backend.
  - `fake` — use the bundled `fake-success` fixture three times (hermetic, no real agents required).
  - A comma-separated list of backend ids (e.g. `claude,codex`, or fixtures like `fake-delay,fake-stderr`, `fake-postgres`, `fake-dynamodb`, `fake-high-risk`). Unknown ids are rejected.
- `--timeout` — per-reviewer subprocess timeout in seconds (default `30`).
- `--project-root` — root directory for `.argus/` artifacts (default: current directory).

Reviewer roles are assigned to selected backends in the order they appear; duplicate `<backend>-<role>` ids are de-duplicated with a numeric suffix.

### Decision workflow

Use `argus show <run-id>` to review the run summary, decision gate, and recommendation for a completed or awaiting-decision run.

Use `argus respond <run-id> --action <action>` to record the human decision. Supported actions are `approve`, `choose-option`, `revise`, `request-more-review`, `defer`, and `abort`. `choose-option` also requires `--choice <value>`; any response can include `--note <text>`. `approve` and `choose-option` complete the run, `abort` cancels it, and `revise` and `defer` keep it in `awaiting_decision`. `request-more-review` runs one bounded follow-up pass for the reviewers in unresolved conflicts, then leaves the run in `awaiting_decision` if the revised decision gate still requires a human decision or completes it when the gate clears; the same run cannot start a second follow-up pass.

### Terminal UI

Use `argus tui <run-id>` to launch a [Textual](https://textual.textualize.io/) terminal UI for a run. The `<run-id>` argument is optional; when omitted, the UI loads the latest run under `.argus/runs/`. The `--project-root` option points at the directory holding `.argus/` artifacts (default: current directory).

The UI reconstructs run state from `.argus/argus.db` when the SQLite store is available and falls back to the file artifacts otherwise (shown as `Source: SQLite + artifacts` or `Source: artifacts` in the overview). It shows the run overview, the reviewer pipeline with per-step status and durations, grouped conflicts and reviewer positions, a tail of the reviewer `stderr` logs and `events.jsonl`, and an action bar.

Key bindings:

- `r` — refresh the run state.
- `j` / `k` — move the selected conflict.
- `enter` — toggle raw reviewer output for the selected conflict.
- `a` — accept the recommendation and record accepted risk (only when status is `awaiting_decision`).
- `c` — choose the selected conflict's first option (only when status is `awaiting_decision`).
- `m` — request follow-up review (only when status is `awaiting_decision`).
- `d` — defer the decision (only when status is `awaiting_decision`).
- `x` — abort the run after a second confirmation press (only when status is `awaiting_decision`).
- `h` — toggle help.
- `q` — quit.

Decision keys apply the same decision gate as `argus respond`; they are ignored unless the run is `awaiting_decision`. Pressing `m` runs the same bounded follow-up pass as `argus respond --action request-more-review` and refreshes the run when it finishes.

### Run artifacts

Each run writes to `.argus/runs/<run-id>/`:

- `run.yaml` — run manifest with per-step status and, after a CLI or TUI decision, the recorded `decision_action`, `decision_note`, `decision_choice`, and `decided_at` fields.
- `backend-report.json` / `backend-report.md` — discovered backends and availability.
- `reviewers.json` — per-reviewer record (command, exit code, duration, timed-out flag, artifacts).
- `reviews/<reviewer-id>.raw.md`, `reviews/<reviewer-id>.parsed.json`, `logs/<reviewer-id>.{stdout,stderr}.log`, `artifacts/<reviewer-id>.result.json` — raw reviewer output, the structured `ReviewResult` parsed from it, and execution detail.
- `synthesis.md`, `run-summary.md`, `recommendation.md` — synthesized output, per-reviewer status summary, and the final recommendation with decision matrix, readiness, risk, conflicts, and reviewer status.
- `open-questions.md` / `next-actions.md` — extracted follow-up questions and actions from structured reviews and gates.
- `findings.json` — consolidated structured findings across reviewers; each entry carries a namespaced `id`, `reviewer_id`, `severity`, `action`, `claim`, `evidence`, `confidence`, and `affected_decision`.
- `conflicts.json` — cross-reviewer disagreement grouped by `affected_decision`. Each conflict carries an `id` (e.g. `conflict-database`, with numeric suffixes for slug collisions), `affected_decision`, `risk_level` (`low`/`medium`/`high`), `status` (`unresolved` or `non_conflicting`), `rationale`, and one `position` per contributing finding (with `reviewer_id`, `finding_id`, `claim`, `action`, `severity`, `confidence`, and `evidence`). Findings with the default `affected_decision` are not bucketed across reviewers, and reviewer disagreement is only marked `unresolved` when at least one position carries an `ask-user` or `block` action.
- `decision-gate.yaml` — written only when human decision is required. Records `required`, the aggregated `risk_level`, the deduplicated `reasons` that triggered the gate, the `conflict_ids` and `finding_ids` referenced by those reasons, and the `successful_reviewers` / `minimum_successful_reviewers` counts. A gate is required when there are too few successful reviewers, any reviewer reported `risk_level: high` or a parse error, any finding has an `ask-user` or `block` action, or any conflict is unresolved or high-risk. When the gate is required, `run.yaml` status is set to `awaiting_decision`; otherwise the run completes.
- `decision.md` — written by `argus respond` or TUI decision keys with the selected action, decision timestamp, optional choice, and optional note.
- `rounds/round-1/` — created by `request-more-review` as a snapshot of the original reviews, logs, artifacts, findings, conflicts, decision gate, synthesis, and recommendation before follow-up reviewers run.
- `rounds/round-2-conflict-review/` — created by `request-more-review` with the follow-up prompt, reviewer records, raw and parsed follow-up reviews, logs, execution artifacts, revised findings, revised conflicts, and a follow-up summary. The top-level `findings.json`, `conflicts.json`, `decision-gate.yaml`, `synthesis.md`, `recommendation.md`, `open-questions.md`, and `next-actions.md` are then rewritten from the combined original and follow-up reviews.

Argus also maintains `.argus/argus.db`, a SQLite state store initialized on demand. Each completed `argus run` and each CLI or TUI decision upserts the run manifest plus steps, backend availability, reviewer records, findings, conflicts, decisions, artifacts, and events into tables tracked by `schema_migrations`.

Reviewers are prompted to emit a single JSON object (optionally inside a ```json fenced block). When the output cannot be parsed, the per-reviewer `.parsed.json` records a `parse_error` and `findings.json` simply omits that reviewer's findings.

The file artifacts under `.argus/runs/` remain the human-readable record; SQLite mirrors the same run state for reconstruction, the `argus tui` terminal UI, and future query workflows.

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

Real backend integration tests are opt-in because they invoke installed agent tools and may incur model/API cost or require local authentication:

```bash
ARGUS_REAL_BACKENDS=1 uv run pytest tests/integration_real
```

Without `ARGUS_REAL_BACKENDS=1`, tests marked `real_backend` are skipped during normal `uv run pytest`. When enabled, each real backend test skips cleanly if its binary is not installed on `PATH`; otherwise it runs Argus in a temporary project directory and leaves no artifacts in the repository.

## Release

Release builds are handled by GitHub Actions. Pushing a `v*` tag that matches the version in `pyproject.toml` builds the wheel and source distribution, uploads the generated `dist/*.whl` and `dist/*.tar.gz` files as workflow artifacts, and attaches those files to a GitHub release:

```bash
git tag v0.1.1
git push origin v0.1.1
```

The release workflow can also be run manually from GitHub Actions to validate packaging without creating a tagged release.

## License

Argus is licensed under the MIT License. See [LICENSE](LICENSE).
