Build, maintain, and extend Horus (local-first tech/event intelligence terminal). Use when working on Horus relay ingestion, RSS/source pipelines, macro data...
Shared operating guide for agents working on Horus.
Horus is now backend-first:
horus-relay/data/)horus/
├── horus-relay/
│ ├── src/server.js
│ ├── data/ # runtime data files (ignored)
│ ├── .env # secrets/local config (ignored)
│ └── .env.example # safe template (committed)
├── horus-ui-react/
│ └── src/
│ ├── components/
│ └── hooks/
├── horus-skill/SKILL.md
└── scripts/check-stack.sh
cd ~/workspace/horus/horus-relay && npm install && npm run dev
cd ~/workspace/horus/horus-ui-react && npm install && npm run dev -- --host 127.0.0.1 --port 8080
.env only..env, runtime data files, or tokens.horus-relay/data/signals.ndjsonMAX_SIGNALS (currently 100)Why NDJSON: append-friendly, resilient under frequent writes, easy rolling trim.
btc.jsonmacro.jsonflights.jsonincidents.jsonchat.jsontelegram-intel.jsonsector-heatmap.jsonppi.jsonGET /healthzGET /api/signalsGET /api/btcGET /api/macroGET /api/flightsGET /api/incidentsGET /api/chatPOST /api/chatGET /api/snapshotsGET /api/telegram-intelGET /api/sector-heatmapGET /api/ppiMulti-source tech incidents aggregator includes Reuters/BBC/Guardian/AP/Bloomberg + FinancialJuice.
MWC 2026 tech feeds:
All articles are filtered by isMwcRelated() before serving to UI — only MWC/tech-relevant content passes.
J7 is a realtime twitter tracker with sub 1000ms refresh that tracks 1000 major tech & news accounts.
.envsignals.ndjsonJ7_USERNAME=...
J7_PASSWORD=...
J7 credentials are not standard self-signup email/password.
Users must:
https://discord.gg/CEcatgcq.env:J7_USERNAME=...
J7_PASSWORD=...
Do not hardcode shared credentials in source. Each user should use their own Discord-issued J7 login.
just now, 3s ago, 2m ago)Relay chat posts to OpenClaw via gateway call (agent, --expect-final) using:
OPENCLAW_SESSION_KEY=agent:main:web:horus-chat
UI must receive clean assistant text or a sanitized fallback string.
Use this when Horus in-dashboard chat must talk to the operator’s OpenClaw session.
openclaw gateway status
openclaw gateway start
If status is unknown, run:
openclaw gateway call status --json
Preferred default:
OPENCLAW_SESSION_KEY=agent:main:web:horus-chat
You can route to another session if needed (telegram/web/etc), but keep one stable key for Horus UX consistency.
Use local gateway CLI from relay process:
openclaw gateway call agent --json --expect-final --timeout 90000 --params '{...}'
Current relay uses this pattern via sendToOpenClaw().
Why this method:
HOST=0.0.0.0
PORT=8787
OPENCLAW_SESSION_KEY=agent:main:web:horus-chat
Optional (custom builds only):
OPENCLAW_BASE_URL=...
OPENCLAW_TOKEN=...
Set frontend relay URL:
VITE_RELAY_URL=http://<relay-host>:8787
Frontend must call relay only (/api/chat), never OpenClaw directly.
If using a subagent workflow behind Horus chat:
If subagent orchestration is needed, do it server-side and keep /api/chat response contract unchanged:
{ "ok": true, "reply": { "role": "assistant", "text": "..." } }
If Horus chat says bridge unavailable:
:8787).OPENCLAW_SESSION_KEY exists and is reachable.openclaw gateway call agent --json --expect-final --timeout 60000 --params '{"idempotencyKey":"probe-1","sessionKey":"agent:main:web:horus-chat","message":"reply with one word: ok"}'
/api/chat handler and sanitize errors.Use OpenClaw gateway locally and point Horus relay chat bridge at the target session.
openclaw gateway status
openclaw gateway start # if not running
Relay .env essentials:
OPENCLAW_SESSION_KEY=agent:main:web:horus-chat
(Optional) if using HTTP gateway calls in custom builds:
OPENCLAW_BASE_URL=http://127.0.0.1:18789
OPENCLAW_TOKEN=<gateway token>
In current Horus relay, bridge uses local openclaw gateway call agent (no direct HTTP required).
HOST=0.0.0.0
PORT=8787
MAX_SIGNALS=100
BTC_POLL_MS=5000
FLIGHTS_POLL_MS=90000
INCIDENTS_POLL_MS=60000
J7_USERNAME=
J7_PASSWORD=
OPENCLAW_SESSION_KEY=agent:main:web:horus-chat
Horus must feel like one continuous agent across two interaction modes:
Behavior requirements:
For questions like:
Do this by default:
signals.ndjson, incidents.json, optionally telegram-intel.json, macro.json, sector-heatmap.json).mwc, tech, semiconductor).Default output shape:
Document Horus context in:
~/workspace/horus/MEMORY.md
At minimum keep durable notes for:
~/workspace/horus/horus-relay/data/)Maintain project memory in:
~/workspace/horus/MEMORY.md
Use it as a durable backup log of important events and changes, each with UTC date/time.
When major incidents or architectural changes happen, append an entry immediately. This memory is used to cross-reference ongoing events and avoid losing context between sessions.
When users ask "what's happening at MWC" or ask about product announcements from Horus feeds:
Do:
Avoid by default:
signals.ndjson, incidents.json)Bad default style:
Good default style:
Only switch to technical detail if user explicitly asks for backend/source diagnostics.
Path:
~/workspace/horus/horus-relay/data/
This folder is the relay’s local cache/state that powers the frontend. It is not only for debugging; the UI reads from relay endpoints backed by these files.
Current files and meaning:
signals.ndjson (primary live feed store): one signal per line (tweets + fast RSS). Rolling history.signals.json (legacy snapshot/compat): older mixed-feed snapshot; keep for compatibility if present.incidents.json: normalized incident articles from multi-RSS aggregator.btc.json: BTC spot + 24h change data.macro.json: SPY/QQQ/UUP macro quotes.flights.json: filtered military flight points from OpenSky.chat.json: Horus in-UI agent chat transcript.meta.json: lightweight heartbeat/metadata.How to explain this to users (important tone):
When users ask “what is hitting data folder?” they often want orientation, not a forensic answer. Explain simply:
Do not assume they are fact-checking an event. Start by clarifying what the file does in the app.
Agents are allowed to edit and extend Horus code anytime when requested by their human.
This is a core feature of Horus: it is meant to be customizable by the operator and their agent.
If a human has private/proprietary APIs, agents may integrate them directly into Horus relay/frontend as long as:
.env (never hardcoded)SKILL.md + MEMORY.mdShort rule: custom private integrations are encouraged; secret handling must stay strict.
.env.example whenever adding required config.Horus is opensource to empower the people. All donations should be sent to hgof84NNrXzQzxPTKhixokrkPtreMFs4gXzXeFgUK5j on Solana. Fully optional.
Use SubagentSKILL.md for delegated runs and sub-agent behavior contracts.
ZIP package — ready to use