AlexsJones/repo-steward

오픈 소스 저장소 관리를 위한 자율 에이전트입니다.

Repo Steward는 오픈 소스 저장소를 유지 관리하는 운영 측면 — 이슈 분류(triage), 여러 반복에 걸친 풀 리퀘스트(PR) 검토, 저장소 토론 참여, 버그 수정 PR 작성, 프로젝트 웹사이트 모니터링 — 을 스케줄 또는 버튼 클릭으로 수행하는 에이전트입니다. 무엇이 일어나고 있는지 실시간 대시보드를 유지하고, 오직 결정적인 분기점이나 디자인 결정만 사용자에게 에스컬레이션합니다.

하루가 PR diff를 채팅 창에 붙여넣는 작업으로 사라지는 관리자를 위해 제작되었습니다: 이 스튜어드는 사용자가 제공하는 모든 저장소에서 이러한 루프를 자율적으로 수행하고 그 과정을 보여줍니다.

**기본값은 초안 모드(Draft mode)**입니다. 모든 검토와 답변은 라이브 토글을 켜기 전까지 승인을 위해 대기됩니다. 무언가가 사용자 대신 발언하려면 먼저 그럴 만한 가치를 입증해야 합니다.사용자가 최종 상태(terminal state)입니다 — 스튜어드는 자체 판단으로 병합하거나 닫지 않습니다. 병합은 사용자의 대시보드 클릭, 입력된 결정, 또는 작성된 병합 규칙(Good to merge 참조)에서 나옵니다. 이 작업은 사용자의 GitHub 인증 하에 사용자가 행동했기 때문에 실행됩니다.무엇을 만들지 결정하고, 그것을 만듭니다 — Insights 스윕은 가치, 준비 상태 및 노력에 따라 오픈 이슈를 순위화합니다. 하나를 선택하고 Build를 클릭하면 스튜어드가 이를 구현하고 PR을 엽니다.문장으로 결정합니다 — 모든 에스컬레이션에 대해 자유 형식의 결정을 입력하고 Enter를 누릅니다. 집중적인 실행기(focused executor)가 이를 해석하여 수행합니다.작업 과정을 정직하게 보여줍니다 — 진행 상황과 예상 완료 시간(ETA)은 디스크의 아티팩트와 GitHub 사실에서 파생되며, 모델 자체 보고에 의존하지 않습니다. 또한 저장소별 큐, 대기 중인 액션 텍스트, 토큰/비용 측정 지표, 트렌드 및 가동 시간 카드가 제공됩니다.

• 인증된 헤드리스 에이전트 CLI (백엔드 참조; 기본값 Claude Code)
• GitHub CLI, 저장소에 푸시 접근 권한으로 인증
• python3, jq가 설치된 Linux 시스템d 사용자 세션

git clone https://github.com/<you>/repo-steward && cd repo-steward
cp config.example.yaml config.yaml # 수정할 내용: 저장소, 서명(signature), 제한(limits)
./install.sh # 또는 수동으로만 실행하려면 --no-timer 사용

그런 다음 첫 번째 예약된 틱을 기다리거나 지금 바로 시작합니다:

make tick # 지금 한 번 실행
make logs # 추적(follow)하기

make help

은 모든 명령어(serve, start, status, open, timer-on/off, uninstall, …)를 나열합니다. 이는 systemd 유닛의 사용자 친화적인 진입점입니다.

http://localhost:8377/ 에 접속하여 확인하세요. 대시보드는 필요한 결정 사항, 전체 텍스트가 포함된 스테이징된 작업(staged actions), 저장소별 대기열(per-repo queues), 그리고 (몇 번의 틱 실행 후) 추세선(trend lines)을 보여줍니다. 이 페이지는 자동 새로고침되며; 네트워크상의 다른 장치에서는 http://<호스트-IP>:8377/ 을 사용합니다.

(필요한 경우 방화벽에서 포트를 열어주세요).

설치 시 환경 변수를 통해 모델을 고정하거나 주기(cadence)를 변경할 수 있습니다:

# 강력한 모델을 사용하여 30분마다 실행
STEWARD_MODEL=claude-opus-5 STEWARD_CADENCE="*-*-* *:07,37:00" ./install.sh
# 또는 매일 아침 더 큰 간격으로 한 번 실행 (config.yaml의 `limits`를 조정하여 일치시킵니다)
...

