README

Project 2: GitHub Workflow Agent

A conversational agent that connects to the GitHub REST API and helps you understand and manage your repository workflow — triage issues, summarize PRs, and answer questions about recent activity.

---

What It Does

You talk to the agent in plain English. It decides which GitHub API tools to call, reads the results, and gives you a clear summary. Examples:

• “What are my three oldest open issues and what do they have in common?”
• “Summarize the pull requests waiting for review.”
• “What changed in the codebase this week?”
• “Are there any issues labeled ‘bug’ with no assignee?”

All tools are read-only — the agent cannot modify your repository.

---

Architecture

User prompt
    |
    v
Agent loop (ReAct-style, max 15 steps)
    |
    |-- Claude decides which tool to call
    |
    |-- Tool is executed (GitHub REST API via requests)
    |   |
    |   |-- list_open_issues(repo, limit)
    |   |-- get_issue_details(repo, issue_number)
    |   |-- list_open_prs(repo, limit)
    |   |-- get_pr_diff(repo, pr_number)
    |   `-- get_recent_commits(repo, days)
    |
    `-- Result fed back to Claude -> next step or final answer

Each tool call is printed:  "-> Calling list_open_issues..."

The agent uses Claude’s native tool-use API. Claude picks the right tool, reads the result, and decides whether it needs more information or can answer.

---

Skills Covered

Module	Concept
03 — Agents	ReAct-style loop with stop conditions
04 — Tools	Tool schemas, tool dispatch, result injection
09 — Production	Max-step guard, error propagation, env-var config
10 — Claude Code Patterns	Streaming, structured JSON tool schemas

---

Setup

1. Install dependencies

cd projects/02-github-agent
pip install -r requirements.txt

2. Create a GitHub personal access token

Go to https://github.com/settings/tokens and create a fine-grained token with:

• Repository permissions: Contents (read), Issues (read), Pull Requests (read), Metadata (read)

You only need read access — this agent never writes.

3. Create a .env file

ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=github_pat_...
DEFAULT_REPO=owner/repo-name    # e.g. torvalds/linux or your own repo

---

Usage

python agent.py

Or set the repo inline:

DEFAULT_REPO=myorg/myrepo python agent.py

Sample session

GitHub Agent ready. Repo: myorg/myrepo
Type 'quit' to exit.

You: What are the 5 oldest open issues?
-> Calling list_open_issues(repo='myorg/myrepo', limit=10)
   Got 10 issues.

The 5 oldest open issues are:

1. #12 — "Database connection pool exhausted under load" (opened 8 months ago, labels: bug, backend)
2. #18 — "Add dark mode support" (opened 6 months ago, labels: enhancement, ui)
...

The common theme among the oldest issues is that they are either infrastructure-level bugs
or large feature requests that require significant design work before implementation.

You: Give me the diff for PR #47
-> Calling get_pr_diff(repo='myorg/myrepo', pr_number=47)
   Got diff (2341 chars).

PR #47 "Refactor auth middleware" modifies auth/middleware.py and tests/test_auth.py.
The main change is extracting JWT validation into a standalone verify_token() helper...

You: quit
Goodbye!

---

Safety Notes

• The agent is strictly read-only. All five tools only make HTTP GET requests.
• Your GitHub token is read from the environment — it is never logged or sent to Claude.
• Diffs are truncated to 3000 characters to avoid blowing the context window.
• The agent loop caps at 15 steps to prevent runaway execution.
• Rate limiting: GitHub’s REST API allows 5000 requests/hour for authenticated users. The agent is conservative — a typical conversation uses 3–5 API calls.

---

Extension Ideas

Idea	Effort	Notes
Write operations	Medium	Add create_issue, add_comment behind a --allow-writes flag
Daily digest	Small	Schedule agent.py to answer “summarize today’s activity” and email/Slack the result
Multi-repo	Medium	Accept a list of repos; aggregate issues across all of them
PR reviewer	Large	Post a structured Claude review as a PR review comment
Webhook mode	Large	Trigger the agent on new issue/PR events via a GitHub webhook
Org-wide triage	Medium	Use the GitHub search API to find all issues across an org

---

Interview Demo Script

1. Point the agent at any public repo (your own, or a well-known OSS project).
2. Ask: “What are the three oldest open issues and what do they have in common?”
3. Show the ReAct trace — every -> Calling ... line demonstrates the agent reasoning step by step.
4. Ask a follow-up: “Show me the details on the first one.”
5. Ask: “What changed this week?” — demonstrates multi-tool reasoning.
6. Explain: why tool-use instead of just asking Claude to generate an answer? (Real-time data, accuracy, no hallucination of issue numbers.)

---

File Reference

File	Purpose
agent.py	All agent logic — tool definitions, loop, REPL
requirements.txt	Python dependencies
.env	API keys and repo config (never commit this)