https://github.com/ooloth/agency
Autonomous pipelines for AI coding agents — give your agents more agency. 🤖
https://github.com/ooloth/agency
Last synced: 9 days ago
JSON representation
Autonomous pipelines for AI coding agents — give your agents more agency. 🤖
- Host: GitHub
- URL: https://github.com/ooloth/agency
- Owner: ooloth
- Created: 2026-04-02T00:31:30.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T00:17:15.000Z (2 months ago)
- Last Synced: 2026-04-04T00:24:44.835Z (2 months ago)
- Language: Python
- Homepage:
- Size: 415 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# agency
> [!CAUTION]
> **Agency is a research project. If your name is not Michael Uloth, do not use it.**
>
> This software may change or break without notice. No support or warranty is provided.
> Use at your own risk.
Agency is a base of operations for the projects you maintain — a command center from which you scan
for issues, triage findings, and implement fixes. You register projects and their monitoring use
cases here, and your effects land in those projects as issues and PRs.
```mermaid
flowchart TD
subgraph scan["Scan loop"]
direction LR
S1[find] --> S2[triage] --> S3[draft] --> S4[review]
S4 -.->|revise| S3
end
S4 -->|ready| issues[(GitHub issues)]
subgraph groom["Groom loop"]
G1[evaluate]
end
issues --> G1
G1 -->|edit / close| issues
issues --> F1
subgraph fix["Fix loop"]
direction LR
F1[implement] --> F2[review]
F2 -.->|revise| F1
F2 -->|approved| F3[open PR]
end
```
## How it works
- **Scan runs find problems**: they query logs, read codebases, or check whatever else you
configure — they analyze what they see and propose worthwhile actions by posting well-formed
GitHub issues
- **Groom runs curate issues**: before fix runs, groom re-evaluates every open issue against the
current codebase — issues that are still accurate pass through unchanged, partially stale issues
get their bodies edited to reflect current state, and fully resolved issues are closed
- **Fix runs ship solutions**: they pick up open issues, implement solutions in fresh agent
subprocesses, and open PRs after a review pass — GitHub issues are the handoff mechanism, so
scan, groom, and fix can all run on independent schedules
- **The pipelines are deterministic**: every run follows the same fixed sequence of steps —
agentic behavior gets the repeatability and auditability you'd expect from a traditional
pipeline. What varies is configuration: adding a new scan type is adding a prompt file and a
scan block in `projects.json`
---
## Setup
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## Configure
### Register a project
Add an entry to `projects/projects.json`:
```json
{
"id": "my-project",
"name": "My Project",
"path": "~/Repos/me/my-project",
"install": "npm ci",
"test": "npm test",
"scans": [
{
"type": "codebase/dead-code",
"normal": ["Utility helpers that are imported dynamically"],
"flag": ["Exported functions with no internal or external callers"],
"ignore": ["Legacy adapters kept for backwards compatibility"]
}
]
}
```
`normal`, `flag`, and `ignore` are required — they calibrate the agent to each project's specific
signal and noise rather than relying on generic heuristics.
### Add a scan type
1. Add a prompt file to `prompts/scan/find/` describing what to look for
2. Add a matching scan block (with `type`, `normal`, `flag`, `ignore`) to the project in
`projects.json`
See [docs/playbooks/](docs/playbooks/) for step-by-step instructions.
## Run
```bash
# Scan a project (dry run — prints issues without posting)
uv run --frozen python run.py scan my-project --type codebase/dead-code --dry-run
# Scan a project and post issues
uv run --frozen python run.py scan my-project --type codebase/dead-code
# Groom open issues (dry run — logs verdicts without editing/closing)
uv run --frozen python run.py groom my-project --dry-run
# Groom open issues (edit partially resolved, close fully resolved)
uv run --frozen python run.py groom my-project
# Fix a specific issue
uv run --frozen python run.py fix --issue 3 --project my-project
# Fix the next open issue labelled 'ready-for-agent'
uv run --frozen python run.py fix
# Run with secrets from 1Password exposed as environment variables
op run --env-file=secrets.env -- uv run --frozen python run.py scan pilots --type logs/error-spikes
```
## Schedule
Edit your crontab with `crontab -e`:
```
# nightly at 2am — use absolute paths; cron has a minimal environment
0 2 * * * cd ~/path/to/agency && /opt/homebrew/bin/op run --env-file=secrets.env -- ~/.local/bin/uv run --frozen python run.py scan my-project --type codebase/dead-code
```
Or use GitHub Actions or your favourite other scheduler.
---
## Docs
| What | Where |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Philosophy and goals | [docs/philosophy.md](docs/philosophy.md) |
| Design decisions | [docs/decisions/](docs/decisions/) |
| Invariants to uphold | [docs/rules.md](docs/rules.md) |
| How to add projects, scan types, debug failures | [docs/playbooks/](docs/playbooks/) |
| Auth strategies by provider | [docs/architecture/auth.md](docs/architecture/auth.md) |
| Scan cadence and entropy management | [docs/architecture/scan-cadence.md](docs/architecture/scan-cadence.md) |
| Harness self-improvement | [docs/architecture/harness-self-improvement.md](docs/architecture/harness-self-improvement.md) |
| Conventions | [docs/conventions/](docs/conventions/) |
---
## Inspiration
- [workos/case](https://github.com/workos/case)