{"id":50541475,"url":"https://github.com/ooloth/agency","last_synced_at":"2026-06-03T20:01:24.912Z","repository":{"id":348624735,"uuid":"1198985333","full_name":"ooloth/agency","owner":"ooloth","description":"Autonomous pipelines for AI coding agents — give your agents more agency. 🤖","archived":false,"fork":false,"pushed_at":"2026-04-04T00:17:15.000Z","size":425,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T00:24:44.835Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ooloth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T00:31:30.000Z","updated_at":"2026-04-04T00:17:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ooloth/agency","commit_stats":null,"previous_names":["ooloth/vitals","ooloth/agency"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ooloth/agency","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooloth%2Fagency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooloth%2Fagency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooloth%2Fagency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooloth%2Fagency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ooloth","download_url":"https://codeload.github.com/ooloth/agency/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooloth%2Fagency/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33876894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T20:01:24.004Z","updated_at":"2026-06-03T20:01:24.903Z","avatar_url":"https://github.com/ooloth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agency\n\n\u003e [!CAUTION]\n\u003e **Agency is a research project. If your name is not Michael Uloth, do not use it.**\n\u003e\n\u003e This software may change or break without notice. No support or warranty is provided.\n\u003e Use at your own risk.\n\nAgency is a base of operations for the projects you maintain — a command center from which you scan\nfor issues, triage findings, and implement fixes. You register projects and their monitoring use\ncases here, and your effects land in those projects as issues and PRs.\n\n```mermaid\nflowchart TD\n    subgraph scan[\"Scan loop\"]\n        direction LR\n        S1[find] --\u003e S2[triage] --\u003e S3[draft] --\u003e S4[review]\n        S4 -.-\u003e|revise| S3\n    end\n    S4 --\u003e|ready| issues[(GitHub issues)]\n    subgraph groom[\"Groom loop\"]\n        G1[evaluate]\n    end\n    issues --\u003e G1\n    G1 --\u003e|edit / close| issues\n    issues --\u003e F1\n    subgraph fix[\"Fix loop\"]\n        direction LR\n        F1[implement] --\u003e F2[review]\n        F2 -.-\u003e|revise| F1\n        F2 --\u003e|approved| F3[open PR]\n    end\n```\n\n## How it works\n\n- **Scan runs find problems**: they query logs, read codebases, or check whatever else you\n  configure — they analyze what they see and propose worthwhile actions by posting well-formed\n  GitHub issues\n- **Groom runs curate issues**: before fix runs, groom re-evaluates every open issue against the\n  current codebase — issues that are still accurate pass through unchanged, partially stale issues\n  get their bodies edited to reflect current state, and fully resolved issues are closed\n- **Fix runs ship solutions**: they pick up open issues, implement solutions in fresh agent\n  subprocesses, and open PRs after a review pass — GitHub issues are the handoff mechanism, so\n  scan, groom, and fix can all run on independent schedules\n- **The pipelines are deterministic**: every run follows the same fixed sequence of steps —\n  agentic behavior gets the repeatability and auditability you'd expect from a traditional\n  pipeline. What varies is configuration: adding a new scan type is adding a prompt file and a\n  scan block in `projects.json`\n\n---\n\n## Setup\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Configure\n\n### Register a project\n\nAdd an entry to `projects/projects.json`:\n\n```json\n{\n  \"id\": \"my-project\",\n  \"name\": \"My Project\",\n  \"path\": \"~/Repos/me/my-project\",\n  \"install\": \"npm ci\",\n  \"test\": \"npm test\",\n  \"scans\": [\n    {\n      \"type\": \"codebase/dead-code\",\n      \"normal\": [\"Utility helpers that are imported dynamically\"],\n      \"flag\": [\"Exported functions with no internal or external callers\"],\n      \"ignore\": [\"Legacy adapters kept for backwards compatibility\"]\n    }\n  ]\n}\n```\n\n`normal`, `flag`, and `ignore` are required — they calibrate the agent to each project's specific\nsignal and noise rather than relying on generic heuristics.\n\n### Add a scan type\n\n1. Add a prompt file to `prompts/scan/find/` describing what to look for\n2. Add a matching scan block (with `type`, `normal`, `flag`, `ignore`) to the project in\n   `projects.json`\n\nSee [docs/playbooks/](docs/playbooks/) for step-by-step instructions.\n\n## Run\n\n```bash\n# Scan a project (dry run — prints issues without posting)\nuv run --frozen python run.py scan my-project --type codebase/dead-code --dry-run\n\n# Scan a project and post issues\nuv run --frozen python run.py scan my-project --type codebase/dead-code\n\n# Groom open issues (dry run — logs verdicts without editing/closing)\nuv run --frozen python run.py groom my-project --dry-run\n\n# Groom open issues (edit partially resolved, close fully resolved)\nuv run --frozen python run.py groom my-project\n\n# Fix a specific issue\nuv run --frozen python run.py fix --issue 3 --project my-project\n\n# Fix the next open issue labelled 'ready-for-agent'\nuv run --frozen python run.py fix\n\n# Run with secrets from 1Password exposed as environment variables\nop run --env-file=secrets.env -- uv run --frozen python run.py scan pilots --type logs/error-spikes\n```\n\n## Schedule\n\nEdit your crontab with `crontab -e`:\n\n```\n# nightly at 2am — use absolute paths; cron has a minimal environment\n0 2 * * * cd ~/path/to/agency \u0026\u0026 /opt/homebrew/bin/op run --env-file=secrets.env -- ~/.local/bin/uv run --frozen python run.py scan my-project --type codebase/dead-code\n```\n\nOr use GitHub Actions or your favourite other scheduler.\n\n---\n\n## Docs\n\n| What                                            | Where                                                                                          |\n| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Philosophy and goals                            | [docs/philosophy.md](docs/philosophy.md)                                                       |\n| Design decisions                                | [docs/decisions/](docs/decisions/)                                                             |\n| Invariants to uphold                            | [docs/rules.md](docs/rules.md)                                                                 |\n| How to add projects, scan types, debug failures | [docs/playbooks/](docs/playbooks/)                                                             |\n| Auth strategies by provider                     | [docs/architecture/auth.md](docs/architecture/auth.md)                                         |\n| Scan cadence and entropy management             | [docs/architecture/scan-cadence.md](docs/architecture/scan-cadence.md)                         |\n| Harness self-improvement                        | [docs/architecture/harness-self-improvement.md](docs/architecture/harness-self-improvement.md) |\n| Conventions                                     | [docs/conventions/](docs/conventions/)                                                         |\n\n---\n\n## Inspiration\n\n- [workos/case](https://github.com/workos/case)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooloth%2Fagency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooloth%2Fagency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooloth%2Fagency/lists"}