kith

kith (n.) — your friends, acquaintances, and the people you know.

A private, version-controlled map of who you know and what they're good at — built so an AI can read it and tell you who to bring into a project.

The idea

Everyone knows useful people — a developer, sure, but also a nurse, a carpenter, an accountant, a teacher, the friend who started a business, the neighbor who's good with contracts. That's real leverage: the right person can turn a 3-week grind into a 20-minute call. But your network lives in your head — unstructured, unsearchable, and invisible to your tools. So when you ask an AI to help with a project, it answers as if you're doing it all alone.

kith fixes the missing input — for anyone, not just people in tech:

• Capture — one short file per person: what they're good at, how well you know them, what you'd go to them for.
• Query — "who do I know who can help with X?"
• Expose — hand it to an AI so that when you brainstorm or plan anything — a product, a renovation, a side business, a legal headache — it doesn't just give generic advice; it points to the real people you already know who could help with each part.

What I want to build

Not a contacts app. The thing worth building — and eventually worth paying for — is network-aware planning: an agent that turns "this is a 3-week solo grind" into "...or a 2-day effort if you pull in Dana for infra and Lena for the contract."

• Now — a proof of concept (this repo): a person file format + a zero-dependency CLI. Write people down → ask → get a ranked, useful answer.
• Next — agent-native: an MCP server (find_people, staff_project), an OpenAI-compatible local proxy, and a Claude Code / Codex skill, so agents and open-weight models can consult your network mid-plan as a first-class step.
• Later — a product: network-aware planning anyone can adopt, pointing their own kith at their own agents. (Vision.)

Only the POC exists today. Everything past it is the trajectory — see docs/VISION.md for the full picture. If you want to adopt it in another checkout, start with ADOPTING.md; the stable v0.1 data and People plan contract is in SPEC.md.

Status

| Phase | What | State | | ----- | ---- | ----- | | POC | File format + CLI to store and query people | 🟡 In progress (this repo) | | MCP server | find_people / get_person / list_people / staff_project as MCP tools | 🟡 Working (docs/MCP.md) | | OpenAI-compatible endpoint | Local proxy for LM Studio / open-weight models | 🟡 Working (docs/OPENAI_COMPAT.md) | | Skill | Drop-in skill that reads people/ (no server) | 🟡 Working (skills/kith/SKILL.md) | | Adoption docs | Versioned spec + outsider quickstart + kith init | 🟡 Working (SPEC.md, ADOPTING.md) | | Framework | Packaged, sellable product for AI agents | ⚪ Vision | | Monetization | Open-core: free format/CLI/skill, paid hosted + team | ⚪ Strategy (docs/MONETIZATION.md) |

Website: kith-network.vercel.app

See docs/ROADMAP.md for the full plan and docs/VISION.md for the bigger picture.

Business model

The model is open-core, and the product being sold is network-aware planning, not the data. The person format, the CLI, the skill, the self-hosted MCP server, and the local OpenAI-compatible proxy are free and open — they're adoption fuel, and they keep the private, self-hosted, you own the files promise honest. Paid tiers wrap the genuinely hard work around the data, and the Team tier is the revenue engine. See docs/OPEN_CORE_DECISION.md for the exact split.

• Free / Open — format + bin/kith.mjs + skill + self-hosted MCP + local OpenAI-compatible proxy. Runs fully local.
• Pro — hosted sync, capture, a hosted MCP endpoint, and auto-enrichment.
• Team — shared collective network, permissions, SSO, audit log. The business.

Full reasoning, including why the spec stays open, in docs/MONETIZATION.md.

How it works

Each person is one Markdown file in people/ with YAML frontmatter:

---
id: dana-dev
name: Dana
roles: [developer, devops]
trust: high
skills:
  - TypeScript (expert)
  - Kubernetes (advanced)
can_help_with:
  - Backend architecture reviews
  - Getting things deployed on AWS
---
Met at a hackathon. Prefers async. Owes me a favor.

The format is documented in docs/DATA_MODEL.md, with a machine schema in schema/person.schema.json.

Quick start (POC)

No dependencies — just Node.

# once published to npm
npx kith-network init
npx kith-network staff "build and deploy a web app"

# scaffold starter files in an empty/fresh checkout
node bin/kith.mjs init

# import contacts into reviewable draft Markdown files
node bin/kith.mjs import csv contacts.csv
node bin/kith.mjs import vcard contacts.vcf
node bin/kith.mjs import linkedin Connections.csv

# list everyone
node bin/kith.mjs list

# find people who can help with a skill / need
node bin/kith.mjs find kubernetes
node bin/kith.mjs find "legal"

# suggest who to approach for a project
node bin/kith.mjs staff "build and deploy a web app, then sell it as a physical product"

# run an OpenAI-compatible local proxy for LM Studio / open-weight models
node bin/kith-openai.mjs

# check that all people files are valid
node bin/kith.mjs validate

Add real people by copying people/_TEMPLATE.md. The _example-*.md files are fictional and safe to delete. To lower the initial data-entry cost, kith import csv|vcard|linkedin <file> writes reviewable drafts under people/_drafts/; use --commit only when you are ready to write normal people/*.md records.

Want to see it work first? docs/USE_CASES.md has real, reproducible query transcripts against a 14-person fictional network — showing the matcher's stemming/synonym handling and where it still falls short.

Use it from an AI agent (MCP)

The same logic is exposed to AI agents over the Model Context Protocol by a zero-dependency, read-only server — so Claude Code (or any MCP client) can consult your network mid-plan and route work to real people you know.

node bin/kith-mcp.mjs    # or: npm run mcp

This repo ships a project .mcp.json, so Claude Code offers to connect a kith server automatically. Tools: list_people, find_people, get_person, staff_project. Full setup and the output convention are in docs/MCP.md.

Use it with LM Studio / open-weight models

For clients that can set an OpenAI base_url but do not speak MCP, run the local OpenAI-compatible proxy:

node bin/kith-openai.mjs

Point the client at http://127.0.0.1:8787/v1. By default, kith forwards to LM Studio at http://127.0.0.1:1234/v1 and injects local People plan context when the prompt is network-relevant. For manual testing, open http://127.0.0.1:8787/ for a readable browser console. Full setup and configuration, including --port troubleshooting if 8787 is already in use, are in docs/OPENAI_COMPAT.md.

Privacy

This repo is private and holds personal information about real people. Treat it accordingly:

• Keep the GitHub repo private.
• Don't paste contact details into shared chats or public issues.
• Consider keeping sensitive contact fields out of git (see the contact: notes in docs/DATA_MODEL.md).

License

MIT for the local/open-core repo. The open-core split is documented in docs/OPEN_CORE_DECISION.md: format, CLI, local imports, skill, self-hosted MCP, and the local OpenAI-compatible proxy are open; hosted sync, enrichment, and Team features stay commercial.