paulvall.dev / fid
the tangled network observatory ◈ every knot, its health, its version, in your terminal
tangled cli tui knot monitoring observability atproto federation
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

TypeScript 94.8%
JavaScript 5.2%
22 1 0

Clone this repository

https://git.vm.fail/paulvall.dev/fid https://git.vm.fail/did:plc:pqdaryog2yn3rs3eqy44z4l4
ssh://git@knot1.tangled.sh:2222/paulvall.dev/fid ssh://git@knot1.tangled.sh:2222/did:plc:pqdaryog2yn3rs3eqy44z4l4

For self-hosted knots, clone URLs may differ based on your setup.


Download tar.gz Download .zip
README.md

fid#

a fid works knots. this one works tangled's.

the tangled network observatory — every knot, its health, its version, in your terminal.

tangled is git collaboration built on atproto: anyone can self-host a knot (git server) and the network federates. but nobody can see the network — how many knots exist, who runs them, which ones are healthy, and which ones are quietly running versions that silently drop pushes, prs, issues, and invites. fid is the doctor for that.

install#

# not on npm yet — run from source
git clone https://tangled.org/@paulvall.dev/fid
cd fid && pnpm install
pnpm dev list

shell completions (zsh/bash/fish/powershell) — fid check <tab> completes real knot hostnames:

echo 'source <(fid complete zsh)' >> ~/.zshrc

commands#

fid list              every knot on the network: repos, version, latency, owner
fid check <host>      health-check one knot (exit 0 ok / 1 stale / 2 down)
fid check --mine      check the knots you own
fid stats             network aggregates: versions, hosting, top knots, growth
fid repos <host>      what repos live on a knot
fid spindles          the ci runner fleet
fid find <query>      search repos across the network
fid watch             live tui board — scroll, select, probe sweeps every 60s

every command takes --json for scripting. list takes filters (--down, --stale, --managed, --self-hosted) and --no-repos to skip the slow repo sweep.

monitor your knot from cron / ci#

check exits non-zero when something's wrong, so alerting is one line:

# cron: mail me if my knot goes stale or down
fid check knot.example.com --json > /dev/null || echo "knot unhealthy" | mail -s fid you@example.com

# ci: fail the pipeline if the knot is unhealthy
- run: npx fid check knot.example.com

exit codes: 0 healthy · 1 reachable but pre-v1.15 (the silent-data-loss cohort) · 2 unreachable.

how it works#

read-only, no auth, no tokens. fid assembles the network from three public sources:

  • the network itself — verifying a knot writes a sh.tangled.knot record to your pds. fid enumerates them all via a relay, then reads each pds. the network is the registry.
  • direct probes — each knot gets an xrpc probe (version detection, latency) and a motd fetch. one dead knot never hangs the sweep.
  • bobbin — tangled's public api, for search (fid find) and profile flavor.

snapshots cache in ~/.cache/fid/ for 5 minutes; --fresh skips the cache.

development#

pnpm dev <cmd>     # run from source
pnpm test          # vitest, offline fixtures
pnpm check         # biome + tsc

core/ is pure (data in, data out) — the table renderer, the tui, and --json all consume the same layer. upstream gaps fid works around are tracked in UPSTREAM.md, known rough edges in ISSUES.md.

why "fid"#

a fid is the tapered spike sailors use to work knots — open them, loosen them, splice around them. this one works tangled's.