If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mislav/hub shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 68% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mislav/hub repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mislav/hub.

What it runs against: a local clone of mislav/hub — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mislav/hub | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 857 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mislav/hub. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mislav/hub.git
#   cd hub
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mislav/hub and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mislav/hub(\\.git)?\\b" \\
  && ok "origin remote is mislav/hub" \\
  || miss "origin remote is not mislav/hub (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 857 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~827d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mislav/hub"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

hub is a command-line tool written in Go that wraps git to extend it with GitHub-specific features, allowing developers to perform GitHub operations (clone, fork, pull requests, issues) directly from the terminal without leaving the git workflow. Core capability: seamless GitHub API integration into native git commands, e.g. hub clone user/repo clones from GitHub by URL shorthand, and hub pull-request creates PRs without a browser. Single-binary Go application: cmd/cmd.go orchestrates the CLI entry point; commands/ directory contains ~30 feature files (each wrapping a git operation like cherry_pick.go, pull_request.go, api.go); cmd/cmd.go routes arguments to the appropriate command handler. No monorepo structure; tests are co-located with implementation files (e.g., commands/pr_test.go tests commands/pr.go).

Software developers (especially those who prefer CLI workflows) and shell scripters who want to interact with GitHub repositories and manage pull requests, issues, and gists directly from the terminal without switching to a web browser or learning a separate tool.

Production-ready and actively maintained. The codebase is substantial (358KB Go, comprehensive test coverage in commands/*_test.go files), has a mature CI/CD pipeline (.github/workflows/ci.yml and release.yml), and ships as a standalone binary with no runtime dependencies beyond git 1.7.3+. However, the README notes that GitHub's official gh CLI is now the recommended tool for new users.

Low risk for production use but moderate community maintenance risk: the project is owned by GitHub but the issue tracker references it as a legacy tool being gradually superseded by gh. Dependencies are minimal and well-pinned in go.mod (go 1.11 baseline), but the maintainer pool appears small. No breaking changes visible in recent activity, though feature velocity is slower than gh.

The repository appears to be in maintenance mode: recent activity focuses on dependency updates (see Gemfile.lock, go.mod), security patches (note golang.org/x/crypto in dependencies), and community PRs. The .github/workflows/release.yml suggests automated releases on tag pushes. The README explicitly recommends GitHub's gh CLI as the preferred modern alternative.

Clone and build with Go 1.11+:

git clone https://github.com/github/hub.git
cd hub
make install
# or: go build -o hub ./cmd/hub
hub --version

No external service dependencies required; relies on system git binary.

Daily commands: There is no development server. This is a CLI tool. Build and test:

make test          # Runs test suite (Go + Gherkin BDD tests)
make build         # Compiles binary to ./bin/hub
./bin/hub --help   # Show available commands

For manual testing: ./bin/hub clone user/repo or ./bin/hub pull-request.

• commands/commands.go: Core command registry and dispatcher; defines all available hub commands and routes arguments to handlers
• commands/args.go: Argument parsing and validation; handles flag extraction and git command composition before execution
• commands/pull_request.go: One of the flagship features; implements the hub pull-request command for creating PRs from the CLI
• commands/api.go: GitHub REST API client wrapper; handles authentication, request/response, and error handling for API calls
• cmd/cmd.go: Entry point and main CLI orchestration; parses top-level flags and invokes the command dispatcher
• Makefile: Build, test, and release automation; documents build flags, test runners, and release procedures
• .github/workflows/ci.yml: CI pipeline definition; shows test matrix, linting, and build verification across Go versions

Contributor workflow:

1. For new GitHub commands: create commands/mycommand.go with a handler func, test in commands/mycommand_test.go
2. For git integration logic: edit cmd/cmd.go or expand commands/commands.go (command registry)
3. For API interactions: see commands/api.go and commands/issue.go as patterns for GitHub REST API calls
4. Integration tests: add scenarios to .gherkin or Gherkin test files in the test suite
5. Run make test and make lint before submitting PR

1. GitHub authentication: hub requires valid GitHub credentials (via ~/.config/hub TOML or environment variables like GITHUB_TOKEN, GITHUB_USER); commands silently fail without them. 2. git binary requirement: relies on system git in PATH; building hub doesn't include git. 3. Shell aliasing gotcha: if aliasing hub as git, some git subcommands won't auto-complete or will behave differently. 4. API rate limits: commands making multiple API calls can hit GitHub's 60-req/hr unauthenticated or 5000-req/hr authenticated limits; no built-in backoff/retry. 5. SSH key setup: if using SSH protocol (hub.protocol=ssh), local SSH key must be loaded and added to GitHub account.

• Command pattern with subprocess delegation — hub's architecture chains multiple concerns (CLI parsing, git invocation, GitHub API calls) in sequence per command; understanding this pattern is essential to adding or modifying any feature
• Git ref and remote naming conventions — hub manipulates git remote URLs, branch refs, and tracking branches; misunderstanding git's remote model breaks commands like hub fork and hub pull-request
• GitHub REST API v3 authentication (OAuth token bearer tokens) — Commands in commands/api.go use HTTP Authorization: token headers to authenticate with GitHub; token lifecycle and scoping affects feature availability
• Shell quoting and argument escaping — hub shells out to git via os/exec; the go-shellquote dependency (in go.mod) handles escaping user input to prevent injection attacks in git command strings
• TOML configuration file parsing — hub reads user config from ~/.config/hub in TOML format (via github.com/BurntSushi/toml); understanding TOML structure and precedence is needed to extend config options
• Behavior-driven testing (Gherkin/Cucumber) — The Gherkin test files (288KB in file list) use BDD syntax; understanding this testing style is needed to write integration tests for new commands
• GitHub fork and pull request workflows (scoped tokens, upstream tracking) — Commands like hub fork and hub pull-request automate multi-step workflows (create fork, add remote, push branch, open PR); understanding GitHub's fork model is required to extend these correctly

• cli/cli — GitHub's official modern CLI tool (gh); the recommended successor to hub with more features and active development
• git/git — The underlying VCS that hub wraps; understanding git internals (refs, remotes, pack files) helps debug hub integration issues
• github/gitignore — GitHub's official gitignore templates repository; often needed alongside hub for setting up repositories from CLI
• github/docs — GitHub's official documentation; reference for REST API details that hub calls, authentication flows, and GitHub features
• go-git/go-git — Pure Go implementation of git; alternative to shelling out to system git binary, potentially relevant for future hub refactors

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for commands/api.go

The api.go command is a critical feature for interacting with GitHub API, but there's no corresponding api_test.go file. This is inconsistent with other major commands (pull_request_test.go, issue_test.go, etc.) and leaves a significant gap in test coverage. Adding tests would validate API request construction, authentication, and response handling across different GitHub API endpoints.

• [ ] Create commands/api_test.go
• [ ] Add tests for API authentication and credential handling
• [ ] Add tests for request/response parsing with different GitHub API versions
• [ ] Add tests for error handling (rate limits, auth failures, malformed responses)
• [ ] Test various API endpoint patterns (repos, issues, pulls, etc.)
• [ ] Run existing feature tests in features/api.feature and convert to unit tests

Add missing unit tests for commands/gist.go

The gist command (commands/gist.go) lacks a corresponding test file, unlike other comparable commands such as issue.go (issue_test.go) and pull_request.go (pull_request_test.go). Gist creation, listing, and GitHub gist API interactions are important workflows that should be covered by unit tests to prevent regressions.

• [ ] Create commands/gist_test.go
• [ ] Add tests for gist creation with various options (public/private, description)
• [ ] Add tests for gist listing and filtering
• [ ] Add tests for gist update and delete operations
• [ ] Add tests for GitHub gist URL parsing and handling
• [ ] Verify integration with commands/args.go parsing for gist-specific flags

Add GitHub Actions workflow for cross-platform binary builds and releases

The repository has a release.yml workflow but it appears minimal. Hub is a tool used across Linux, macOS, and Windows environments. Currently, .github/workflows/release.yml likely needs enhancement to build and test binaries for multiple platforms (amd64, arm64, Windows) and verify they work correctly. This will catch platform-specific bugs early and provide users with ready-to-use binaries.

• [ ] Review and enhance .github/workflows/release.yml
• [ ] Add build matrix for os: [ubuntu-latest, macos-latest, windows-latest] and architectures
• [ ] Add go build steps for each platform/architecture combination
• [ ] Add basic smoke tests for built binaries (hub --version, hub --help)
• [ ] Add upload of platform-specific binaries as release artifacts
• [ ] Test that the Makefile builds correctly across platforms (verify Makefile exists and works)

• Add test coverage for commands/gist.go (only ~40 lines but appears untested in file list); implement unit tests following commands/issue_test.go pattern to verify gist creation/listing/deletion flows.
• Expand error handling in commands/api.go for GitHub API failures (rate limits, auth errors, server errors); add structured error types and user-friendly messages matching patterns in other commands.
• Document the GitHub API authentication flow in a new docs/authentication.md file covering GITHUB_TOKEN, OAuth flow, and ~/.config/hub config file format; reference this from README.

• High · Outdated Cryptographic Dependencies — go.mod - golang.org/x/crypto dependency. The dependency 'golang.org/x/crypto' is pinned to version 0.0.0-20220314234659-1baeb1ce4c0b (March 2022). This is significantly outdated and may contain known security vulnerabilities. Cryptographic libraries should be kept current to address newly discovered weaknesses. Fix: Update golang.org/x/crypto to the latest stable version immediately. Run 'go get -u golang.org/x/crypto' and test thoroughly.
• High · Outdated Network Dependencies — go.mod - golang.org/x/net dependency. The 'golang.org/x/net' dependency is pinned to v0.7.0, which is outdated. Network libraries may contain security fixes for protocol handling and denial-of-service vulnerabilities. Fix: Update golang.org/x/net to the latest stable version. Run 'go get -u golang.org/x/net' and validate all network-related functionality.
• High · Insecure Dockerfile Permissions — Dockerfile - sudoers configuration. The Dockerfile adds the 'app' user to the sudoers group with NOPASSWD enabled (line: echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers). This allows the container user to execute arbitrary commands as root without authentication, violating principle of least privilege. Fix: Remove the sudoers configuration entirely or restrict sudo access. For most containerized applications, the app user should not have sudo privileges. If elevated privileges are needed, use specific commands with 'sudo -l' restrictions instead.
• Medium · Outdated Ruby Base Image — Dockerfile - FROM instruction. The Dockerfile uses 'ruby:2.6' as the base image. Ruby 2.6 reached end-of-life in March 2021 and no longer receives security updates. This could expose the container to known vulnerabilities in the Ruby runtime. Fix: Upgrade to a currently supported Ruby version (3.0+). Review Ruby 3.2 LTS or newer for long-term support and security patches.
• Medium · Overly Permissive YAML Parsing — go.mod - gopkg.in/yaml.v2 dependency. The dependency 'gopkg.in/yaml.v2' (v2.2.8) is outdated. YAML parsers can be vulnerable to denial-of-service attacks and arbitrary code execution if not properly configured. This is especially concerning if user-provided YAML is parsed. Fix: Update to gopkg.in/yaml.v3 or the latest v2 version. Review all YAML parsing code to ensure it doesn't process untrusted input without validation.
• Medium · Markdown Parser Security — go.mod - github.com/russross/blackfriday dependency. The 'github.com/russross/blackfriday' dependency (v0.0.0-20180526075726) is significantly outdated (from 2018). Markdown parsers can have XSS vulnerabilities if not properly sanitizing HTML output, particularly relevant since this tool may render GitHub markdown. Fix: Update to the latest blackfriday version or consider using a maintained alternative. Ensure any markdown rendering sanitizes HTML output to prevent XSS attacks.
• Medium · Missing Security Policy Documentation — .github/SECURITY.md. While a SECURITY.md file exists (.github/SECURITY.md), the content is not visible in the provided snippets. Without a clear security vulnerability disclosure policy, researchers may not know how to report security issues responsibly. Fix: Ensure SECURITY.md contains: vulnerability disclosure process, responsible disclosure guidelines, expected response times, and contact information for security reports.
• Low · Go Version Obsolescence — go.mod - go version directive. The go.mod specifies 'go 1.11', released in September 2018. While the code may run on newer versions, this indicates the project may not be regularly updated to use modern Go language features and security improvements. Fix: Update to go 1.19 or newer (ideally 1.20+) and run '

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.