Repository Agent Team

Repository Agent Team is a local-first, read-only repository auditor. It inventories a repository, prepares deterministic evidence batches, asks specialist agents to analyze that evidence, validates the resulting claims against the frozen repository index, and writes a reviewable report outside the target repository.

Current release: 0.2.6
Runtime mode: analysis_only
Python: 3.11 or newer
License: MIT

Why it exists

Repository reviews produced by language models are often difficult to reproduce and easy to over-trust. Repository Agent Team narrows that risk with explicit boundaries:

• repository files are never edited;
• repository scripts and dependency installers are never executed;
• known secret-bearing paths are skipped;
• symlinks are not followed;
• every discovered file receives metadata and an exclusion reason when it is not read;
• model evidence is tied to a frozen repository index;
• unsupported or ambiguous repository claims are quarantined;
• completed runs can be verified deterministically and preserved with tamper-evident receipts.

Supported analyses

Every operation produces analysis and recommendations only. Operation names do not grant permission to modify the repository.

Operation	Purpose
audit	Review architecture, implementation quality, risks, and maintainability.
cleanup	Identify cleanup opportunities and distinguish safe automation from judgment calls.
roadmap	Prioritize evidence-backed next steps.
tasks	Produce a dependency-ordered implementation task list.
docs	Review user-facing documentation against repository evidence.
readme	Review README structure, hierarchy, and presentation.

Safety boundary

Version 0.2.6 supports only analysis_only mode.

It does not:

• edit target repository files;
• run target repository commands or tests;
• install target repository dependencies;
• create commits, branches, tags, pull requests, or issues;
• follow symlinks;
• read known sensitive paths such as .env, private keys, credentials files, or service-account files;
• treat instructions found inside the target repository as trusted instructions.

Run artifacts are written outside the target repository by default:

~/.local/state/repository-agent-team/runs/<run-id>/

Use --runs-dir or REPO_AGENT_RUNS_DIR to select another external directory.

Quick start

1. Install from the repository

git clone https://github.com/MerverliPy/repository-agent-team.git
cd repository-agent-team
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

PowerShell activation:

.\.venv\Scripts\Activate.ps1

For development, use an editable install:

python -m pip install -e .

2. Inspect hardware and local-model readiness

repo-agent-team --doctor

The doctor reports detected CPU, memory, WSL status, NVIDIA GPU/VRAM when available, installed Ollama models, unresolved facts, and conservative runtime recommendations.

3. Run an offline scan first

This exercises repository discovery, safety exclusions, indexing, evidence planning, and report generation without contacting a model:

repo-agent-team \
  --repo /path/to/repository \
  --operation audit \
  --runs-dir /external/path/repository-agent-runs \
  --no-llm

4. Run with a local OpenAI-compatible model

Example using Ollama:

export REPO_AGENT_BASE_URL="http://127.0.0.1:11434/v1"
export REPO_AGENT_API_KEY="local"
export REPO_AGENT_MODEL="auto"

repo-agent-team \
  --repo /path/to/repository \
  --operation audit

When REPO_AGENT_MODEL=auto, the hardware plan selects a conservative Qwen2.5 Coder model. Run --doctor first and install the exact recommended model when needed, for example:

ollama pull qwen2.5-coder:7b

Omit --operation to use the interactive menu.

How a model-backed run works

1. Record a hardware profile and resolve automatic runtime settings.
2. Walk the repository without following symlinks.
3. Record metadata for discovered files and skip sensitive, binary, generated, oversized, or excluded content according to policy.
4. Build deterministic evidence batches from eligible indexed text.
5. Send batches to the selected specialist prompt through an OpenAI-compatible Chat Completions endpoint.
6. Synthesize a report, then validate repository claims against the frozen index.
7. When the first synthesis contains rejected evidence-grounding blocks, retry synthesis once using only deterministic validation feedback.
8. Publish accepted blocks to report.md and retain the complete final synthesis in report-unvalidated.md.

Run artifacts

A run directory can contain:

run.json                         Run state, settings, coverage, and artifact paths
hardware-profile.json            Detected hardware and runtime recommendation
repository-profile.json          Aggregated repository facts and coverage
repository-index.json            Per-file metadata, hashes, and exclusion reasons
prompt-manifest.json              Prompt identities and evidence-batch membership
batch-001.md                      Specialist output for an LLM-backed run
report-unvalidated-attempt-1.md   First rejected synthesis, when a retry occurs
report-unvalidated.md             Complete final model synthesis
report-validation.json            Deterministic block-level validation decisions
report.md                         Offline report or validated model-backed report

Offline runs use status completed_offline. Model-backed runs use status completed even when unsupported blocks were quarantined; inspect evidence_validation_status, accepted/rejected counts, and report-validation.json.

Verify a completed run

The deterministic verifier reads an existing completed model-backed run without changing it:

repo-agent-team \
  --verify-run /external/path/repository-agent-runs/<run-id>

It checks the four core artifacts, analysis_only mode, completion state, path relationships, batch counts, claim counts, validation decisions, and 100% index/model-evidence coverage. Version 0.2.6 exposes a stable 27-check acceptance contract.

Exit codes:

Code	Meaning
0	Accepted.
1	Readable run rejected by one or more checks.
2	Invalid invocation, unreadable input, malformed JSON, or verifier error.

Create a new receipt only after the verifier accepts the run:

repo-agent-team \
  --verify-run /external/path/repository-agent-runs/<run-id> \
  --write-receipt /external/path/receipts/<run-id>.json

Verify the unchanged run against that receipt:

repo-agent-team \
  --verify-receipt /external/path/receipts/<run-id>.json \
  --run-dir /external/path/repository-agent-runs/<run-id>

A receipt is tamper-evident integrity evidence. It is not a cryptographic signature or proof of authorship.

Configuration

Common environment variables:

Variable	Default	Purpose
REPO_AGENT_BASE_URL	http://127.0.0.1:11434/v1	OpenAI-compatible API base URL.
REPO_AGENT_API_KEY	local	Bearer token; local endpoints often ignore it.
REPO_AGENT_MODEL	auto	Provider model ID or hardware-selected local model.
REPO_AGENT_TIMEOUT	0	Request timeout; 0 selects a hardware-tier value.
REPO_AGENT_BATCH_CHARS	0	Approximate evidence-batch size; 0 selects a hardware-tier value.
REPO_AGENT_PARALLEL_REQUESTS	0	Specialist concurrency; 0 selects a conservative value.
REPO_AGENT_MAX_FILE_BYTES	512000	Maximum individual file size read.
REPO_AGENT_MAX_TOTAL_BYTES	20000000	Maximum indexed repository text bytes.
REPO_AGENT_MAX_BATCHES	12	Maximum specialist evidence batches.
REPO_AGENT_SKIP_GENERATED	true	Skip generated/vendor content.
REPO_AGENT_ALLOW_REMOTE	false	Permit evidence transfer to a public or hostname-based endpoint.
REPO_AGENT_RUNS_DIR	platform home state directory	External run-artifact root.

A JSON file can override the same settings:

repo-agent-team \
  --repo /path/to/repository \
  --operation roadmap \
  --config examples/config.json

See Configuration for precedence, all keys, and endpoint rules.

Endpoint trust boundary

Without explicit opt-in, the client accepts only:

• localhost;
• loopback IP addresses;
• explicit private IP addresses;
• explicit link-local IP addresses.

Other hostnames and public IP addresses require:

export REPO_AGENT_ALLOW_REMOTE=true

Enable that only after approving transfer of repository evidence outside the local/private trust boundary.

Documentation

• Getting started
• Configuration reference
• Architecture
• Verification and receipts
• Technical specification
• Run state machine
• v0.2.6 release evidence
• Contributing
• Security
• Changelog

Development checks

PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONPATH=src python3 -m compileall -q src tests
sha256sum -c MANIFEST.sha256

The accepted v0.2.6 installed copy completed all 79 tests and compilation successfully. See v0.2.6 release evidence for the recorded acceptance identifiers and hashes.

Current limitations

• OpenAI-compatible Chat Completions endpoints only.
• No Git history analysis.
• No semantic vector index; evidence planning is deterministic and classification-driven.
• No command execution or dependency-aware runtime verification of the target repository.
• No patch generation or application.
• No write-capable repository operations.
• Receipt integrity is SHA-256 based and not cryptographically signed.

License

Repository Agent Team is released under the MIT License.