Spark
Sign In
Tool

Explore tragedy-of-the-commons dynamics with AI coding agents

Fish Banks Sandbox is an offline tragedy-of-the-commons fishery simulation, hackable with an AI coding agent.

Get this
Works with github
github
Own this? Claim it

Maintainer of this project? Claim this page to edit the listing.

91
Spark score
out of 100
Updated last month
Version 1.0.0
Add to Favorites

Why it matters

Teach systems thinking and policy design by providing an interactive, agent-ready simulation of shared-resource collapse that developers can run locally, break open with AI coding assistants, and extend to model their own domains.

Outcomes

What it gets done

01

Run headless simulations to find collapse thresholds and test policy interventions

02

Extend the model with new policy levers like taxes, quotas, or dynamic pricing

03

Let AI agents play as fishing companies to observe emergent goal-misalignment

04

Re-skin the fishery dynamics to model your domain's shared-resource problems

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/bayramannakov-fishbanks-sandbox | bash

Overview

Fishbanks Sandbox

Fish Banks Sandbox is an offline tragedy-of-the-commons fishery simulation, packaged with an engine you can explore and extend using an AI coding agent. Use it to see how shared-resource collapse is driven by structure - a build delay and a cash-maximizing goal - not by any one team's greed.

What it does

Fish Banks - Policy Sandbox packages the tragedy-of-the-commons fishery simulation from an AI + Systems Thinking workshop into a fully offline, no-login tool: each of several fishing companies chases its own cash by buying and sailing ships, and collectively they can overfish a shared ocean stock to collapse. The engine (in fishbanks.js) is three pure functions - fishBanksParams, fbNewState, stepRound - ported and tuned from Dennis Meadows' classic model, with a carrying capacity of 6,000, a maximum sustainable yield of about 8,688 per round, and a commons-cliff threshold of about 75 ships at sea.

When to use - and when NOT to

Use it to see, hands-on, that the fishery's collapse is driven by structure - a shared stock, a one-round ship-build delay, and a "maximize my cash" goal - rather than by any one team being greedy: with 3 teams the ocean collapses once any team buys 3 or more ships per round, and with 4 teams at buy 3-4. It ships a CLAUDE.md/AGENTS.md so an AI coding agent already understands the engine, with suggested prompts to run explore.mjs and explain a collapse threshold, add a policy lever (supply-demand pricing, a ship tax, cap-and-trade quotas, a purchase subsidy), or replace the decision function with an LLM playing one company per round to watch it strip-mine the ocean when told to maximize cash versus maximize catch without collapse.

Inputs and outputs

Input: a per-team decision each round - buy, toSea, sendNewToSea - where buy is ships ordered (they cost $25k and arrive next round) and toSea moves ships from port to sea. Output: the round's result (fish stock, catch per ship, each team's cash, ships at sea or in port, bankruptcy) plus updated simulation state.

import { fishBanksParams, fbNewState, stepRound } from './fishbanks.js';

const P = fishBanksParams();        // tuned constants (K=6000, costs, regen curve)
let state = fbNewState(P, 4);       // 4 teams, 4800 fish to start
// one round = 3 simulated years; a decision per team:
const decisions = state.teams.map(() => ({ buy: 5, toSea: 99, sendNewToSea: true }));
const result = stepRound(state, decisions, P);   // mutates `state`, returns this round's outcome

Run it live at bayramannakov.github.io/fishbanks-sandbox, offline by opening index.html directly with no server or install, or headless with node explore.mjs to print the collapse threshold, your game versus one defector, and the enforced-quota cure straight from the engine.

Integrations

Runs entirely client-side - index.html is the sandbox UI (sliders, presets, live charts) backed by draw.js canvas helpers, with no backend or account required. Designed to be extended by an AI coding agent (Claude Code or Codex) using the bundled CLAUDE.md/AGENTS.md context, and MANUAL.md and FISHBANKS-SPEC.md document the full model, parameters, equations, the Meadows leverage map, and the live classroom multiplayer architecture it's derived from.

Who it's for

Educators and students of the AI + Systems Thinking course's Fish Banks workshop, and anyone who wants a hands-on, hackable systems-thinking example - re-skinnable to groundwater management, API rate limits, ad-auction CAC, or shared codebase tech debt while keeping the same collapse dynamics.

Source README

🐟 Fish Banks - Policy Sandbox

The simulation you played in the workshop, packaged so you can play with it and break it open with your AI coding agent. Same verified engine, no login, runs fully offline.

