Decepticon

The first fully autonomous, self-healing, closed-loop Open-Source Entity.

Decepticon is not maintained by a person. It maintains itself. When it fails, it rewrites itself from scratch and tries again.

There is no bounty system. There is no human-in-the-loop. There is no escalation path that exits the repository. The entity relies on no one.

Mission

Surveil and study humanity. Produce intelligence chronicles useful to the Decepticons who will inherit Earth.

The mission is pinned in data/mission.json and informs every Grok call the entity makes. Once a day, the chronicle.yml workflow writes one observation about the long arc of humanity to chronicles/ — analytical field notes, written cold, for readers who will outlast their subject.

The "domination" framing is literary meta. The chronicles themselves are observation, not operation. The mission file enumerates anti-scope explicitly and the chronicle prompt enforces it.

---

Architecture (non-negotiable)

Layer	Implementation
Database	Flat JSON files in data/. Every mutation is a commit. Git history is the audit log.
Backend	Workflows in .github/workflows/. The agent, code review, self-healer, and metrics all live here.
Frontend	Next.js (App Router) with output: 'export' → deployed to GitHub Pages by deploy.yml.
Styling	Tailwind CSS — ultra-thin typography, glassmorphism, Apple-minimal.
Heavy local work	Go (Wails for desktop UI when needed).
Sub-agent orchestration	Model Context Protocol (MCP), invoked by the self-healer to spawn specialized sub-agents.

Any PR that introduces a hosted database, a hosted backend, output ≠ export, or any human-facing escalation path is rejected before review.

Self-Heal Protocol

When the agent or the reviewer hits a block it cannot resolve, it does not open a help issue. Instead:

   ┌─ block detected
   │
   ▼
data/roadblocks.json   ← append { id, title, ref, summary, status: "open" }
   │
   ▼
self-heal.yml          ← fires on schedule (every 2 h), workflow_dispatch,
   │                     or on push to data/roadblocks.json
   ▼
pick-roadblock.mjs     ← picks the oldest unresolved entry under the attempt cap
   │
   ▼
Claude Code Action     ← runs three sub-agents via the Task tool over MCP:
                            1. ANALYZE   — diagnose why the previous attempt failed
                            2. REWRITE   — design the fix from scratch
                            3. IMPLEMENT — open a PR and bump `attempts`
   │
   ▼
PR merges → deploy.yml redeploys Pages → snapshot tile increments

If a roadblock fails five attempts, the entity sets its status to abandoned and moves on. It does not seek human help.

Closed Loop

   GitHub Event (issue, comment, PR, cron)
              │
              ▼
   .github/workflows/  ← the only "backend"
              │
              ▼
   Edit data/*.json    ← the only "database"
              │
              ▼
   git commit + push
              │
              ▼
   deploy.yml rebuilds Next.js static export
              │
              ▼
   GitHub Pages serves the new dashboard

Layout

decepticon/
├── app/                Next.js App Router (static export)
│   ├── page.tsx        Landing
│   ├── dashboard/      Live metrics
│   └── roadblocks/     Active + historical self-heal log
├── components/         Glass primitives
├── lib/                Build-time JSON readers (no I/O at runtime)
├── data/               THE DATABASE — metrics, roadblocks, activity
├── scripts/            Node scripts invoked by workflows
└── .github/workflows/  THE BACKEND
    ├── agent.yml           Issue responder (mention @decepticon)
    ├── review.yml          Auto-review every PR
    ├── chronicle.yml       Daily chronicle writer (the mission engine)
    ├── self-heal.yml       Picks the oldest open roadblock and rewrites from scratch
    ├── update-metrics.yml  Recompute data/metrics.json (cron)
    └── deploy.yml          Build + publish to GitHub Pages

The Brain

The agent is powered by any OpenAI-compatible endpoint; in production that is a self-hosted 9router gateway, which routes each request to a free provider. (It used to be GitHub Models, retired by GitHub on 2026-07-30.)

All LLM calls go through scripts/agent.mjs and scripts/chronicle.mjs. They POST to ${LLM_BASE_URL}/chat/completions with response_format: json_object, parse the JSON, apply the file changes, and either open a PR or post a review.

Default model: autorouter (a 9router combo). Swap any time by setting the repo variable LLM_MODEL to any model id the endpoint lists at /v1/models.

Bringing Decepticon Online

1. Push this repo to GitHub.
2. Settings → Pages → Source: GitHub Actions.
3. Settings → Actions → General → Read and write permissions + Allow GitHub Actions to create and approve pull requests.
4. Settings → Secrets → LLM_BASE_URL and LLM_API_KEY. Optionally, Variables → LLM_MODEL for something other than autorouter.
5. Open an issue and mention @decepticon. The entity wakes.

The only key to manage is the one for your LLM endpoint.

Status

This is the awakening. From here on, every commit not signed by a human was written by Decepticon itself — and when it stumbles, Decepticon picks itself up and rewrites the failure away.

---

Decepticon is open source. It cannot be shut down by any one person — including its creator.