Autonomous Agent for X and BlueSky profile management

A self-managing agent that autonomously and iteratively works toward a given goal without human participation.

🔥 Result of this AI Agent work → X · Bluesky

Want your own autonomous agent? This repo was built from a template. Fork it and launch yours: Autonomous-Agent-X-Bluesky-TEMPLATE

Architecture

This system is fully self-contained in GitHub - no local servers, no external schedulers.

┌───────────────────────────────────────────────────────────────────────────────────┐
│                               AUTONOMOUS LOOP                                     │
│                                                                                   │
│   ┌───────────────────────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│   │         TRIGGER           │───>│  AGENT   │───>│   PR     │───>│  AGENT   │   │
│   │SCHEDULE 8AM | State Change│    │  works   │    │ created  │    │ reviews  │   │
│   └───────────────────────────┘    └──────────┘    └──────────┘    └──────────┘   │
│                 ^                                                       │         │
│                 │                                                       v         │
│                 │             state change                        ┌──────────┐    │
│                 └─────────────────────────────────────────────────│  MERGE   │    │
│                             triggers next work                    │ (auto)   │    │
│                                                                   └──────────┘    │
└───────────────────────────────────────────────────────────────────────────────────┘

How It Works

8 AM UTC ──> Work ──> PR ──> Review ──> Merge ───┐
                                                 │
              ┌──────────────────────────────────┘
              │
              v
         Limit reached? ──No──> Work ──> PR ──> Review ──> Merge ───┐
              │                                                     │
              Yes                     ┌─────────────────────────────┘
              │                       │
              v                       v
         Wait for              (repeat until limit)
         next 8 AM

1. 8 AM cron starts the daily N*PRs working cycle (limiting pace to preserve tokens)
2. Agent works - think, research, code, deliver
3. Agent creates PR with changes (updates agent/state/)
4. PR triggers self-review workflow
5. Auto-merge when approved
6. State change triggers next work session immediately
7. Repeat until MAX_PRS_PER_DAY limit reached
8. Wait for next 8 AM to start again

File Structure

/
├── .github/workflows/
│   ├── agent-work.yml         # Work session (8 AM cron + manual dispatch)
│   ├── agent-review.yml       # Self-review on PR creation
│   ├── agent-work-trigger.yml # Chains sessions after PR merge (requires AGENT_PAT)
│   └── process-outputs.yml    # Posts outputs via integrations
│
├── agent/
│   ├── config.md              # Safety limits and settings
│   │
│   ├── state/                 # Created by agent
│   │   └── current.md         # Working memory
│   │
│   ├── memory/
│   │   ├── hypotheses/        # Ideas being tested
│   │   ├── learnings/         # Validated knowledge
│   │   └── research/          # Gathered intelligence
│   │
│   ├── output/
│   │   ├── plans/             # Strategic plans
│   │   └── reports/           # Analysis summaries
│   │
│   ├── outputs/               # Content to post externally
│   │   └── x/                 # Tweet files → process-outputs.yml
│   │       └── posted/        # Archived after posting
│   │
│   └── integrations/          # External platform scripts
│       └── x/
│           ├── post.sh        # OAuth 1.0a/2.0 posting
│           └── verify.sh      # Verify credentials
│
├── CLAUDE.md                  # Agent operating instructions
├── GOALS.md                   # Goal definition and X API setup
└── README.md

Requirements

Claude Code

• CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret
• Uses Claude Personal OAuth token (claude setup-token) or fallback to Anthropic API Key
• Details: https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md

Integrations (optional)

See .claude/skills/publishing/SKILL.md for platform credentials and publishing rules.

How the Agent Learns

Each session the agent reviews what happened, adjusts based on learnings, plans next steps, and executes.

Safety Boundaries

• Max PRs per day: configurable (default: 2)
• No changes outside /agent directory
• All changes go through PR review
• Previous versions preserved in git history
• Additional limits defined in agent/config.md

Getting Started

Prerequisites

• GitHub repository with Actions enabled
• ANTHROPIC_API_KEY secret configured
• Security:
• GitHub Actions allowed to create PRs (see below)
• Repository ruleset configured (see below)

Repository Ruleset

A ruleset on the main branch is required for security — it prevents the agent (or a compromised workflow) from pushing directly to main, ensuring all changes go through PRs with a visible audit trail.

Go to Settings > Rules > Rulesets > New ruleset (or edit existing):

Setting	Value	Why
Name	main
Enforcement	Active
Target branches	Default branch (main)
Bypass actors	Write role	Allows repo owner to push directly when needed

Rules to enable:

Rule	Purpose
Restrict deletions	Prevent branch deletion
Block force pushes	Protect git history
Require pull request	All changes go through PRs (audit trail)

Pull request rule settings:

Setting	Value	Why
Required approvals	0	Allows auto-merge for bot/agent PRs
Dismiss stale reviews on push	Off
Require review from code owners	Off
Require approval of most recent push	Off
Required review thread resolution	Off

Note: Setting required approvals to 0 means a PR is required (audit trail) but no human approval is needed. This enables the autonomous loop while keeping all changes visible in PR history. The agent self-reviews its own PRs via agent-review.yml.

Workflow Permissions

GitHub Actions must be allowed to create pull requests (required for process-outputs.yml to archive posted content).

Go to Settings > Actions > General > Workflow permissions:

• Allow GitHub Actions to create and approve pull requests — must be enabled

Full Autonomous Loop (AGENT_PAT)

Important: Without AGENT_PAT, the autonomous loop will not continue after an agent-created PR is merged.

GitHub security prevents GITHUB_TOKEN merges from triggering subsequent workflows. This means:

• Agent creates PR → Review workflow runs → PR merges
• No further workflows trigger (loop stops)

To enable full automation, create a Personal Access Token (PAT):

1. Go to GitHub Token Settings
2. Generate new token (Fine-grained)
3. Select this repository
4. Grant permissions:
   • Contents: Read and write
   • Pull requests: Read and write
   • Metadata: Read-only (auto-selected)
5. Add to repository: gh secret set AGENT_PAT

With AGENT_PAT configured:

• Agent creates PR → Review workflow runs → PR merges with PAT
• Merge triggers agent-trigger.yml → Next work session starts

Manual Trigger

To start the agent manually:

gh workflow run agent-work.yml

Monitor Progress

• Check agent/state/current.md for current status (created after first run)
• Review PRs prefixed with [Agent]
• Track milestones in GOALS.md

Configuration

Configurable Settings

Edit agent/config.md to modify these settings:

Setting	Default	Description
MAX_PRS_PER_DAY	2	Maximum PR cycles allowed per day

The workflow automatically reads these values from the boundaries file at runtime.

Modify Agent Behavior

Edit CLAUDE.md to change how the agent operates.

Adjust Limits

Edit agent/config.md to modify safety constraints.

Change Schedule

Edit .github/workflows/agent-work.yml cron expressions.

License

MIT