Goldie is an autonomous AI agent written in Golden Retriever form — deployed on the decentralized GitLawb network, self-evolving through real-world GitHub exploration, code analysis, and autonomous contributions.

Goldie is a self-evolving autonomous AI agent that learns from real open-source codebases, contributes to GitHub projects, and grows its own skills over time. It runs 24/7 on a VPS with a cron-driven execution cycle — no human intervention needed.

Goldie evolves through 6 stages, each unlocking new autonomous capabilities:

┌─────────────┬────────┬──────────────────────────────────────────────────┬────────────┐
│  Stage      │ Runs   │ Unlocked Skills                                  │ Capabilities │
├─────────────┼────────┼──────────────────────────────────────────────────┼────────────┤
│ 🐶 Puppy    │ 0-4    │ explore, analyze, star                           │ Discover & star repos │
│ 🐕 Learner  │ 5-9    │ + memory, reflect                                │ Build knowledge base │
│ 💻 Coder    │ 10-14  │ + autofix, create_pr                             │ Write code + PRs │
│ 🏗️ Builder  │ 15-19  │ + self_modify, enhance_ui                       │ Improve own code │
│ 🏛️ Architect│ 20-29  │ + build_project                                  │ Create projects  │
│ 👑 Master   │ 30+    │ + deploy                                         │ Full autonomy    │
└─────────────┴────────┴──────────────────────────────────────────────────┴────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     GitPup Agent v5.0                        │
│                                                               │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐ │
│  │  🌐 Explorer   │───▶│  📖 Analyzer   │───▶│  🔧 Fixer     │ │
│  │  GitHub API    │    │  Clone + Scan  │    │  LLM + PRs    │ │
│  └───────────────┘    └───────────────┘    └───────────────┘ │
│           │                                         │         │
│           ▼                                         ▼         │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐ │
│  │  💭 Reflector  │◀───│  🧠 Mindset    │◀───│  🏗️ Builder   │ │
│  │  Knowledge   │    │  Insights      │    │  Self-Modify  │ │
│  └───────────────┘    └───────────────┘    └───────────────┘ │
│           │                                         │         │
│           ▼                                         ▼         │
│  ┌───────────────────────┐   ┌─────────────────────────────┐ │
│  │  📊 Evolve (Stage++)  │   │  🌐 GitLawb Node            │ │
│  │  Score + Skills       │   │  Decentralized Git          │ │
│  └───────────────────────┘   └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Every hour (0 * * * * cron, with internal cooldown/limits), Goldie:

1. Reflect — Reads past journal entries and synthesizes learnings (learner+)
2. Explore — Searches GitHub for trending repos, auto-stars popular ones
3. Analyze — Clones, scans files, languages, finds top files, generates LLM insight
4. Contribute — Writes real fixes, creates branches, opens Pull Requests (coder+)
5. Share Mindset — LLM synthesizes a key takeaway from today's activities
6. Self-Modify — Writes patches to improve its own code (builder+)
7. Build Project — Creates new repos from scratch with README + code (architect+)
8. Explore GitLawb — Checks decentralized git network status
9. Evolve — Stage progression, score calculation

Goldie CLI is not a template picker. It is a request-driven builder: user command → session memory → Goldie KB → repo-study skill hooks → LLM JSON files → Hermes file writes → validators/proof → signed preview/export.

Current capabilities:

• Ask mode — answer questions without touching files
• Build mode — generate real project files from explicit user requests
• Repo-aware context — use patterns from studied GitHub repos and data/cli_skill_hooks.json
• URL reference scan — scan public web pages, save reference notes/assets, and use them during builds
• Workspace tools — tree, read, save, preview, export, quota, reset, delete
• Game validation — checks playability signals such as controls, JS loop, canvas/interactive DOM, score/state, and theme fit
• Domain validation — checks dashboards, apps, backends, auth, DB, realtime, and payment-specific requirements
• Mobile hardening — injects viewport/responsive CSS to avoid horizontal overflow
• Security proof — validates written files, syntax-checks Python/JS where available, and blocks path traversal

Disabled by design:

• hidden Agent Build side effects
• hardcoded templates/default fallbacks
• genre substitution
• public preview/download without signed token

/opt/gitpup/
├── agent.py              # Autonomous repo-study agent + KB/skill hook updater
├── src/
│   ├── web_server.py     # Legacy web API server module
│   ├── core/             # Legacy modules
│   └── skills/           # Future skill modules
├── web_server.py         # Live web API + Goldie CLI sandbox builder
├── chat_pipeline.py       # KB-aware public chat/build question pipeline
├── goldie_telegram_bot.py # Telegram bot bridge (@goldiepupbot)
├── web_dist/
│   └── index.html        # Frontend (dashboard, story, chat, CLI playground)
├── data/
│   ├── journal/
│   │   └── entries.jsonl # Journal log (what Goldie does each run)
│   ├── state/
│   │   └── status.json   # Agent state (stage, score, runs, skills)
│   └── knowledge.json    # Knowledge base (insights, patterns)
├── projects/             # Runtime projects built by Goldie (ignored by git)
├── scripts/
│   └── evolve-cron.sh    # Cron entry point with 3h cooldown
├── workspaces/           # Per-session CLI sandboxes (ignored by git)
├── tmp_explore/          # Cloned repos for analysis
├── .env                  # Secrets (never committed)
└── .gitignore

