Skip to content

About

Static dashboard for agent work. Fixed layout slots from config.json; collectors write data.json; one render writes HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

FlightDeck

FlightDeck is a static dashboard for agent work. Ten slots stay in a fixed layout. config.json chooses which widget fills each slot. Collectors write data.json. One render command writes a single HTML file.

The renderer and collectors use the standard library only. Clone this repo and run the commands from the root.

Render the demo

The public demo is a static illustration of publicly released work from my repos. The page title is FlightDeck. Streams are FlightDeck, OpenMausBot, pi-agentic-driver, pi-bowerbird, and Demeter. Pull requests and notes link to public GitHub pages. Activity counts and the cluster chart are examples stored in examples/demo/data.json. That file is static. Rendering it does not collect from GitHub. The architecture slot is architecture.diagrams, with public FlightDeck, OpenMausBot, pi-bowerbird, and Demeter fieldnotes stubs.

The banner is examples/demo/assets/banner.webp. Swap in your own banner.webp beside your config if you wish to bring your own. The banner keeps its natural aspect.

./publish.sh

That runs the pre-render hooks, then writes dist/local/index.html and copies the demo assets beside it. With no GitHub owner and no root data.json, the hooks skip and examples/demo/data.json stays as it is in git. Open dist/local/index.html in a browser. The same render is scripts/publish_local.sh.

python3 -m flightdeck.render examples/demo/config.json examples/demo/data.json dist/local/index.html

Do not deploy a Worker for this public demo.

FlightDeck walkthrough: banner, cluster, activity, streams, decisions, steps, merges, and architecture

Explore the full dashboard tour above, including the interactive architecture diagrams. Watch the video or view the dashboard still. To preview locally (leave the file offline; do not upload a Worker):

./publish.sh
python3 -m http.server --directory dist/local 8765

Config

Copy config.example.json to config.json. Every slot is required. An unknown slot or widget id stops the render with ConfigError. empty hides a slot. assets_dir is relative to the config file (the demo uses assets/). Optional banner.alt is the image description. Optional timezone is an IANA name (the demo uses Europe/London).

Slot What it holds
banner Banner image
cluster Host or GPU readings
activity Commits and pull requests, this hour and this week
streams Who is working on what
decisions Open yes/no items
steps Human checklist
merges Pull request queue
priorities Focus per stream
settled Already decided
architecture Optional diagrams

Widgets

Widget id Role
banner.image Embeds banner.webp from the assets directory
cluster.gpu GPU / cluster readings from data.json spark
metrics.generic CPU, memory, and disk bars from data.json metrics
activity.github Hourly and weekly commit and pull request counts
streams.table Stream rows
decisions.cards Open decisions
steps.checklist Human steps
merges.table Merge queue
priorities.list Priority items
settled.list Settled today
architecture.diagrams Architecture embeds
empty Hide the slot

The demo sets cluster to cluster.gpu and architecture to empty. config.example.json sets cluster to metrics.generic for a machine without GPU readings. Use architecture.diagrams when you have diagrams. empty leaves a slot out.

The demo weekly block is the current week, so the column reads This week. A weekly block from an earlier week, without sample, shows zeros and Collecting. activity_weekly.sample keeps stored counts after Friday 17:00 and labels that column Example. A live collector does not set sample.

Refresh data.json before rendering again:

FLIGHTDECK_GH_OWNER=you GITHUB_TOKEN=... python3 -m collectors.activity --data data.json
python3 -m collectors.metrics_generic --data data.json

FLIGHTDECK_GH_OWNER has no default. Unset, the activity collector writes nothing. Collectors and sync hooks also refuse to write examples/demo/data.json, so the illustration stays static even if that path is passed as --data. Point collectors at your own data.json.

Sync hooks

./publish.sh and scripts/publish_local.sh run hooks/pre-render.d before they render. Each hook calls a collector or a script in scripts/. The scripts reconcile data.json from files in .cache/. They do not invent counts, ready state, or activity. Hook 02b-merge-sidecars reads optional CREW_TRACKER_SIDECAR_DIRS (colon-separated directories) and merges their bot-reports.json and responses.json into the evidence caches before hooks 03-reconcile-responses and 40-apply-bot-reports. Sidecar files remain read-only; missing directories skip.

Copy config/sync.example.json to config/sync.json (gitignored). Set the GitHub owner, the public repos you merge, the primary stream label, and the responses KV ids there, or set the same values in the environment (FLIGHTDECK_GH_OWNER, FLIGHTDECK_PUBLIC_REPOS, FLIGHTDECK_STREAM_LABEL, FLIGHTDECK_RESPONSES_KV_ID, CLOUDFLARE_API_TOKEN). The field list is in the sync skill at docs/skills/.

Repository evidence covers every repository pushed within repo_evidence.days (14 by default), not only repositories with a bot. Streams and priorities use repository facts. Green drafts get an explicit Undraft and merge step. Decisions use current checks and head identity, including private repositories in your own tracker. The static demo shows an example green-draft step, not live readiness.

Existing sync helpers handle PR normalization and response history. Separate repository scripts add commits and branch coverage because bot reports cannot cover repositories without bots.

The new collector uses read-only GitHub requests and retains a failed repository's last successful collection date. Local Herdr and Treehouse evidence is off by default. To enable it, set repo_evidence.local.enabled and explicitly list workspaces or repository checkout paths in your ignored sync config. Excluded workspaces are never inspected. Do not publish private tracker data.

Preview changes without writing data or caches:

python3 scripts/reconcile_repo_panes.py --data data.json --dry-run --diff

Use --panes streams,priorities to limit reconciliation. The collector accepts --owner, --days, --since, --include, --exclude, --out, --offline, and --no-mac. Offline fixtures use generic repository metadata and REST responses in repo-evidence-fixtures.json within the configured cache directory. Without fixtures, offline replay never renews evidence dates. Architecture retains its original diagram age and pending state even when repository collection succeeds.

With FLIGHTDECK_GH_OWNER unset and no data.json in the repo root, every hook skips. examples/demo/data.json stays as it is in git, and the render still works offline.

FLIGHTDECK_CLUSTER=metrics collects CPU, memory, and disk. FLIGHTDECK_CLUSTER=spark copies .cache/spark.json into data.json spark. It does not open SSH. Unset, the cluster hook skips. The demo keeps the readings already in the demo data file.

./publish.sh --build is the local render. ./publish.sh --deploy uploads a Worker and needs site/site.json on that machine. Do not point it at the public demo placeholders.

Deploy

Local folder: docs/deploy-local.md. scripts/publish_local.sh writes dist/local/index.html.

Cloudflare Workers: docs/deploy-cloudflare.md. scripts/publish_cloudflare.sh is a dry-run that embeds that HTML into a flightdeck-demo Worker. Real account ids, zone ids, Access emails, and KV ids stay in site/site.json on your machine. The repo only has placeholders in site/site.example.json. The optional architecture_kv_id binds CREW_ARCHITECTURE; deploy uploads changed architecture HTML views to that namespace. Leave it unset to skip uploads. For ./publish.sh --deploy, an existing CREW_TRACKER_CF_TOKEN_FILE (default ~/.cloudflare_token) supplies a token only when CLOUDFLARE_API_TOKEN is unset. The token is passed only to KV uploads and Wrangler; the file should be mode 600.

License

MIT

About

Static dashboard for agent work. Fixed layout slots from config.json; collectors write data.json; one render writes HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages