{"id":49277749,"url":"https://github.com/spaceshipmike/setlist","last_synced_at":"2026-05-19T19:00:55.283Z","repository":{"id":353673179,"uuid":"1196656640","full_name":"spaceshipmike/setlist","owner":"spaceshipmike","description":"Project registry + intelligence + bootstrap","archived":false,"fork":false,"pushed_at":"2026-05-19T18:31:51.000Z","size":13297,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T18:53:43.979Z","etag":null,"topics":["project-bootstrap","project-intelligence","project-registry"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spaceshipmike.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T23:05:38.000Z","updated_at":"2026-05-17T10:02:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spaceshipmike/setlist","commit_stats":null,"previous_names":["spaceshipmike/setlist"],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/spaceshipmike/setlist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceshipmike%2Fsetlist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceshipmike%2Fsetlist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceshipmike%2Fsetlist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceshipmike%2Fsetlist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spaceshipmike","download_url":"https://codeload.github.com/spaceshipmike/setlist/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceshipmike%2Fsetlist/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33228878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["project-bootstrap","project-intelligence","project-registry"],"created_at":"2026-04-25T17:03:11.945Z","updated_at":"2026-05-19T19:00:55.262Z","avatar_url":"https://github.com/spaceshipmike.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Setlist\n\nA personal project registry and intelligence hub. Setlist is the structured memory of every project, area of life, and tool I work on — usable from agents (via MCP), from the terminal (via a CLI), from any Node.js process (via a library import), and from a native macOS app.\n\nThis is built primarily for my own workflow, but the architecture is general. The repo is public so the auto-update path can reach the running app from GitHub Releases.\n\nPublic-readiness work is tracked in [`docs/public-readiness-plan.md`](docs/public-readiness-plan.md): the current direction is a local, workspace-agnostic intelligence registry for agents across multiple MCP clients, with code and non-code projects both treated as first-class.\n\n## What it does\n\nSetlist holds a small SQLite database (~/.local/share/project-registry/registry.db) and exposes it through four interfaces. The database tracks:\n\n- **Project identity** — every project I work on, with paths, tech stack, goals, status, and free-form descriptions agents can read\n- **Canonical areas** — every project lives under one of seven areas (Work, Family, Home, Health, Finance, Personal, Infrastructure), with optional parent-child sub-project relationships\n- **Capability declarations** — what an MCP server exposes, what CLI commands a tool offers, what a library exports — so other agents can discover what's available without reading source\n- **Portfolio memory** — typed observations across projects (insights, decisions, contradictions, procedural knowledge) with full-text search, belief classification, temporal validity, and area-scoped inheritance\n- **Per-project essence digests** — short generated summaries of each project, useful for embedding, semantic matching, or dropping into another agent's context\n- **Local workspace inspection** — shallow code and non-code folder signals, such as manifests, scripts, dependency groups, runtime hints, document categories, folder roles, and notable filenames\n- **Port allocation** — conflict-free local-port assignment for development services\n- **Composite project health** — qualitative tier (Healthy / At risk / Stale) per project, computed from activity, profile completeness, and outcome signals\n\nThe point: an agent working on any workspace can ask Setlist \"what is this, what depends on it, what have we learned about it\" and get a structured, queryable answer.\n\n## Portable project intelligence demo\n\nAgents usually start cold. A new session lands in a folder, scans files, asks what matters, rediscovers conventions, and then loses that orientation when you switch from one agent client to another. Setlist's move is simple: register a workspace once, enrich the local registry over time, and make that project intelligence portable through the CLI, MCP, the library, and the desktop app.\n\nThe same brief is available from the terminal:\n\n```bash\nsetlist brief calendar-bridge --json\n```\n\nFor a narrower local source check, use:\n\n```bash\nsetlist inspect calendar-bridge --json\n```\n\nOr from any MCP client with:\n\n```json\n{ \"tool\": \"get_project_brief\", \"arguments\": { \"name\": \"calendar-bridge\" } }\n```\n\nBefore Setlist, a fresh agent entering a code repo might know only this:\n\n```text\nCurrent directory: /Users/demo/Workspaces/calendar-bridge\nNeed to inspect package files, README, open ports, prior decisions, and exposed commands before making a safe change.\n```\n\nAfter Setlist, the agent can ask for one brief. Abridged output:\n\n```json\n{\n  \"project\": {\n    \"name\": \"calendar-bridge\",\n    \"display_name\": \"Calendar Bridge\",\n    \"status\": \"active\",\n    \"workspace_kind\": \"code\",\n    \"paths\": [\"/Users/demo/Workspaces/calendar-bridge\"]\n  },\n  \"purpose\": {\n    \"summary\": \"Syncs calendar events into a local planning dashboard.\",\n    \"goals\": [\"Keep planning data local\", \"Expose a small MCP read surface\"],\n    \"topics\": [\"calendar\", \"mcp\", \"local-first\"]\n  },\n  \"profile\": {\n    \"tech_stack\": [\"TypeScript\", \"SQLite\", \"MCP\"],\n    \"patterns\": [\"library-first\", \"plan-before-apply\"]\n  },\n  \"digest\": {\n    \"digest_kind\": \"essence\",\n    \"digest_text\": \"Calendar Bridge is a TypeScript service that normalizes calendar data into a local SQLite store and exposes read-only planning context through MCP.\",\n    \"producer\": \"manual-demo\",\n    \"generated_at\": \"2026-05-09T12:00:00.000Z\",\n    \"stale\": false\n  },\n  \"capabilities\": {\n    \"count\": 2,\n    \"by_type\": { \"cli-command\": 1, \"tool\": 1 },\n    \"highlights\": [\n      { \"name\": \"calendar-bridge sync\", \"type\": \"cli-command\", \"description\": \"Run a bounded local sync.\" }\n    ]\n  },\n  \"operations\": { \"ports\": [{ \"port\": 4382, \"service_label\": \"dev\", \"protocol\": \"tcp\" }] },\n  \"orientation_notes\": [\n    \"Syncs calendar events into a local planning dashboard.\",\n    \"Essence digest is available for agent orientation.\",\n    \"Code workspace signals: TypeScript, SQLite, MCP.\"\n  ],\n  \"enrichment_gaps\": []\n}\n```\n\nSetlist is not only for code. A research, household, client, or planning folder can be registered as a workspace without pretending it has a software stack:\n\n```bash\nsetlist brief community-grant-archive --json\n```\n\nBefore Setlist:\n\n```text\nCurrent directory: /Users/demo/Workspaces/community-grant-archive\nNeed to infer purpose from filenames and ask which documents, deadlines, and decisions matter.\n```\n\nAfter Setlist. Abridged output:\n\n```json\n{\n  \"project\": {\n    \"name\": \"community-grant-archive\",\n    \"display_name\": \"Community Grant Archive\",\n    \"status\": \"active\",\n    \"workspace_kind\": \"workspace\",\n    \"paths\": [\"/Users/demo/Workspaces/community-grant-archive\"]\n  },\n  \"purpose\": {\n    \"summary\": \"Tracks grant requirements, submitted materials, reviewer notes, and follow-up decisions.\",\n    \"goals\": [\"Keep application history findable\", \"Preserve decision rationale across yearly cycles\"],\n    \"topics\": [\"grants\", \"documents\", \"planning\"]\n  },\n  \"profile\": {\n    \"short_description\": \"Grant document archive and decision log.\",\n    \"medium_description\": \"A non-code workspace for grant materials, requirements, notes, and yearly follow-up planning.\",\n    \"tech_stack\": [],\n    \"patterns\": []\n  },\n  \"digest\": null,\n  \"capabilities\": { \"count\": 0, \"by_type\": {}, \"highlights\": [] },\n  \"operations\": { \"ports\": [] },\n  \"orientation_notes\": [\n    \"Grant document archive and decision log.\",\n    \"No essence digest has been stored yet.\",\n    \"Treat this as a general workspace unless code-specific fields are added.\"\n  ],\n  \"enrichment_gaps\": [\"digest\"]\n}\n```\n\nThat empty `tech_stack` is intentional. Non-code workspaces remain first-class; Setlist does not require code metadata just to orient an agent.\n\n**Local-first trust note:** Setlist writes local registry data to `~/.local/share/project-registry/registry.db`. The registry, brief, and inspect commands do not upload workspace contents. Local inspection uses shallow folder structure and small known metadata files, redacts credential-looking manifest and remote values, and keeps findings as read-time context; any external digest generator is an explicit separate action.\n\n## MCP client setup demo\n\nSetlist can install its MCP server entry into supported local clients, but the flow is deliberately staged: detect the real client, preview the exact config change, then install only after review. Config-file presence alone is not detection; Setlist looks for real client artifacts such as the Claude Desktop app bundle, the Codex app bundle, or a `codex` binary on `PATH`.\n\nExample output below is synthetic, shortened, and shaped like the current CLI output.\n\nFirst, detect supported clients:\n\n```bash\n$ setlist mcp-clients detect\nClaude Desktop: detected\n  Config: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json\n  Found by: app: /Applications/Claude.app\nCodex: detected\n  Config: /Users/demo/.codex/config.toml\n  Found by: binary: codex\n```\n\nThen preview the install plan. This is a dry run; no files are changed:\n\n```bash\n$ setlist mcp-clients plan --client all\nDry run only. No files were changed.\n\nClaude Desktop: would-add-server\n  Config: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json\n  - Claude Desktop: would back up config before writing.\n  - Claude Desktop: would add managed 'setlist' MCP server.\n  - Claude Desktop: would preserve unmanaged 'filesystem'.\n  Backup before install: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup\n  Recovery guidance:\n  - Claude Desktop config would be written. A backup will be created first. 1 unmanaged server(s) will be preserved.\n  - Config file: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json\n  - Backup before write: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup\n  - Unmanaged entries preserved: filesystem\n  - If installed, Setlist will create a backup at /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup before writing /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.\n  - Unmanaged MCP servers preserved in place: filesystem.\n  - Setlist will not delete MCP client config files automatically. Setlist will not overwrite, adopt, or remove unmanaged MCP server entries automatically. Setlist will not restore backups automatically; backup restoration stays a manual recovery step.\n\nCodex: conflict-unmanaged-server\n  Config: /Users/demo/.codex/config.toml\n  - Codex: leave existing unmanaged 'setlist' MCP server untouched.\n  Recovery guidance:\n  - Codex was not changed because an unmanaged 'setlist' MCP server already exists.\n  - Config file: /Users/demo/.codex/config.toml\n  - Backup: not required for this state\n  - Unmanaged entries preserved: github, setlist\n  - Review the existing unmanaged 'setlist' MCP server in /Users/demo/.codex/config.toml; rename or remove it manually before asking Setlist to install its managed entry.\n  - Unmanaged MCP servers preserved in place: github, setlist.\n  - Setlist will not delete MCP client config files automatically. Setlist will not overwrite, adopt, or remove unmanaged MCP server entries automatically. Setlist will not restore backups automatically; backup restoration stays a manual recovery step.\n```\n\nOnly after the plan looks right, apply one client at a time:\n\n```bash\n$ setlist mcp-clients install --client claude-desktop --yes\nClaude Desktop: detected, backed_up, written\n  Config: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json\n  - Claude Desktop: backed up config to /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup-20260509T160000Z.\n  - Claude Desktop: wrote managed 'setlist' MCP server.\n  Backup: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup-20260509T160000Z\n  Recovery guidance:\n  - Claude Desktop config was written. A backup was created first.\n  - Config file: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json\n  - Backup created: /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup-20260509T160000Z\n  - Unmanaged entries preserved: filesystem\n  - To roll back, quit Claude Desktop, replace /Users/demo/Library/Application Support/Claude/claude_desktop_config.json with /Users/demo/Library/Application Support/Claude/claude_desktop_config.json.setlist-backup-20260509T160000Z, then reopen the client.\n  - Unmanaged MCP servers preserved in place: filesystem.\n  - Setlist will not delete MCP client config files automatically. Setlist will not overwrite, adopt, or remove unmanaged MCP server entries automatically. Setlist will not restore backups automatically; backup restoration stays a manual recovery step.\n```\n\nSetlist writes only its managed `setlist` entry. Existing configs are backed up before writes, unmanaged MCP servers are preserved, and unmanaged `setlist` conflicts are refused instead of adopted. Backup restoration stays manual: quit the client, restore the backup, then reopen the client. Setlist does not install Claude Desktop or Codex, restart those apps, validate that `@setlist/mcp` launches inside them, delete config files, or clean up unmanaged entries.\n\nTo uninstall Setlist from a supported client, use the guarded remove flow. Without `--yes`, it previews the exact managed entry removal and names the backup path:\n\n```bash\nsetlist mcp-clients remove --client claude-desktop\nsetlist mcp-clients remove --client claude-desktop --yes\n```\n\nRemove deletes only a Setlist-managed `setlist` entry, preserves unrelated MCP servers, backs up an existing config before writing, and refuses unmanaged `setlist` entries.\n\nSee [`docs/mcp-client-compatibility.md`](docs/mcp-client-compatibility.md) for the current Claude Desktop and Codex compatibility matrix, including detection signals, config paths, install behavior, backup behavior, conflicts, recovery guidance, and known limits.\n\n## How to use it\n\n### Desktop first run\n\nOpen the signed macOS app, then register an existing local folder. Setlist asks\nwhat kind of project or workspace it is, previews shallow local metadata from\nthat folder, and keeps non-code workspaces first-class. The preview is local on\nyour Mac; it does not upload contents, call an LLM, or index deeply.\n\nFrom Settings, you can preview installing or removing the managed Setlist MCP\nentry for Claude Desktop or Codex. Setlist shows the config change first,\npreserves unmanaged MCP entries, refuses unmanaged `setlist` conflicts, and\nbacks up existing config files before writing. Restore is manual from that\nbackup; Setlist does not restart clients or verify the MCP server inside them.\n\nAfter registration, ask an agent for the Setlist project brief with the MCP\n`get_project_brief` tool, or use `setlist brief \u003cworkspace\u003e --json` from the\nCLI.\n\n**Download the desktop app** from [Releases](https://github.com/spaceshipmike/setlist/releases) — `.dmg` for macOS Apple Silicon. Signed, notarized, with in-app auto-update over a stable channel.\n\n**As an MCP server**, point Claude Desktop or Codex at `@setlist/mcp`. The CLI can check supported clients and preview the managed Setlist entry before writing:\n\n```bash\nsetlist mcp-clients detect\nsetlist mcp-clients plan --client all\nsetlist mcp-clients install --client claude-desktop --yes\nsetlist mcp-clients remove --client claude-desktop\n```\n\nRun the `plan` command before install. Run `remove` without `--yes` before uninstall. Install and remove both preserve unmanaged MCP servers, refuse unmanaged `setlist` conflicts, and create a timestamped backup before writing an existing config.\n\nSee the setup demo above and [`docs/mcp-client-compatibility.md`](docs/mcp-client-compatibility.md) for the current Claude Desktop and Codex compatibility matrix, including detection signals, config paths, install behavior, backup behavior, conflict handling, recovery guidance, and known limits.\n\n**As a Node.js library**, `npm install @setlist/core` and import directly — Chorus, Ensemble, and other tools in my ecosystem use this path rather than going through the MCP protocol.\n\n**As a CLI**, `setlist` exposes registry maintenance, migration, digest refresh, bootstrap, recipe, primitive, worker, MCP-client install/remove commands, and `setlist brief \u003cproject\u003e [--json]` from the terminal. Run a command without the required arguments to see its usage.\n\n## How it's built\n\nFour npm workspace packages:\n\n```\npackages/\n├── core/    @setlist/core  — library: SQLite + all registry logic\n├── mcp/     @setlist/mcp   — MCP server (stdio transport)\n├── cli/     @setlist/cli   — CLI commands + async worker\n└── app/     @setlist/app   — Electron desktop control panel\n```\n\n**Stack:** TypeScript, better-sqlite3 (synchronous native bindings), the official `@modelcontextprotocol/sdk`, Electron 35 + React 19 + Tailwind CSS 4 + Radix UI for the desktop app. ESM-only, no CJS. The SQLite schema is migration-backed, uses WAL mode, and includes FTS5 for memory search.\n\n**Architecture decisions worth knowing:**\n\n- `@setlist/core` is the primary interface; MCP, CLI, and the desktop app are thin wrappers over it. The Electron main process imports `@setlist/core` directly via an IPC bridge — no API server sits between the UI and the database.\n- The desktop app and the MCP server need different native ABIs for `better-sqlite3` (Electron's Node vs. standalone Node). A wrapper script swaps binaries between dev/build/start steps and a session-start hook checks ABI integrity.\n- The desktop app shares a design system (`chorus-ui`) with another personal app (Chorus) — same surfaces, accents, typography, status colors. The information architecture is Setlist's own.\n\n**Spec-driven, not test-driven.** Setlist is built using a personal workflow I call fctry (factory). The complete behavioral contract is described in plain English in `.fctry/spec.md` (NLSpec v2 format) and validated by 118 end-to-end scenarios in `.fctry/scenarios.md`. The scenarios are evaluated by an LLM-as-judge — they're the holdout set, not test fixtures shown to the coding agent during builds. Vitest runs alongside as a fast local canary, but it's not the truth signal.\n\nWhat this means in practice:\n- I describe behavior in user-facing language; the coding agent picks the implementation\n- Every change starts with a spec evolution, then code follows\n- Pull requests don't pass because tests pass — they pass because the relevant scenarios still satisfy under LLM evaluation\n\nThe full contract: [`.fctry/spec.md`](.fctry/spec.md) (describing every surface, dimension, and invariant) and [`.fctry/scenarios.md`](.fctry/scenarios.md) (the end-to-end scenario set).\n\n## Develop\n\n```bash\ngit clone https://github.com/spaceshipmike/setlist.git\ncd setlist\nnpm install\nnpm run typecheck\nnpm test\nnpm run build       # builds core → cli → mcp (dependency order)\n```\n\nFor the desktop app:\n\n```bash\ncd packages/app\nnpm run dev         # electron-vite live reload\nnpm run build       # production build\nnpm start           # launch the built app\n```\n\n## Release\n\nTagging `vX.Y.Z` triggers the GitHub Actions workflow in [`.github/workflows/release.yml`](.github/workflows/release.yml). It signs with a Developer ID certificate, notarizes via Apple's notary service, staples the ticket, and publishes a GitHub Release containing the `.dmg` + `.zip` + `latest-mac.yml` update metadata. The running app's `electron-updater` reads `latest-mac.yml` to detect updates.\n\nSee [`packages/app/README.md`](packages/app/README.md) for credential setup and signing details.\n\n## Status\n\nExternal version 0.6.0, spec version 0.29. The project is actively developed against my own usage; APIs and schema may shift between minor versions until 1.0.\n\n## License\n\nNo formal license yet — this is personal infrastructure published openly. If you want to use any of the code beyond reading it, open an issue and we'll figure something out.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceshipmike%2Fsetlist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspaceshipmike%2Fsetlist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceshipmike%2Fsetlist/lists"}