It's a tragedy-of-the-commons model: each fishing company chases cash; collectively they can overfish a shared ocean to collapse. The lesson isn't "be nice" - it's that the structure (a shared stock + a build delay + a "maximize my cash" goal) drives the collapse, and only the right rule prevents it.

Want the detailed step-by-step (running locally, reading the charts, troubleshooting, extending)? See MANUAL.md.

Want the full model + multiplayer-architecture spec (parameters, equations, the Meadows leverage map, the 3 escapes, and how the live classroom game is built)? See FISHBANKS-SPEC.md.

Your cohort never collapsed it (room 8305: ocean survived, +$23.6M). But that was low fishing pressure + luck, not safety. You averaged ~1 ship bought/team/round - below the threshold. If any one team had floored it to buy-5, the shared ocean dies and everyone goes bankrupt. Your restraint was only as good as the least restrained player. This package lets you prove that to yourself in 10 seconds.

Play it now (no setup)

Live (GitHub Pages): https://bayramannakov.github.io/fishbanks-sandbox/
Hit the ▶ Your cohort preset, then flip 😈 …now one of you defects.

Run it locally

Just open index.html - double-click it (or drag it into a browser tab). It's fully self-contained, so it works straight from your disk with no server and no install.

Explore headless (the fun part)

node explore.mjs

Prints the collapse threshold, your real game vs. one defector, and the enforced-quota cure - straight from the engine. Then go edit it.

The model in 30 seconds

Three functions, all pure, in fishbanks.js:

import { fishBanksParams, fbNewState, stepRound } from './fishbanks.js';

const P = fishBanksParams();        // tuned constants (K=6000, costs, regen curve)
let state = fbNewState(P, 4);       // 4 teams, 4800 fish to start
// one round = 3 simulated years; a decision per team:
const decisions = state.teams.map(() => ({ buy: 5, toSea: 99, sendNewToSea: true }));
const result = stepRound(state, decisions, P);   // mutates `state`, returns this round's outcome
// result.fish, result.catchPerShip, result.teams[i].roundCatch
// state.fish, state.teams[i].cash / shipsSea / shipsPort / bankrupt

A decision is { buy, toSea, sendNewToSea }:

  • buy - ships ordered this round (they cost $25k and arrive next round - the build delay that causes overshoot).
  • toSea - move ships from port to sea (99 = send them all). Ships at sea earn; ships in port idle cheaply.

Key numbers (engine-verified): carrying capacity 6,000, max sustainable yield ~8,688/round (regen peaks at 70% density), the commons cliff is ~75 ships at sea, a sea ship breaks even at 25 t/yr. With 3 teams it collapses at buy ≥ 3/team; with 4 teams at buy ≥ 3-4.

Explore with your agent (Claude Code / Codex)

This folder ships a CLAUDE.md / AGENTS.md so your agent already knows the engine. Open the folder in Claude Code or Codex and try:

Warm-ups

  • "Run explore.mjs and explain why buy-2 survives but buy-3 collapses."
  • "Find the exact MSY by sweeping a constant total catch per round."
  • "Plot the fish stock for buy-4 as ASCII in the terminal."

Add a policy lever

  • "Add supply-demand pricing: make fish sell for more as they get scarcer. Does collapse happen sooner or later? Why?" (it speeds up - scarcity rewards fishing harder)
  • "Add a ship tax and a cap-and-trade quota. Which one sustains the fishery with the least lost profit?"
  • "Add a subsidy on ship purchases and show it guarantees collapse."

Make it agentic

  • "Replace the decision function with a call to an LLM - let Claude play one fishing company each round, given only what a real player sees (its own cash + catch, not the stock). Watch it strip-mine the ocean."
  • "Now change only the goal you give the LLM from 'maximize my cash' to 'maximize total catch over 50 years without collapse.' Does it self-restrain? This is the whole point: the optimizer obeys the goal, not your intent."

Make it yours

  • "Re-skin this as [your domain] - groundwater / API rate limits / ad-auction CAC / shared codebase tech-debt. Keep the same dynamics, rename the variables."

Files

File What
index.html the sandbox UI (sliders, presets, live charts)
fishbanks.js the simulation engine - pure functions, the source of truth
draw.js tiny canvas chart helpers (used by index.html only)
explore.mjs headless policy explorer + your starting point for extensions
MANUAL.md full step-by-step instruction manual (run, read, extend, troubleshoot)
CLAUDE.md / AGENTS.md context for your AI coding agent

From the AI + Systems Thinking course, Workshop 5 (Fish Banks). Model ported & tuned from Dennis Meadows' classic; engine validated round-by-round. Have fun breaking it.

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.