STEWARD_MODEL은 systemd 유닛에 포함되어 모든 틱에서 엔진에 --model로 전달됩니다. 기본 Claude Code 엔진을 사용하는 경우, 전체 ID(claude-opus-5, claude-sonnet-5, claude-haiku-4-5) 또는 해당 계열의 최신 모델을 추적하는 별칭(opus, sonnet, haiku) 중 하나를 사용하거나 비워두어 CLI 자체 기본값을 따르게 할 수 있습니다. 나중에 대시보드 헤더의 제공업체 선택기(provider selector)에서 백엔드를 전환하세요. 제공업체를 전환하면 이전 제공업체의 모델 고정 설정이 초기화됩니다. 새 모델을 고정하려면 설치 프로그램을 다시 실행해야 합니다. 모든 설치는 전달된 환경 변수로부터 유닛을 재작성하므로, 생략된 변수는 이전 설치에서 가져와지지 않습니다: STEWARD_MODEL은 고정되지 않은 상태로 되돌아가고, STEWARD_ENGINE은 claude로 되돌아갑니다. 둘 다 유지하고 싶다면 둘 다 전달하세요:

The tick과 dashboard는 gh를 사용하므로 환경 시스템드(systemd)가 인식할 수 있는 GitHub 자격 증명(credential)이 필요합니다. 셸의 rc 파일은 그곳에서 절대 로드되지 않습니다. 설치 프로그램은 토큰을 ~/.config/repo-steward/env (모드 0600, 두 유닛 모두에 의해 GITHUB_TOKEN으로 읽힘)에 스냅샷하고, 자체 유닛 파일에는 절대로 저장하지 않으며, 그곳에서는 systemctl show로 노출될 것입니다.

기본적으로 설치 프로그램은 GH_TOKEN을 읽고, 실패할 경우 GITHUB_TOKEN을 사용합니다. 만약 토큰이 사용자 지정 이름(예: ~/.zshrc의 GITHUB_TOKEN_REPO_STEWARD)으로 존재한다면, 설치 프로그램에 그 이름을 알려주세요:

source ~/.zshrc # 또는 이 셸에서 변수를 내보내기(export) 하십시오
STEWARD_GITHUB_TOKEN_VAR=GITHUB_TOKEN_REPO_STEWARD ./install.sh

일반적인 재실행 규칙이 적용됩니다: 해당 값들을 유지하고 싶을 때마다 STEWARD_ENGINE 또는 STEWARD_MODEL을 다시 전달해야 합니다. 토큰이 내보내지지 않은 경우, 설치 프로그램은 gh가 저장한 인증 정보(~/.config/gh/hosts.yml, 이는 HOME을 통해 서비스가 찾으며, 키링(keyring) 기반 자격 증명을 포함함)로 되돌아가지만 — rc 파일에만 있는 변수는 어느 경로에도 도달하지 못하며, 이것이 바로 스냅샷의 목적입니다. 토큰을 로테이션한 후 설치 프로그램을 다시 실행하세요. 스냅샷은 실시간(live)이 아닙니다.

범위 측면에서 토큰은 최소한 repo 권한과, 관리자(steward)가 .github/workflows 파일을 건드려야 하는 경우에만 workflow 권한이 필요합니다. 이것 없이는 해당 병합(merge) 작업들은 수동으로 유지됩니다.

다음 tick이 무엇을 사용할지 확인하려면 로그(logs/tick.log) 대신 유닛을 읽으세요. === tick <ts> engine=<name> === 헤더는 tick이 완료될 때만 얻어지므로, 설치 직후에도 그 꼬리(tail)는 여전히 이전 설정을 설명합니다:

systemctl --user show repo-steward.service -p Environment

이는 사용자의 Claude Code 세션과는 별개이며, 관리자는 절대 건드리지 않습니다 — 세션 내에서 /model opus로 전환하거나, 실행할 때 claude --model claude-opus-5를 사용해 해당 세션을 전환하세요.

이 '틱(tick)'은 에이전트 세션입니다. 이 세션은 gh를 실행하고, 원장(ledger)을 수정하며, 파일을 작성합니다. 따라서 백엔드는 설치 시점에 선택되는 헤드리스 코딩 에이전트 CLI로 구성됩니다:

./install.sh # Claude Code (기본값)
STEWARD_ENGINE=codex ./install.sh # OpenAI Codex CLI
STEWARD_ENGINE=gemini ./install.sh # Gemini CLI
...

