The install is the wrapper. You supply the neighborhood, the conversations, and the AI. This page is the honest version of what that actually takes over the first 30 days.
There's no one-click "launch a neighborhood" button, and anyone selling you one is lying. The reason most civic software fails is that it treats the software as the product. The software isn't the product here. Trust is the product. The software is just the wrapper that makes showing up reliably a little easier.
What you'll do over the first 30 days is mostly talk to people. Roughly 20 conversations. The software helps you remember what they said, spot patterns, and pick one sharp wedge to build around. You bring the neighborhood. You bring your own AI (OpenAI key, Anthropic key, or a local Ollama). We bring the wrapper.
A single concrete pain that passes the four-test filter and has at least 3 neighbors ready to try v1.
Your neighborhood's boundary, key civic contacts, meeting schedule, and the five loudest pain patterns from your intake conversations.
SQLite DB, ingest scripts pointed at your city's open data, weekly digest in your inbox. Data stays on your machine.
A one-page plan for the ugliest possible version of the tool that solves your chosen wedge inside 90 days.
Write a one-page NODE.md about your neighborhood. Boundary. Roughly how many households. Existing groups (HOA, neighborhood association, block captains, Facebook group). What civic meetings already happen and who shows up. What's broken that everyone already complains about. You'll update this as you learn.
Decide who else is in on this with you, even loosely. One person alone can start a node. One person alone can't sustain one.
wedges/_template/NODE.md in the repoClone the repo, install dependencies, point the ingest scripts at your city's open data portal (Socrata, ArcGIS, or your local equivalent), and drop in an AI key.
git clone https://github.com/simonlpaige/neighborhoodos.git cd neighborhoodos npm install cp .env.example .env # edit .env: add OPENAI_API_KEY or ANTHROPIC_API_KEY or OLLAMA_HOST # edit connectors/cities.json: add your city's open data endpoints
If your city doesn't have open data, that's fine. Skip the connectors for now. The intake and wedge work still runs.
This is the phase where real nodes are made and fake ones die. Talk to 20 neighbors. Start with the loud ones (block captains, long-timers, the person who runs the Facebook group). Move to the quiet ones (people who moved in recently, elderly homeowners, renters if your wedge includes them).
The intake tool in the repo gives you a 12-question conversation guide and stores the anonymized notes in your local DB. After each batch of 5 conversations, run node intake/summarize.js and it asks your AI to pull pain patterns across them.
Run node wedges/suggest.js. It hands your intake summary to your AI with the four-test filter baked in. You get 2-3 candidate wedges ranked on:
The AI recommends. You decide. Pick one. Write the chosen wedge into wedges/your-wedge/README.md. Tell three of the neighbors who showed up strongest in intake that this is what you're building toward, and ask if they'll try v1.
Run node wedges/scaffold.js your-wedge. It creates a folder with an ingest script, a local data model, a basic CLI, and a README stub. It does NOT build you a product. It gives you the skeleton so you can start filling in what YOUR wedge actually needs.
The ugliest possible v1 is usually: a spreadsheet-or-SQLite list, one script that updates it, and one human (you) sending a weekly text message to the neighbors who opted in. That's fine. Ship that. Every fancier version is built on top of that skeleton once it earns trust.
After 90 days, check the signals below. If the wedge is working, keep running it and queue the next one. If it isn't, rotate the wedge. The platform stays, the wedge changes. This is the whole point.
20+ households have used the tool once. 3+ named "prevented a disaster" stories. At least one coordinated block-level job where real money was saved. Neighbors bring other neighbors without you asking.
Fewer than 10 households have touched it. You're the only one talking about it. The people who said "yes, try it on me" at intake have gone quiet. Rotate the wedge. No shame. The platform stays.
The install is the easy part. The first real step is writing your NODE.md and lining up your first 5 conversations. Clone the code when you're ready for day 1.
Browse the code Back to homeQuestions? Open an issue on GitHub, or if you're piloting in a neighborhood and want to compare notes, reach out through simonlpaige.com.