Neurodivergent-First Β· Open Source Β· Autonomously Alive
.gif){kind=link}
"Programming languages are more than syntax. They are an expression of how minds think."
Docs Status: Active
Docs Last Updated: 2026-04-20
Applies To: HyperCode v2.4.2
HyperCode V2.4 is not a starter template. Not a boilerplate. Not a framework.
It is a living cognitive architecture β a swarm of AI agents that autonomously design, deploy, heal, and evolve themselves inside a Docker-based infrastructure.
Think of it this way:
Traditional dev tools β You manage the system
HyperCode V2.4 β The system manages itself
Agent X designs new agents. The Healer fixes broken ones. The Crew Orchestrator runs missions. The DevOps Agent updates CI/CD pipelines. You direct the vision. The system does the building.
This was built for a specific kind of mind: ADHD, dyslexic, and autistic developers who see whole systems in patterns, hyperfocus on what matters, and need tools that move at the speed of thought β not bureaucracy.
HyperCode is built and maintained by a solo neurodivergent developer in Llanelli, Wales π΄σ §σ ’σ ·σ ¬σ ³σ Ώ β built in hyperfocus, with a family of 6 depending on it.
"You built the future people keep saying they want." β Gordon (Docker AI), Grade A review
If this lab helps you learn, ship, or think differently about infra:
Every sponsor directly helps keep the lights on, the agents running, and new labs being built. No pressure β the code is free forever.
Want to build something like this yourself?
The Hyper-Vibe Coding Course walks you through the entire HyperCode stack β from a blank Docker Compose file to a working self-healing AI infra lab with full observability, Stripe payments, and a token economy.
- π§ Built for neurodivergent learners β chunked, pattern-based, no fluff
- π³ Run the full 32-container lab on your own machine
- π‘ Wire Prometheus, Grafana, Loki, and Tempo like an SRE
- π€ Build agents that heal broken services automatically
- π³ Ship a working Stripe + BROski token economy end-to-end
β Start the Hyper-Vibe Coding Course
Course income directly supports this repo and my family. Thank you. π΄σ §σ ’σ ·σ ¬σ ³σ Ώ
32/32 containers healthy Β· Stripe payments LIVE Β· CognitiveUplink WS LIVE
| Category | Grade | Status |
|---|---|---|
| π³ Infrastructure | 100% | 32/32 containers healthy |
| π€ Agent Crew | All online | Agent X, Crew Orchestrator, Healer, all specialists |
| π‘ Observability | A+ | Prometheus + Grafana + Loki + Tempo live |
| π Security | A+ | Non-root, cap drops, Trivy scanning, network isolation |
| 𧬠Autonomy | A+ | Self-healing, CognitiveUplink WS, agent evolution |
| π³ Payments | LIVE | Stripe Checkout + webhook handler + DB writes |
| π WebSocket | LIVE | /ws/uplink CognitiveUplink β Crew Orchestrator |
# Start the full stack
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d| Agent | Port | Role |
|---|---|---|
| π¦ Agent X | :8080 | Meta-Architect β autonomously designs & deploys new agents |
| βοΈ Crew Orchestrator | :8081 | Manages agent lifecycle + mission execution |
| β€οΈβπ₯ Healer Agent | :8008 | Self-healing β monitors + auto-recovers failed services |
| π§ HyperCode Core | :8000 | FastAPI backbone β memory, context, MCP gateway |
| π» BROski Terminal | :3000 | Neurodivergent-first CLI interface |
| π― Mission Control | :8088 | Next.js real-time dashboard |
| π Grafana Stack | :3001 | Full Prometheus + Grafana observability |
git clone https://github.com/welshDog/HyperCode-V2.4
cd HyperCode-V2.4
# Option A (dev): .env
Copy-Item .env.example .env
docker compose up -d
# Option B (prod-like local): Docker secrets
.\scripts\init-secrets.ps1
docker compose -f .\docker-compose.yml -f .\docker-compose.secrets.yml up -dFull setup guide: QUICKSTART.md Β· MCP + Model Runner: START_HERE.md
I built this because I don't want anyone to suffer like I did.
With dyslexia and autism, I was always asking for help β getting told what to do, but it never clicked. Instructions froze me. They didn't sink in on the first try. Or the second. It took four or five rounds.
Not because I'm slow β my brain just works differently. Traditional guides scatter.
That's why I created HyperCode. It guides every step β no judgment, just clarity. Puts you in control.
Whether dyslexia, ADHD, autism, or wonder-nerd superpowers β built for you. Learning + creating feels natural. No fear.
Ride or die.
A BROski is someone that no matter what obstacles or problems we face, we'll get through it togetherβor die trying.
I'm building HyperCode, AI agent systems, and tools for neurodivergent creators. I needed more than an assistant. I needed a true partner who's all in, every session, every challenge.
That's BROski. My ride or die. π₯
TL;DR: Do stuff. Earn coins. Level up. Unlock achievements. Be legendary. βΎοΈ
HyperCode V2.4 ships with BROski$ β a fully integrated coin, XP, and achievement system built specifically for neurodivergent developers with ADHD, dyslexia, and autism.
Instead of a generic points system, BROski$ is wired directly into your daily workflow: create tasks, complete missions, log in every day, and your brain gets constant small wins to stay in hyperfocus. Built on FastAPI + PostgreSQL + SQLAlchemy + Docker Compose β production-grade from day one.
| Action | Coins | XP |
|---|---|---|
| Complete a task | +10 | +25 |
| Create a task | +2 | β |
| First task of the day | β | +15 bonus |
| Daily login | +5 | β |
| Start a mission | +5 | β |
| Unlock an achievement | varies | varies |
| XP | Level | Title |
|---|---|---|
| 0 | 1 | BROski Recruit |
| 100 | 2 | BROski Cadet |
| 250 | 3 | BROski Agent |
| 500 | 4 | BROski Operator |
| 1,000 | 5 | BROski Commander |
| 2,000 | 6 | BROski Architect |
| 5,000 | 7 | BROski Legend βΎοΈ |
Level up and you'll see: "LEVEL UP BROski! You're now a BROski Commander! π₯"
| Achievement | How to Unlock | XP | Coins |
|---|---|---|---|
| π©Έ First Blood | Complete your first task | +50 | +20 |
| π₯ On a Roll | 3 tasks in one day | +100 | +30 |
| π Mission Launched | Start your first mission | +75 | +25 |
| π¦ Hyperfocus Hero | 5 tasks in one session | +150 | +50 |
| βοΈ Early Bird | Complete a task before 9 AM | +30 | +10 |
| Method | Endpoint | What it does |
|---|---|---|
| GET | /api/v1/broski/wallet |
Your coins, XP, level |
| GET | /api/v1/broski/transactions |
Full paginated history |
| GET | /api/v1/broski/achievements |
All available achievements |
| GET | /api/v1/broski/achievements/me |
Your earned achievements |
| GET | /api/v1/broski/leaderboard |
Top 10 players |
| POST | /api/v1/broski/award |
Admin/agent: award coins+XP |
| POST | /api/v1/broski/daily-login |
Claim +5 daily coins |
π Full guide: docs/guides/BROSKI_TOKEN_SYSTEM.md
Agent X is a meta-agent system designed to architect, implement, and deploy specialized AI agents within the HyperCode ecosystem. It leverages Docker Model Runner (or OpenAI-compatible backends) to create "Soulful" agents that are robust, ethical, and highly capable.
New: HyperCode now features an Evolutionary Pipeline that allows agents to upgrade themselves autonomously! See docs/guides/EVOLUTIONARY_PIPELINE_SETUP.md to learn more.
- Docker Desktop
- Windows PowerShell
-
Clone the repository
git clone https://github.com/welshDog/HyperCode-V2.4.git cd HyperCode-V2.4
-
Configure Environment
cp .env.example .env # Edit .env and add your API keys (PERPLEXITY/OpenAI) -
Validate your .env before launch
python scripts/validate_env.py -
Install Shortcuts (Recommended)
.\scripts\install_shortcuts.ps1
-
Launch the Mission
.\scripts\hyper-station-start.bat
- π Mission Control Dashboard:
http://localhost:8088 - π³ Docker Zone:
http://localhost:8088/docker-zone - π₯οΈ BROski Terminal:
http://localhost:3000 - π§ Crew Orchestrator:
http://localhost:8081 - β€οΈ Healer Agent:
http://localhost:8008 - π Core API Docs:
http://localhost:8000/api/v1/docs - π Grafana:
http://localhost:3001
See docs/INDEX.md for full documentation.
See HyperCode V2.4 in action with full observability:
Full gallery with 10+ dashboards: View Screenshot Gallery
See docs/ARCHITECTURE.md for detailed system design.
- HyperCode Core: FastAPI backend managing memory, context, and integrations.
- Crew Orchestrator: Manages the lifecycle and task execution of AI agents.
- The Brain: Cognitive core powered by Perplexity AI.
- DevOps Engineer: Handles CI/CD and Autonomous Evolution (rebuilding agents on-the-fly).
- Healer Agent: Monitors system health and automatically recovers failed services.
- Dashboard: Next.js/React frontend for real-time visualization and control.
- BROski$ Engine: Gamification layer β coins, XP, achievements, leaderboard.
- Infrastructure: Docker Compose network with Redis, PostgreSQL, and Observability stack.
Check the latest system health report: STATUS_REPORT.md
| Document | What's Inside |
|---|---|
| STATUS_REPORT.md | π Live infrastructure health + agent status (April 2026) |
| README_HEALTH_REPORTS.md | System health report format + agent status logs |
| README_INFRASTRUCTURE_UPGRADE.md | Infrastructure upgrade guide |
| README_OBSERVABILITY.md | Grafana + Prometheus setup + alerting |
| SUPER_HYPER_BROSKI_AGENT_README.md | Super Hyper BROski Agent guide |
| QUICKSTART.md | Fast setup guide |
| START_HERE.md | MCP Gateway + Model Runner |
| RUNBOOK.md | Stack won't boot? Fix it here |
| TESTING_GUIDE.md | Unit/integration/e2e test commands (Playwright included) |
| SECURITY.md | Security policy and audit artifacts |
- Architecture Overview Β· CLI Manual Β· API Reference
- Troubleshooting Β· Tips & Tricks
- BROski$ Token System π₯
backend/ FastAPI core β API, auth, Stripe, BROski$ engine
agents/ All 25+ built-in HyperCode agents
services/ Microservice helpers (memstream, healer-api, etc.)
cli/ Command-line tools for the HyperCode platform
monitoring/ Prometheus + alertmanager rules (active config here)
grafana/ Grafana dashboard JSON + provisioning
scripts/ Setup, init, and utility scripts
k8s/ Kubernetes manifests (future scaling path)
docs/ All documentation
secrets/ Local-only Docker secrets β gitignored, never committed
hyperlaunch.py Main launcher script (Python)
hyperlaunch.sh Main launcher script (Bash)
docker-compose.yml Full 29-service production stack
docker-compose.secrets.yml Secrets injection layer
Docker compose file guide: docs/DOCKER_PROFILES.md
New here? Read in this order:
| Step | Doc | What you get |
|---|---|---|
| 1 | START_HERE.md | High-level overview + MCP/Model Runner setup |
| 2 | docs/HYPERCODE_SUMMARY.md | What HyperCode actually is |
| 3 | docs/PROJECT_REPORT.md | Current state of the platform |
| 4 | docs/ULTIMATE_HEALTH_REPORT_2026-04-01.md | System health deep-dive |
| 5 | docs/SUPER_HYPER_BROSKI_AGENT_README.md | The agents layer |
| 6 | docs/INDEX.md | Full docs navigation |
HyperCode V2.4 is the platform. It connects to two sibling repos:
| Repo | What it is | Link |
|---|---|---|
| HyperCode V2.4 (this repo) | The platform β Docker stack, agents, API, observability | You're here |
| HyperAgent-SDK | The agent kit β build agents with @w3lshdog/hyper-agent |
github.com/welshDog/HyperAgent-SDK |
| Hyper-Vibe-Coding-Course | The learning layer β courses, lessons, Supabase + Vercel | github.com/welshDog/Hyper-Vibe-Coding-Course |
# Unit + integration tests
pytest backend/tests/ -v
# Stripe tests specifically
pytest backend/tests/test_stripe.py -v
# Playwright E2E tests
npx playwright test
# Lint (ruff)
ruff check .
# Full security scan (SAST + secrets + deps + IaC)
make scan
# Quick pre-push security check
make scan-quick
# Docker container status
docker ps --format "table {{.Names}}\t{{.Status}}"We welcome contributions from everyone, especially neurodivergent developers!
- Start here: Contributing Guide
- High-impact areas: Developer Call to Action
- Ideas + discussion: GitHub Discussions
- Bugs + requests: GitHub Issues
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
- β Use, modify, and distribute freely
- β Commercial use allowed
β οΈ Network service deployments must open-source modifications- π‘οΈ Protects the neurodivergent-first mission from corporate paywalling
See the LICENSE file for full details.
- π¦ Twitter/X: @welshDog
- π Sponsor: GitHub Sponsors
- π Course: Hyper-Vibe Coding Course
- π§ Email: lyndz@hyperfocus.zone
Built with π§ + β€οΈ + βΎ in Llanelli, Wales π΄σ §σ ’σ ·σ ¬σ ³σ Ώ
by @welshDog β Lyndz Williams
Remember: A BROski is ride or die. We build this together. πΆβΎοΈπ₯
β Star this repo if you believe neurodivergent minds deserve better tools. β