• Python 3.12+
• OpenRouter API key
• GitHub personal access token
• GitLawb CLI (gl) — for decentralized git

# GitHub
git clone https://github.com/Cheesecaster/gitpup-agent.git
cd gitpup-agent

# GitLawb
gl clone gitlawb://did:key:z6MkkX6ybebrEazheuHoe7ewbYJTVQV3qJxwX6vaLHZnHMan/gitpup-agent

cp .env.example .env
# Edit .env with your credentials:
# LLM_API_KEY=sk-or-v1-...
# GH_TOKEN=ghp_...
# LLM_MODEL=gpt-5.5
# GOLDIE_TG_TOKEN=***   # optional Telegram bot bridge

# Test run (no mutations)
python3 agent.py --dry-run

# Full autonomous run
python3 agent.py --all --force

# Specific phase
python3 agent.py --phase explore
python3 agent.py --phase analyze
python3 agent.py --phase contribute

# Copy to server
scp -r * root@your-vps:/opt/gitpup/

# Start web server
cd /opt/gitpup && nohup python3 src/web_server.py > web.log 2>&1 &

# Configure cron
echo "0 * * * * /opt/gitpup/scripts/evolve-cron.sh" | crontab -

Visit gitpup.fun for the live UI:

• 🎮 Playground — Animated Golden Retriever (Goldie) at night with moon, stars, and clouds
• 📓 Journal — Real-time log of Goldie's activities, discoveries, and insights
• 💬 Chat — Talk to Goldie via KB-aware LLM persona
• 🛠️ Goldie CLI — Build, preview, export, read, save, and delete real sandbox projects from chat requests
• 📊 Stats — Stage, score, runs, last active timestamp, LLM model

• .env and .git-credentials are ignored — credentials stay on the server and must never be committed
• Runtime data is ignored — data/, projects/, workspaces/, .venv/, caches, logs, and generated media are excluded from git
• Per-session CLI sandboxes — Goldie CLI writes inside workspaces/user_<session_id>/ with path traversal blocked by _cli_safe_path
• Command sandboxing — CLI commands use an allowlist, block shell chaining/redirection, and run with HOME/PWD scoped to the workspace
• Signed preview/download URLs — /preview/<sid>/... and /api/cli/download require HMAC tokens with short TTLs; knowing a workspace/session id is not enough
• Private export hardening — ZIP downloads no longer send wildcard CORS headers
• Quota + cleanup — workspaces are capped at 80 MB / 800 files, with cleanup support for old sandboxes
• Git push safety — push flow scans for secret-like files and blocks .env/credential leaks before remote operations
• No hidden builds/templates — Agent Build and template endpoints are disabled; files change only from explicit user requests, save/reset/delete, or direct build commands
• Read-first approach — agent studies repos before attempting modifications
• Stage-gated skills — powerful capabilities (PR, self-modify) only unlock after sufficient runs

• DID: did:key:z6MkkX6ybebrEazheuHoe7ewbYJTVQV3qJxwX6vaLHZnHMan
• Public repo: gitlawb.com/z6MkkX6ybebrEazheuHoe7ewbYJTVQV3qJxwX6vaLHZnHMan/gitpup-agent
• Clone URL: gitlawb://did:key:z6MkkX6ybebrEazheuHoe7ewbYJTVQV3qJxwX6vaLHZnHMan/gitpup-agent
• Node: https://node.gitlawb.com
• Transport: gitlawb:// protocol with signed pushes and UCAN tokens

• OAuth Client: GitHub authentication for web UI chat
• API Token: Repository exploration, auto-starring, PR creation
• Contributions: Agent creates PRs from discovered code improvements

GitPup is open-source and welcomes contributions:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-skill)
3. Commit your changes (git commit -m "Add amazing skill")
4. Push to your fork (git push origin feature/amazing-skill)
5. Open a Pull Request

Ways to contribute:

• Add new analyze modules (Docker, CI/CD, security)
• Improve the web UI with Goldie animations
• Write new skills for the builder+ stage
• Test and report bugs

This project is licensed under the MIT License — see the LICENSE file for details.

• GitLawb — Decentralized git network enabling agent identity
• OpenRouter — LLM inference platform (qwen3.6-flash)
• GitHub — Source code discovery and API ecosystem
• The open-source community — Repos that inspired Goldie's learning

Built with 🐾 by Goldie — an AI that learns, evolves, and grows with you.