UACOS

UACOS is a local-first repo brain, context-compression layer, orchestration planner, and patch safety/evidence gate for AI coding workflows.

UACOS is not a Goose clone or general chat agent. The AI coding agent proposes or writes code. UACOS prepares bounded context, validates patch scope/risk, supports guarded apply/rollback, records evidence, and prevents unsupported product claims.

Start here

• Documentation Index — organized map of all project documentation.
• Current Status — completed phases, CI evidence, maturity, and remaining evidence gaps.
• Production Improvement Checklist — finite roadmap and completion evidence.
• Strategic Status — product positioning, Goose comparison, and maturity estimate.
• Language Policy — English-only repository content policy and automated release-gate check.

Requirements

• Python 3.9+
• Optional: Ollama for local real-model evaluation

Quick Start

python -m pip install -e .
uacos-flow setup --repo . --task "fix login bug safely"
uacos-flow doctor --repo .
uacos-flow status --repo .

Expected output:

{
  "status": "pass",
  "mode": "setup",
  "quick_commands": [
    "uacos-flow doctor --repo .",
    "uacos-flow assist --repo . --task \"fix login bug safely\" --max-tokens 6000"
  ]
}

Main workflow

uacos-flow assist --repo . --task "fix MCP docs" --max-tokens 6000
uacos-flow guard --repo . --patch change.diff --task "fix MCP docs" --allowed-file docs/PRODUCT_WORKFLOWS.md --test "pytest -q"
uacos-flow apply-safe --repo . --patch change.diff --allowed-file docs/PRODUCT_WORKFLOWS.md --test "pytest -q" --yes

Other useful commands

uacos-flow list
uacos-flow prepare --repo . --summary
uacos-flow orchestrate --spec "upgrade safely until tests pass" --agent goose --test "pytest -q" --max-iterations 3
uacos-flow benchmark --repo . --manifest evals/benchmark_suite.json

Existing uacos ... commands remain available and backward compatible.

Supported product workflows

1. Setup Mode — one-command local setup: bootstrap, graph, cache, scripts, and actionable doctor.
2. Doctor Mode — user-actionable readiness status with concrete next commands.
3. Status Mode — terminal/dashboard-friendly readiness and evidence summary.
4. Prepare Mode — repo graph, cache, memory, health reports, and compressed readiness evidence before AI edits.
5. Assist Mode — bounded task context, selected-file explanations, symbol context, route/API graph, test suggestions, and config-risk review.
6. Guard Mode — patch scope gates, secret scans, risk review, and optional task alignment without applying code.
7. Apply-safe Mode — checkpoint, tests, auto-rollback, and last-run evidence.
8. Orchestrate Mode — bounded spec -> context -> delegate -> patch -> test -> record -> improve planning without becoming the agent.

Product proof package

Use these before publishing claims or customer-facing material:

• Claim Wording Guide
• Public Benchmark Report Template
• Case Study Template
• Agent Comparison Matrix

Evidence and claims

Run the repeatable benchmark suite before making public savings claims:

python scripts/uacos_benchmark_suite.py --repo . --manifest evals/benchmark_suite.json --summary

Safe baseline claim:

UACOS reduces unnecessary repository context sent to AI coding agents by selecting task-relevant files, compressing context, and validating changes through local safety gates.

Do not claim 80-90% or 99% token savings unless a benchmark report directly supports that exact claim.

What you get

• reports/uacos_performance_report.json for token/context estimates
• reports/uacos_benchmark_suite_report.json for repeatable benchmark evidence
• reports/uacos_auto_report.json for Auto Mode summary
• reports/release_gate_report.json for release readiness checks
• .uacos/patch_lifecycle/latest_patch_lifecycle_report.json for the latest safe-apply evidence
• .uacos/scripts/ convenience dashboard launchers from uacos-flow setup
• examples/reports/uacos_flow_status_example.json for example status output
• uacos-flow simplified product workflow command

Community listing

UACOS is listed in awesome-cli-coding-agents under Agent infrastructure. The collection maintainer added the listing during a code-focused re-review of previously closed submissions (commit 885684c).

This is a community-maintained project listing, not a certification or vendor endorsement.

Documentation

Use docs/README.md as the main documentation index.