KnoSky turns any repo or folder into an explorable city and grounds your AI in your own source.
Stop paying for thrash. Stop uploading the estate. Prove what the map of your repo did.
Website ↗ · Docs ↗ · Install · Outcomes · In the box · Enterprise path · Connect
Works with Claude Code · Cursor · Codex · Hermes · VS Code (and neighbors) via a shared MCP menu. One local install. Your code stays on the machine.
Product GPS hub (circular — never a diamond). City view is the human skin, not the agent metaphor.
Table of contents
AI coding tools are expensive when they guess.
| Waste you already feel | Why it hurts |
|---|---|
| Wrong files, long loops | Tokens and tool calls burn while agents wander monorepos |
| Meetings that ocean-chart the codebase | Senior time spent “where does X live?” instead of shipping |
| Answers nobody can verify | Hallucinated paths — no citation trail |
| Cloud “repo brain” that wants a copy | Security kills the POC; data residency and exfil risk |
| Pretty demo, no re-runnable proof | CISO can’t replay what was indexed, shared, or refused |
Industry keeps scoring the token bill of agentic workflows. KnoSky attacks a different layer: navigation waste — agents without a shared local map. Complementary to code intelligence and IDEs, not a replacement.
KnoSky is local-first agent GPS for repos and docs:
- Map the folder on your machine (no cloud body store).
- Route assistants through one frozen MCP menu (search, node, provenance, optional allow/deny).
- Cite so answers link to something real.
- Optionally flip Enterprise / Regulated Mode for security report, audit pack/verify, architecture hangboard, and a private synthetic attack gauntlet.
Trust model (approved wording): KnoSky's local trust model applies the core security principles of TUF — role separation, threshold signing, survivable key compromise, and freshness-guaranteed revocation — adapted from TUF's server-oriented update distribution to a fully local, no-egress agentic environment, with attestation formats based on in-toto/DSSE.
From our own small guided-vs-wandering study (5 tasks — not someone else’s marketing deck):
| Metric | Result |
|---|---|
| Tokens | −68% with guided map vs wandering |
| Tool calls | −70% |
| Time-to-right-file | 6× faster |
| Guided hit rate | 5 / 5 correct |
| Wandering | Target sometimes found, 0 / 5 correct |
First-party evidence only. Industry write-ups measure other stacks — they amplify the problem, they are not KnoSky’s hero math.
| Risk without a local GPS layer | With KnoSky |
|---|---|
| Cloud tool insists on a copy of source | Local-first — default path does not upload your bodies as KnoSky product storage |
| Assistants write / run under the best marketing smile | Map tools are read-only (search / get / provenance) — documented in docs/READ_ONLY_GUARANTEE.md |
| Shared map dumps secrets or laptop paths | Share-safe indexing fails closed on secret-like values; absolute roots stripped |
| “Trust us” with no paper | Security report + audit pack / audit verify a stranger can re-run |
| Thin docs and unknown ownership until outage week | intel district scores — docs / ownership / tests / churn / drift / risk (local proxies) |
| Private attack proof that never exists | Private synthetic gauntlet (8 classes) — stays private unless Owner explicitly publishes |
Less thrash spend · less senior scavenger time · fewer dead AI POCs after Security · fewer “who owns this district?” workshops · same folder your agents already open.
| Without KnoSky | With it |
|---|---|
| Agent pays full tourist fare in the monorepo | Route toward the right node with a shared map |
| Security review is a deck of hope | Re-runnable doctor + security report + audit verify |
| Share a city HTML with crossed fingers | Fail-closed share-safe or don’t ship the artifact |
| Swarm marketing language | Doctor-honest ceilings — L3 coordinator = foundation, not fleet-everywhere |
npx knosky@latest .Indexes this folder, builds the city, prints MCP config + starter prompts, starts the local connector.
npx knosky@latest doctorRequirements: Node.js 20+.
Clone:
git clone https://github.com/SathiaAI/knosky
cd knosky && npm install
node bin/knosky.mjs .Flags: --no-open, --no-serve.
| Piece | What you get |
|---|---|
| Local maze map | Indexer for correct folders on your disk |
| City HTML | Human skin (isometric) for the same graph |
| MCP GPS tools | Frozen menu: map lookup + optional governed route/bundle/policy |
| Mode A / Mode B | Advisory tips or identity + policy + audit receipts |
| Packs | Claude · Cursor · Codex · Hermes (+ VS Code / Greptile recipe / PR-GPS) |
doctor |
Health + honesty for this install |
| Enterprise profile | Named safer defaults, security report, capability matrix |
audit pack / verify |
CISO-style portable evidence folder |
intel |
Architecture hangboard per district |
| Private adversarial gauntlet | Synthetic hosts · multi-role checks · rollup (not public by default) |
| L3 coordinator foundation | Local multi-helper leases/claims/heatmap/bench — not cloud fleet product |
| PR-GPS Action | Advisory PR comments — never blocks the build by default |
Not in the box: coding model replacement · cloud vault of everyone’s source · “swarm-safe production factory everywhere” · a compliance certificate peeled from a report file · automatic public attack-pack publish.
For pilots that need proof, not just a pretty city. Casual install still works — this is an opt-in jacket.
# Live on npm — no clone needed
npx knosky@latest enterprise . --no-open --no-serve
npx knosky@latest doctor
npx knosky@latest audit pack --root .
npx knosky@latest audit verify PASTE_BUNDLE_DIR_HERE
npx knosky@latest intel .| Step | Saves / avoids |
|---|---|
| Enterprise index | Fail-closed secrets · stripped absolute paths · security summary |
| Doctor ENT rows | Clear “profile active / report present / map RO vs Mode B” |
| Audit pack + verify | Security re-checks without a vendor meeting |
| Intel | Week-2 architect attention list without a slide workshop |
adversarial run |
Private synthetic proof (secrets, ignores, traversal, injection, stale, …) |
Private gauntlet (synthetic only — never customer data):
npx knosky@latest adversarial list
npx knosky@latest adversarial run
# optional live model reviewer: OPENROUTER_API_KEY or ANTHROPIC_API_KEY + KS_ADV_LLM=1 + --llmOwner walkthroughs:
OWNER-DEMO-ENT-PHASE1.md ·
OWNER-DEMO-ENT-PHASE2.md ·
OWNER-DEMO-ENT-PHASE3.md
SSOT menu: ssot/tool-menu.json · codes · ladder under ssot/.
Packs: packs/.
claude mcp add knosky \
-e KC_CITY=/abs/path/.knosky/city-data.json \
-e KC_PROFILE=coding \
-- node /abs/path/mcp/server.mjs| Profile | Used for |
|---|---|
| coding (default) | Map + governed tools |
| security | + audit query/verify |
| advisory | Explicit non-authorizing explore |
Mode A = labeled advisory only. Mode B = ALLOW / DENY_* with lease + policy + audit before authorized claims.
Mint a lease: npx knosky@latest agent-register --domain .knosky --agent my-agent.
Map tools (read-only): kc_search · kc_get_node · kc_list_categories · kc_get_provenance · kc_related
Governed: kc_route · kc_bundle · kc_policy_check
Details: docs/READ_ONLY_GUARANTEE.md
| L | Name | Promise |
|---|---|---|
| L0 | Local map | Navigate locally — no KnoSky source upload by default |
| L1 | Share-safe | Fail-closed secret controls before share artifacts |
| L2 | Governed evaluator | Mode B identity + policy + audit (or safe DENY) |
| L3 | Multi-helper domain | Coordinator foundation on the local domain — not multi-tenant fleet SaaS |
npx knosky@latest doctor
npx knosky@latest swarm status --domain .knosky
# bench only on a throwaway domain — never your live .knosky
npx knosky@latest swarm bench --domain /tmp/knosky-swarm-benchYou may say: local GPS, cited map tools, optional Mode B receipts, enterprise security report/audit pack, private synthetic gauntlet, architecture hangboard, L3 foundation.
You must not say: production swarm-safe fleet everywhere · dual-control operator lease revoke by default · “no egress guaranteed on Windows” without packaging proof · public attack-tested as marketing without Owner publish seek · a compliance certificate derived from a JSON report alone.
Lease revoke (accepted Wave-1 risk): holder or a single valid operator token — not dual quorum on revoke. Dual quorum applies to elevated registration. See SECURITY.md.
Windows: runtime network lockdown is not kernel-enforced for this CLI — LIMITATIONS.md.
| Command | Job |
|---|---|
npx knosky@latest . |
Map + city + connector |
npx knosky@latest doctor |
Honesty scorecard |
npx knosky@latest enterprise . --no-serve |
Enterprise profile + security report |
npx knosky@latest audit pack / audit verify |
Evidence bundle |
npx knosky@latest intel . |
Architecture intelligence |
npx knosky@latest adversarial list|run |
Private synthetic gauntlet |
npx knosky@latest agent-register |
Mode B lease |
npx knosky@latest swarm status|bench |
L3 foundation ops |
- Not an IDE or full code-intelligence product
- Not a multi-tenant cloud vault of source
- Not an autonomous “run the business” agent
- Not “zero residual risk” or finished multi-helper factory
- Not auto-public attack marketing after a private green
- Local by default; skips common secret-ish paths and ignore rules
- Scrub + fail-closed share-safe
More: PRIVACY.md · SECURITY.md · LIMITATIONS.md · CHANGELOG.md
FSL-1.1-MIT — free to use; no competing hosted side-sell; converts toward MIT on schedule. “KnoSky” trademark of the author.
City art: Kenney (CC0) — CREDITS.md.
Map locally. Cite answers. Prove the ceiling.
KnoSky is built and run by Viaknox.