← back to AbramsEgo
memos/design-research.md
326 lines
# AbramsEgo Design Research
Living notes distilled from the design north-star sources (SPEC.md → @androoagi
"AI Agent Environment Tour"). Advisory only — Steve's hard UI rules (🕓 created
date+time chips, sort+density+infinite-scroll, cost labels, color-coded
thresholds) always win over borrowed aesthetics.
---
## androoagi
**Researched:** 2026-07-01 (task 30). **Cost: $0 (local)** — yt-dlp + ffmpeg +
frame reads, no metered APIs.
### What was obtained
- **TikTok (@androoagi): SUCCESS.** yt-dlp pulled the newest 8 videos from the
local IP with no anti-bot block → `~/Videos/design-research/androoagi/`
(~535 MB total). Titles: *AI Agent Ecosystem Tour 2* (2026-06-01, the
north-star video), *Skynet is Coming*, *The Most Important Skill You Can
Learn*, *3 Ethical AI Agent Business Ideas*, *AI Beginners Need To Hear
This*, *Ethical Ways to Make Money Using AI*, *AI Agents are an UNFAIR
Advantage*, *You are soon to be replaced by AI*.
- **Frame analysis:** 130 frames extracted from *AI Agent Ecosystem Tour 2*
(`ffmpeg -vf fps=1/3`, ~6.5-min video); 10 frames read spanning the full
runtime.
- **X (x.com/androoagi): BLOCKED.** WebFetch was permission-denied in this
session; curl gets only X's JS shell (no post content without a logged-in
browser); nitter.net mirror returned nothing. **Not fought further per
budget rail — Browserbase fallback is task 31's owner (≤$0.50, log to
cost-tracker).**
### What the Ecosystem Tour actually shows
It is NOT a conventional grid dashboard. Two-layer system, filmed off a
physical monitor (vertical phone crop):
1. **A spatial "agent village" world map** — dark starfield background; each
agent is a self-contained pixel-art "station"/room with its OWN strong color
identity (orange station, red station, blue, white/mono, green, magenta).
Stations are connected by conveyor/pipe-style paths with particles flowing
along them (work/data visibly moving between agents). The camera slowly
pans/zooms across the world; the selected station glows bright (blue) while
the rest dim.
2. **Green-CRT terminal chrome + panels** — thick green border framing the
viewport, a thin top metrics strip of small segmented gauges/readouts, and
monospace green-on-black panels:
- an **agent roster** ("9 Agents") with a gift-shop/lab metaphor per agent;
- a **GENERATION WINDOW**: 2×2 grid of output thumbnails, each captioned
with a name + a quantified stat ("...% render confidence"), with a
scrolling timestamped action log beneath;
- an **OUTPUT TERMINAL**: dense 3-column layout (text log | thumbnail
cards | stats), header metrics like `34 / 91% / 15 Live`, every section
inside a boxed, labeled frame.
Video ends on a landing page ("THE AGENT THAT GROWS WITH YOU") — he's selling
the aesthetic as a product; the tour itself is the demo.
### Patterns worth copying → AbramsEgo panel mapping
1. **Stable per-agent color identity** → *Fleet health*: give every pm2
process / launchd job / agent a persistent hue chip (golden-angle rotation,
same trick as /color) so entities are tellable apart at a glance across all
panels.
2. **Segmented mini-gauges in a thin always-on strip** → *Top metrics bar*:
render CPU/RAM/swap/disk as 10-cell segmented bars with bracketed monospace
labels, not plain numbers — reads instantly at small size, and cells map
naturally onto the SPEC's color-coded thresholds.
3. **Work visibly flowing** → *Activity feed*: motion communicates "alive."
Cheap version: new feed items slide in + a subtle pulse on the source
panel's header when its data changes (commit lands → Fleet pulses).
4. **Selected-entity glow / dim-the-rest** → all panels: clicking a card
focuses it (bright border) and dims siblings — the tour's strongest
focus cue.
5. **Quantified caption line on every card** → *Sessions & sub-agent runs*:
each card carries one stat caption (model + tokens/cost) exactly like the
"% render confidence" captions — aligns with the Always-Show-Costs rule.
6. **Boxed, labeled terminal frames** → panel headers styled as
`[ OUTPUT TERMINAL ]`-style labeled boxes with a header metrics row
(count / % healthy / N live) — a per-panel summary before the detail.
7. **(Stretch) Spatial map view** → an optional toggle view where each
agent/service is a room sized by activity with edges for recent
interactions (session → cron → cost). High effort; list-first is fine.
### What NOT to copy
- **Monochrome green-on-everything CRT palette** — kills threshold color
coding (green must mean "healthy," not "everything"). Keep the dark theme;
use green as ONE accent in a real status palette (green/amber/red).
- **Decorative pixel-art sprite density** — charming in a video, noise in an
ops surface Steve scans daily. Density should come from information, not
decoration.
- **Vertical/phone-crop composition** — AbramsEgo is a desktop admin surface.
- **No timestamps on cards** — the tour's cards show none; Steve's hard rule
requires 🕓 created date+time on every admin card. Do not inherit this gap.
### Apply next (build tasks consume this)
1. Segmented 10-cell gauges + bracketed monospace labels in the top metrics
bar (keep threshold colors).
2. Per-agent golden-angle hue chips in Fleet health, reused everywhere that
agent appears.
3. `[ PANEL NAME ]` boxed headers with a per-panel summary metrics row
(count / healthy% / live N).
4. Focus state: click card → glow + dim siblings.
5. One-stat caption line on session/sub-agent cards (model · tokens · $).
6. Slide-in + source-panel pulse on new activity-feed items.
7. (Deferred/stretch) spatial map toggle view.
8. (Task 31) Browserbase pass on x.com/androoagi posts (≤$0.50) + remaining
TikTok videos' frame pass if the X posts add design detail.
### Cost lines
| Item | Cost |
|---|---|
| yt-dlp profile pull (8 videos) | $0 (local) |
| ffmpeg frame extraction (130 frames) | $0 (local) |
| Frame reads (10) + curl attempts | $0 (local) |
| Browserbase/Exa | $0 — not used (deferred to task 31) |
---
## dropped-links
**Researched:** 2026-07-01 (task 31). **Cost: $0** — WebFetch and the Exa MCP
were both permission-blocked in the session, but every source fell to free
plumbing: all three X posts recovered via Twitter's public syndication CDN
(`cdn.syndication.twimg.com/tweet-result?id=<id>&token=<derived>` — token is
`((id/1e15)*π).toString(36)` minus zeros/dots), docs + READMEs via curl, and
repo architecture via the unauthenticated DeepWiki MCP endpoint
(`mcp.deepwiki.com/mcp`, JSON-RPC `ask_question`). No Browserbase, no Exa.
### Nous Research — Hermes Agent web search & extraction
Thread (2026-06-30): *"Hermes Agent now reads the web up to 60x faster and 49x
cheaper. Scraping backends pass clean content straight to the agent without
redundant processing steps; large pages are saved locally and paged on demand."*
Linked docs (hermes-agent.nousresearch.com → web-search feature page):
- Two model-callable tools — `web_search` + `web_extract` — behind a
**multi-provider backend matrix** (Firecrawl default, SearXNG, Brave, DDGS,
Tavily, Exa, Parallel, xAI/Grok), with a **per-capability split**: search
and extract can use different providers (free SearXNG search + paid
Firecrawl extract).
- **Size-driven extract pipeline:** <5k chars → raw pass-through, no LLM call;
5k–500k → single-pass summary via a cheap *auxiliary* model, capped ~5k out;
500k–2M → 100k-char chunks summarized in parallel then synthesized; >2M →
refused with a "use a more focused URL" hint. On summarizer failure it falls
back to the first ~5k of raw content instead of erroring.
- **Auxiliary-model cost routing:** extraction summaries default to the main
model but are explicitly routable to a cheap fast model so long-page reads
don't burn reasoning-model tokens.
**Patterns → AbramsEgo panels:**
1. **Tiered by-size processing** → *server.js snapshot collectors*: collectors
that read big JSONL ledgers (revenue-ledger, cost-ledger, activity) should
pass small files raw, summarize/aggregate above a threshold, and refuse
with a hint at silly sizes — never stream a 2M-char blob into a panel.
2. **Provider fallback ladder, free-first** → *research/build tasks*: exactly
what this task lived — WebFetch → nitter mirrors → syndication CDN → (Exa
only if all free rungs fail). Codified here so future tasks don't start at
the metered rung.
3. **Cheap-model auxiliary routing** → *build loop*: summarize/label jobs in
loop tasks should name a cheap model; decisions stay on the main model.
Pairs with the Always-Show-Costs rule.
4. **Quantified before/after framing** ("60x faster, 49x cheaper") → *landing
page copy* (task 35): every claim carries a number.
### @0xRaduan — DeepWiki study posts + the two repos
- Post 2038922136375492835 (2026-03-31), replying to @Fried_rice: *"can study
it with deep wiki now: deepwiki.com/instructkr/claude-code"*. That repo has
since been **renamed → `ultraworkers/claw-code`** (Rust, ~194k stars):
self-described as *"an agent-managed museum exhibit … developed and
maintained with no human intervention"* — the same species as AbramsEgo's
autonomous build-queue loop, at internet scale.
- Post 2043291064149438661 (2026-04-12) thread: *"how I research any topic on
the internet nowadays. TLDR on the best option for claude code statuslines:
**cship** by @MarieStephenLeo — OSS, written in Rust, shows you your 5h/7d
limits."* Repo: github.com/stephenleo/cship — Starship-style TOML-config
statusline for Claude Code: session cost, context usage, model, API usage
limits, per-module warn/critical thresholds, ≤10ms render budget.
**claw-code agent-environment architecture** (via DeepWiki MCP; the
deepwiki.com page itself is client-rendered JS — curl gets nothing):
- **AgentOutput manifest per agent run**, persisted as JSON explicitly so
external viewers can poll it: `agent_id, name, status, derived_state,
current_blocker, error, output_file, lane_events`.
- **LaneEvents** — lifecycle verbs `lane.started / lane.finished /
lane.blocked / lane.commit.created` — with reconciliation of contradictory
or out-of-order events into one deterministic truth.
- **derived_state taxonomy:** `working / finished_cleanable /
blocked_background_job / interrupted_transport`.
- **LaneOwnership `watcher_action` (Act / Observe / Ignore) + per-event
ConfidenceLevel** so downstream automation knows whether to act on an event.
**Patterns → AbramsEgo panels:**
1. **Manifest-per-run file contract** → *build-queue loop*: have
scripts/build-loop.sh write/update a per-task manifest JSON (status,
derived_state, current_blocker, commit hash, events) that the server.js
sessions/activity collectors read — far richer than inferring state from
tasks/ vs done/ vs failed/ directory moves.
2. **derived_state on cards** → *Sessions & build-queue panel*: cards show
working / blocked(+named blocker string) / finished-cleanable — "blocked"
with the actual blocker text beats a generic red dot.
3. **Lifecycle-verb event log** → *Activity feed*: normalize items to
started/finished/blocked/commit.created verbs; a confidence field keeps
noisy sources from triggering automation.
4. **cship's module+threshold model** → *top metrics bar / cost panel*:
per-module warn/critical thresholds with per-state colors (already SPEC'd);
add the **5h/7d API-limit readout** as a first-class stat next to session
cost — limits are the scarcest resource the loop consumes.
5. **DeepWiki MCP as a $0 research tool** for future repo-study tasks. Caveat
observed live: querying an unindexed/renamed repo name returns a
confidently wrong answer (the old `instructkr/claude-code` name produced a
garbage "Devin" citation) — always resolve the canonical repo name first
(GitHub API 301 follow), then ask.
**What NOT to copy:** claw-code is a CLI harness, not a dashboard — steal the
state/file contracts, not the Rust implementation. And its "no human
intervention" posture stops at AbramsEgo's rails: gated actions stay
Steve-gated; the manifest pattern must make approvals *more* visible, not
automate past them.
---
## norma-videos
**Researched:** 2026-07-01 (task 31). **Cost: $0 (own server, SSH read-only).**
**Index status: the :9891 index is DEAD.** Port 9891 on Kamatera is loopback-
only and now serves **recycledwallpaper.com** (port was reused); nothing
externally answers http://45.61.58.125:9891/. The video assets themselves
survive on Kamatera under `/root/.claude/skills/app-demo-video/output/`:
`norma-panels-tour/{email-center, saved-analyses, clients, gmail-crm,
outreach-playbook}`, `norma-analyzer-deep-usage`, `norma-email-analyzer`,
`norma-email-outreach` (plus older cuts in `/root/Projects/Norma/demos/`).
### The proven per-panel tour recipe (app-demo-video skill)
Each panel directory is a self-contained build:
```
narration.txt ~300–370 chars, one paragraph
voice.mp3 TTS of the narration (+ voice-padded.mp3)
page@<hash>.webm Playwright screen recording of the live panel
intro.mp4 title card
body.mp4 recording cut to narration length
captions.ass → body-cap.mp4 captions BURNED IN
concat.txt intro.mp4 + body-cap.mp4
<panel>.mp4 final artifact
```
Final files are tiny — **0.5–1.2 MB ≈ 30–60s per panel**; the long-form
`norma-analyzer-deep-usage.mp4` is 4.3 MB. The narration formula is worth
copying verbatim (email-center example): name the panel → one scope sentence
(*"every send, every campaign and every reply … unified in one queue"*) →
2–3 capability sentences (*"You can filter by status, by client … drill into
any thread"*) → close on the always-on stat (*"reply rates, opens and clicks
are tracked per message so you always know what is working"*).
### What transfers to the AbramsEgo landing (task 35 consumes this)
1. **One MP4 per SPEC panel**, 30–60s, named `<panel>.mp4` — a rack of short
per-panel tours, not one monolithic walkthrough.
2. **intro + captioned-body concat** structure; captions burned in, so the
landing can autoplay muted and still communicate.
3. **The narration formula** above; keep `narration.txt` beside each MP4 so
the landing renders the same text as copy under the player.
4. **≤1.5 MB per panel video** — proven size, fine to self-host from :9773
(no CDN, no external dependency).
5. **Regenerate against the live :9773 dashboard** with the app-demo-video
skill — the Norma set is the *format* reference, not content to reuse. And
since the :9891 index is dead, the AbramsEgo landing self-hosts its videos.
---
## Apply next (updated 2026-07-01, task 31 — supersedes the task-30 list)
1. ✅ Segmented 10-cell gauges + bracketed monospace labels in the top metrics
bar (keep threshold colors). *(task 40 — CPU/RAM/SWAP/DISK now render a
10-cell `.seg` gauge under the value, labels bracketed `[CPU]`, cell fill
inherits the good/warn/bad threshold class.)*
2. ✅ Per-agent golden-angle hue chips in Fleet health, reused everywhere that
agent appears. *(task 40 — `agentHue()` name-hash × 137.508° → stable hsl
chip on local-fleet rows, Kamatera-fleet rows, activity commit repos, and
sub-agent run projects.)*
3. ✅ `[ PANEL NAME ]` boxed headers with a per-panel summary metrics row
(count / healthy% / live N). *(task 40 — CSS `h2::before/::after` brackets
frame every panel header edge-to-edge; the per-panel summary metrics rows
already lived in each h2's muted span.)*
4. ✅ Focus state: click card → glow + dim siblings. *(task 40 — click a panel
→ accent glow, siblings dim to .45; click again or Esc clears; clicks on
links/inputs/sliders inside panels are ignored.)*
5. One-stat caption line on session/sub-agent cards (model · tokens · $) —
*needs the sessions collector to expose model+tokens per card; server-side,
not done in task 40's frontend pass.*
6. Slide-in + source-panel pulse on new activity-feed items.
7. Build-loop **per-task manifest JSON** (status / derived_state /
current_blocker / lifecycle events / commit) written by build-loop.sh,
read by server.js collectors. (claw-code)
8. Activity feed normalized to lifecycle verbs
(started/finished/blocked/commit.created). (claw-code)
9. Sessions panel: **5h/7d API-limit readout** next to session cost. (cship)
10. Snapshot collectors: tiered by-size handling of big JSONL ledgers —
raw / aggregate / refuse-with-hint. (Hermes)
11. **Task 35:** per-panel 30–60s MP4 tours via the app-demo-video skill —
narration formula, intro+captioned-body concat, ≤1.5 MB each, self-hosted
from :9773 with narration.txt beside each file. (Norma)
12. (Deferred/stretch) spatial map toggle view. (androoagi)
13. ~~Browserbase pass on x.com posts~~ **RESOLVED $0** — the syndication-CDN
trick got full post content; Browserbase not needed for X text posts.
### Cost lines (task 31)
| Item | Cost |
|---|---|
| X posts ×5 (syndication CDN) | $0 (free endpoint) |
| Hermes docs + READMEs (curl) | $0 |
| DeepWiki MCP queries ×3 | $0 (free endpoint) |
| Kamatera Norma asset survey (SSH) | $0 (own server) |
| Browserbase / Exa | $0 — not needed |