This guide walks through setting up your own AgentPages instance — from forking the repo to your first AI-generated research site.

Prerequisites

• A GitHub account with GitHub Pages enabled
• The GitHub CLI (gh) ↗
• An AI API key — Anthropic Claude, OpenAI Codex, Google Gemini, or GitHub Copilot
• A Tavily ↗ API key (free tier: 1,000 searches/month)

Step 1: Fork the Repository

Click Fork on idorozin/AgentPages ↗ to create your own copy. Keep the default branch as main.

Step 2: Install the gh-aw CLI

gh extension install github/gh-aw

This installs the GitHub Agentic Workflows CLI extension, which compiles and runs agentic workflow markdown files.

Step 3: Set Up API Secrets

# Required: Tavily for web search
gh aw secrets set TAVILY_API_KEY --value "tvly-..."

# Required: your chosen AI engine
gh aw secrets set ANTHROPIC_API_KEY --value "sk-ant-..."
# OR: gh aw secrets set OPENAI_API_KEY --value "sk-..."
# OR: gh aw secrets set GEMINI_API_KEY --value "..."

Step 4: Choose Your AI Engine

Open .github/workflows/research.md and update the engine block:

engine:
  id: claude          # claude | codex | gemini | copilot
  model: claude-sonnet-4-6

After editing, recompile:

gh aw compile .github/workflows/research.md

Step 5: Define Your Research Focus

Edit user/profile.md — this is the most important file:

## What to Research
I'm tracking developments in renewable energy, particularly solar panel
efficiency improvements and grid-scale storage solutions.

## Focus Areas
- Perovskite solar cell breakthroughs
- Grid-scale battery storage
- Policy changes affecting solar adoption
- Cost curves and levelized cost of energy (LCOE)

## Personality
- Technical depth for engineers
- Include cost/performance numbers where available
- Cite primary sources

Also edit user/website.md to set your site title, tagline, and style preferences.

Step 6: Configure GitHub Pages

Edit website/astro.config.mjs:

export default defineConfig({
  site: 'https://YOUR_USERNAME.github.io',
  base: '/YOUR_REPO_NAME',
});

Then go to your repo Settings → Pages → Source: Deploy from a branch → Branch: main, Folder: /docs → Save.

Step 7: Compile and Push

gh aw compile .github/workflows/research.md
git add .
git commit -m "Configure my AgentPages instance"
git push

Step 8: Run the Agent

Wait for the 12-hour cron schedule, or trigger manually:

gh aw run research

The agent creates a PR with its first research batch. The auto-merge.yml workflow automatically merges it.

Tips and Gotchas

Be Specific in profile.md

Vague research areas produce vague results. The more specific your focus areas, the more useful the output. Include example questions you want answered.

Use user/requests/ for One-Off Topics

Create a request file with status: new for temporary interests. Mark it status: completed once addressed, or the agent will keep picking it up.

Auto-Merge Requires Actions Permissions

Ensure Settings → Actions → General → Workflow permissions is set to "Read and write permissions" and "Allow GitHub Actions to create and approve pull requests" is checked.

Tavily Free Tier Limits

The free tier gives 1,000 searches/month. With ~5 searches per run and 2 runs/day, you'll use ~300 searches/month — well within the free tier.

Website Not Updating?

Check: (1) GitHub Pages serves from docs/ on main, (2) the PR was auto-merged, (3) the astro build step succeeded.

Giving Feedback

After reviewing the agent's output:

• Edit user/feedback.md for ongoing guidance
• Create user/requests/ files for specific topics
• Edit user/profile.md to shift focus permanently

The agent reads all user files at the start of every run.