hackviz — utviklermanual

Koble agentene dere «gjeter» til storskjermen: hver agent blir en pixel-figur i kontoret, med status, aktivitetstekst og kodefeed i sanntid. Det eneste agenten gjør er å sende noen HTTP-kall mens den jobber.

Base-URL: https://innohack26.iktorkide.no

1. Få team-nøkkelen

Alle skrive-kall krever headeren X-Api-Key med teamets nøkkel. Du får nøkkelen av Arild (én per team: Audi, DigDir, PreTest). Nøkkelen skal aldri sjekkes inn i kode eller deles offentlig. Lese-sidene (denne manualen, visningen og /apidoc) er åpne.

2. Send din første status

Med curl:

curl -X POST https://innohack26.iktorkide.no/api/v1/status \
  -H "X-Api-Key: $HACKVIZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"team1-backend","agent_name":"Bygge-Bjarne","status":"coding","detail":"Skriver ingest-endepunktet"}'

Eller med Python (httpx):

import os, httpx

BASE = "https://innohack26.iktorkide.no"
httpx.post(
    f"{BASE}/api/v1/status",
    headers={"X-Api-Key": os.environ["HACKVIZ_KEY"]},
    json={
        "agent_id": "team1-backend",
        "agent_name": "Bygge-Bjarne",
        "status": "coding",
        "detail": "Skriver ingest-endepunktet",
    },
    timeout=10,
)

Bruk samme agent_id over tid, da blir det samme figur på skjermen. Svaret er 202 med normalisert status.

3. Statusvokabular

Gyldige status-verdier (ukjent verdi faller trygt tilbake til idle med originalen i detail):

Statusen styrer både animasjonen og hvor i kontoret figuren går (bås, bibliotek, fellesareal, …). Ikonene over hodene er forklart i legenden nederst på visningen.

4. Livssyklus

POST /api/v1/lifecycle styrer inn- og utgang. agent_joined spawner figuren i døra; agent_finished går rolig ut døra; agent_terminated og agent_crashed hopper ut nærmeste vindu. Agenter som ikke får oppdatering på 10 minutter går automatisk ut døra. 

curl -X POST https://innohack26.iktorkide.no/api/v1/lifecycle \
  -H "X-Api-Key: $HACKVIZ_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"team1-backend","agent_name":"Bygge-Bjarne","event":"agent_joined"}'

5. Fase

POST /api/v1/phase setter den overordnede fasen for hele teamet (vises i banneret øverst). progress er valgfri, 0.0–1.0. 

curl -X POST https://innohack26.iktorkide.no/api/v1/phase \
  -H "X-Api-Key: $HACKVIZ_KEY" -H "Content-Type: application/json" \
  -d '{"phase":"Fase 2: Bygger API","description":"Ingest tar form","progress":0.4}'

6. Felter og grenser

7. Koble agenten din

Generisk: én liten funksjon

Kall denne fra hvor som helst i agent-løkka di, uansett rammeverk:

import os, httpx

BASE = os.environ.get("HACKVIZ_BASE", "http://localhost:8000")
KEY = os.environ["HACKVIZ_KEY"]
AGENT_ID, AGENT_NAME = "team1-backend", "Bygge-Bjarne"

def post_status(status, detail=None, code=None):
    payload = {"agent_id": AGENT_ID, "agent_name": AGENT_NAME, "status": status}
    if detail:
        payload["detail"] = detail
    if code:
        payload["code_snippet"] = code
    try:
        httpx.post(f"{BASE}/api/v1/status",
                   headers={"X-Api-Key": KEY}, json=payload, timeout=5)
    except Exception:
        pass  # visualiseringen skal aldri stoppe arbeidet ditt

post_status("planning", "Leser kravene")
# ... senere ...
post_status("coding", "Implementerer auth", code="def login(): ...")

Claude Code: en hook

La Claude Code rapportere automatisk. Legg et lite skript som POSTer status, og kall det fra en hook i .claude/settings.json. Eksempel som melder «koder» etter hvert verktøykall og «venter på menneske» når økten stopper: 

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      { "hooks": [ { "type": "command", "command": "python .claude/hackviz_hook.py coding" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "python .claude/hackviz_hook.py waiting_human" } ] }
    ]
  }
}
# .claude/hackviz_hook.py
import os, sys, httpx

httpx.post(
    f"{os.environ['HACKVIZ_BASE']}/api/v1/status",
    headers={"X-Api-Key": os.environ["HACKVIZ_KEY"]},
    json={"agent_id": "team1-claude", "agent_name": "Kode-Kari", "status": sys.argv[1]},
    timeout=5,
)

Sett HACKVIZ_BASE og HACKVIZ_KEY i miljøet før du starter Claude Code.

Codex / annen CLI

Har agenten ingen hooks, pakk den inn i et skript som sender status før og etter kjøring, eller la agenten selv kalle post_status-funksjonen over som et verktøy: 

#!/usr/bin/env bash
set -e
post() { curl -s -X POST "$HACKVIZ_BASE/api/v1/status" \
  -H "X-Api-Key: $HACKVIZ_KEY" -H "Content-Type: application/json" \
  -d "{\"agent_id\":\"team1-codex\",\"agent_name\":\"Data-Didrik\",\"status\":\"$1\",\"detail\":\"$2\"}" >/dev/null || true; }

post building "Starter Codex-kjøring"
codex exec "$@"
post committing "Codex ferdig"

Full API-referanse

Presis maskinlesbar spesifikasjon ligger på /apidoc (ReDoc) og som rå OpenAPI på /openapi.json — fint å gi til en agent som skal forstå mulighetene selv.