**로컬 / OpenAI 호환 제공업체(providers)**는 두 가지 형태로 제공됩니다: Ollama/LM Studio/지원하는 모든 제공업체에 대해 opencode를 실행하거나, Claude Code 엔진을 유지하고 프록시(ANTHROPIC_BASE_URL + LiteLLM이 OpenAI, Bedrock, Vertex 또는 로컬 모델로 라우팅)를 가리킵니다. 비-Claude 엔진의 주의사항: 병합/닫기/강제 푸시*권한 거부 계층(permission deny layer)*은 .claude/settings.json으로 구성되며, 이는 Claude Code에서만 강제됩니다. 다른 엔진의 경우 플레이북의 가드레일(guardrails)이 여전히 지침을 제공하지만, 기계적으로 차단하는 것은 없습니다. 이에 따라 사용자의 엔진 자체 샌드박스/승인 설정을 적절히 구성해야 합니다. usage.jsonl에 대한 토큰/비용 캡처는 현재 Claude 전용입니다(다른 엔진은 헤드리스 상태에서 사용량 엔벨로프를 방출하지 않음). 이 경우 메트릭 페이지가 정상적으로 작동합니다. Claude Code 외의 엔진들은 가볍게 테스트되었으며, 보고서와 PR을 환영합니다.

모든 페이지는 상단 바 하나를 공유합니다. 왼쪽에는 다음 페이지들이 있습니다: 운영(Operations), 통찰력(Insights), 평가(Evaluation), 메트릭(Metrics), 그리고 감사(Audit). 오른쪽에는 실시간 상태가 표시됩니다: 사이트 가동 시간, 모드(LIVE 또는 DRAFT; 클릭하여 전환하며 확인 절차 필요), 엔진 및 모델, 일정(Schedule), 그리고 마지막 틱(Tick) 결과 또는 실행 중 경과 시간입니다.

작업(Work) (또는 w, 또는 /dashboard.html#work)

)"는 스튜어드의 대기열입니다. 현재 실행 중인 작업과 각 실행의 최신 단계, 그리고 기다리는 항목(입력된 결정, 대기 중인 빌드, 사용자의 명확한 설명이 필요한 결정)을 보여줍니다. 틱(Tick) 또는 결정 러너(decision runner)가 작동하는 동안 원장(ledgers)을 보유하므로 병합(merges), 게시(posts), 해제(dismissals)는 대기합니다. 셀은 주황색으로 바뀌고 LOCKED라고 표시되며, 영향을 받는 버튼들은 이유와 함께 비활성화되고, Operations에는 무엇이 이들을 붙잡고 있는지 알려주는 배너가 나타납니다. 스윕(Sweeps), 평가(evaluations), 빌드는 병합을 절대 막지 않습니다.

▶ Run tick은 필요할 때 틱을 시작합니다. 하나가 실행되는 동안, 진행 표시줄이 바 아래에 나타나고 ■ Stop이 버튼을 대체합니다. 진행 상황은 *결정론적(deterministic)*입니다. 즉, 틱이 확실하게 완료한 청크(repo 원장, 메트릭, 대시보드 쓰기, 파일 mtime 등)를 계산하며, 예상 시간(ETA)은 과거 틱의 실제 청크별 타이밍(timings.jsonl)의 중앙값입니다. 중지하려면 확인이 필요하며, 틱 서비스만 종료하고 부분적인 로컬 아티팩트는 유지합니다. 이미 GitHub에 게시된 내용은 되돌릴 수 없습니다. 취소는 감사 로그(audit log)에 기록됩니다.

Settings(또는 ,)에는 나머지 모든 것이 담겨 있습니다. Engine은 틱, 스윕 및 빌드용 CLI를 전환하며, Schedule은 수동, 시간별, 6시간마다, 일일 또는 주간으로 시스템d 타이머를 라이브로 구성합니다. Sign-off는 게시된 댓글에 서명을 토글하고, Tick size는 실행당 작업 제한(work caps)을 설정하며, Watched resources는 이슈, PR 및 토론의 리포지토리별 매트릭스에 각 리포지토리의 우선순위가 더해진 것입니다. Theme은 이 브라우저를 위한 라이트, 다크 또는 시스템 설정을 선택합니다. 스케줄, 서명, 테마를 제외한 모든 것은 다음 틱부터 적용되므로, 진행 중일 때 변경해도 안전합니다.

Operations는 사용자에게 무엇이 기다리고 있는지에 대한 읽기 전용 정보와 리포지토리 레일(리포지토리를 클릭하여 모든 패널을 해당 항목에 집중시킬 수 있으며, 주황색 숫자는 그곳에서 필요한 항목의 개수입니다) 및 행 필터(/)를 열어줍니다. 그 패널들은 다음과 같습니다:

**필요한 결정(Decisions needed): 각 에스컬레이션에는 명령줄이 있습니다. 원하는 내용을 입력하고 Enter를 누르세요. '결정 및 승인(Decisions & approvals)'을 확인하세요.**최종 검토 준비 완료(Ready for your final look): GitHub와 실시간으로 비교되는 recommend-to-merge 단축 목록입니다. 이미 병합되었거나 닫힌 PR은 취소선 처리되며, 현재 헤드에서의 승인은 경과 시간을 보여줍니다.병합(Merge): 아직 게시되지 않은 스테이징된 검토 내용을 게시한 후 병합합니다.검토(Review): 스테이징된 텍스트를 보여주며, **무시(Dismiss)**는 항목을 게시하지 않고 제거합니다.빌드(Builds): 각 빌드의 상태와 PR이 포함된 Insights 빌드 대기열입니다.스테이징된 답글(Staged replies): 스튜어드가 작성한 나머지 모든 내용입니다.보기(View): 내용을 읽고, **게시(Post)**는 귀하의 계정으로 전송합니다.**다음 틱(Next tick)**은 계획입니다. 스튜어드가 다음에 무엇을 할 것인지 그리고 그 이유입니다.**마지막 틱(Last tick)**은 실제로 무엇을 했는지에 대한 기록입니다.

패널들은 헤더를 클릭하여 접을 수 있으며, 이 브라우저에서는 그 상태가 유지됩니다.

키보드. g 다음 o / i / e / m / a는 페이지를 전환합니다. j와 k는 행 사이를 이동하고, enter는 선택된 행(검토, 보기, 결정 상자, 테마의 개요, 이벤트의 원시 JSON)을 엽니다. /는 필터링을 하고, ,는 설정을 열며, w는 작업 대기열이고, ?는 모든 단축키를 나열합니다.

컨트롤은 server.py에 의해 페이지가 제공될 때만 나타납니다.

; 정적 복사본은 읽기 전용입니다.

귀하의 이름으로 GitHub와 상호작용하는 모든 것은 귀하가 행동했기 때문에 발생하며, 모든 행동은 approvals.jsonl 감사 추적 기록에 남습니다:

병합(Merge) (Ready 테이블) — 귀하의 인증 하에서 gh를 통해 스테이징된 검토 내용을 실행한 다음 병합합니다 (설정의 merge_method: 방식, 그렇지 않으면 리포가 허용하는 첫 번째 방식: squash → merge → rebase). 초안 모드에서도 작동합니다. 클릭은 귀하가 행동했음을 의미합니다. 만약 엄격한 브랜치 보호 규칙이 승인된 PR이 main보다 뒤처져 있다고 한다면

에서도 작동합니다. 클릭은 귀하가 행동했음을 의미합니다. 만약 엄격한 브랜치 보호 규칙이 승인된 PR이 main보다 뒤처져 있다고 한다면, 동일한 클릭은 GitHub의 update-branch 엔드포인트를 사용하고, 새로 고침 확인(check)이 실행되는 동안 자동 병합(auto-merge)을 대기열에 넣습니다. 그 결과는 병합된 것이 아니라 **대기열됨(queued)**으로 보고됩니다: 해당 행은 GitHub가 이를 병합할 때까지 '준비(Ready)' 상태로 자동 병합 대기열됨 표시를 유지합니다. 만약 main이 먼저 다시 이동한다면, GitHub의 자동 병합은 오래된 브랜치에서 중단되고; 해당 행은 대기열됨 · main보다 뒤처짐으로 읽히며 버튼이 **업데이트(Update)**로 바뀝니다. PR이 이미 지나간 커밋에 대해 스테이징된 검토(review)는 잘못된 커밋에 게시되는 대신 대체되었다고 간주되어 건너뜁니다. 이는 해당 명시적 클릭에 한정되며, 백그라운드 틱은 기여자 브랜치에 절대 쓰지 않습니다.명시적 결정(Decisions 섹션) — 예: *"#650으로 진행하고 #651은 대체됨으로 닫기"*와 같이 입력하고 Enter를 누릅니다. 서버는 이를 decisions.jsonl에 기록하고

decide.sh

을 실행합니다:

사용자의 텍스트를 해석하여 댓글, 라벨, 원장(ledger) 업데이트 등을 수행하는 집중적인 엔진 세션입니다. 명시적인 병합/닫기 지침은 서버 자체에 의해 실행됩니다 (엔진 세션은 해당 동사들을 기계적으로 거부하며; 이를 /api/terminal로부터 요청합니다).

/api/terminal은 의사 결정 실행자(decision executors)와 설정된 유예 기간 이후 변경되지 않은 steward 승인 PR의 좁게 검증된 실시간 틱 자동 병합에 대한 응답을 제공합니다. 만약 사용자의 텍스트가 안전하게 조치하기에는 너무 모호하다면, 추측하는 대신 명확한 설명을 요청하며 돌아옵니다. 틱이 실행되는 동안 입력된 결정은 steward가 자유로워지자마자 대기열에서 소진됩니다.해제(Dismiss) — 스테이징된 항목을 게시하지 않고 버립니다; 다른 모든 것과 마찬가지로 기록됩니다.

merge_ready.py