This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 4.
What I Built
I kept watching the same failure. Someone wants to build a Next.js site, or a Python script that clicks through a browser, or an agent with Google's ADK, and they never get to the interesting part. The README says npm install and assumes Node 20. Their machine has Node 16, or Python without venv, or no GOOGLE_API_KEY. The error is real, and it is also useless if you are new.
I wrote StackSpirit for that moment. It is a small open-source CLI. You tell it what you want to build:
stackspirit check "Next.js website"
stackspirit check "AI agent with Google ADK"
stackspirit check "Python automation with Playwright"
stackspirit check "Expo mobile app"
Or you point it at a repo that will not start:
stackspirit scan .
It prints a table. Installed, missing, or wrong version. Then the exact command for the OS it detected — macOS, Linux, or Windows. If you pass --fix, it asks y/N before each command. The default is no. If the command needs sudo, the question says so. It will not invent an API key, and it will not run anything while you are reading.
The ghost bit is light on purpose. A missing dependency is "haunting your build." When the machine is fine, it says the machine is quiet. I did not want a Halloween skin on a tool that people will run when they are already stuck.
Demo
On the Linux machine I used while building this, Node 22, Python 3.12, and Go 1.22 were already there. Ollama was not.
stackspirit check "Next.js website" came back quiet and told me to run npx create-next-app@latest. It did not run that for me. create-next-app asks questions, and a tool that starts an interactive installer on its own is not helping.
stackspirit check "AI agent with Google ADK" was the interesting one. Python was new enough (ADK wants 3.11). google-adk was not installed. GOOGLE_API_KEY was not set. The fix was a virtualenv and pip install google-adk, plus a line I have to fill in myself:
export GOOGLE_API_KEY="your-key-here"
stackspirit scan examples/nextjs-site is a folder with a package.json, an .nvmrc of 20, and an empty .env.example. Node 22 was newer than the pin, which the report noted and did not treat as a failure. The real gaps were node_modules and NEXT_PUBLIC_SITE_URL. That is the report I wanted when I clone something and it will not boot.
examples/go-api was quiet. examples/docker-web was not, and the only fix was curl | sudo sh from Docker's own installer, marked as sudo, and not executed.
Code
AlizayAyesha
/
StackSpirit
Local-first CLI that tells beginners which tools a project needs, using a built-in stack list and a local open model.
StackSpirit
Local-first CLI that tells beginners which runtimes, packages, versions, and API keys a project needs — and which gaps are haunting the build. A built-in knowledge base covers common stacks offline. A local open-weight model explains the rest. Source code never leaves the machine.
Built by Zar Labs.
Repository: https://github.com/AlizayAyesha/StackSpirit
Suggested topics: cli developer-tools beginners toolchain ollama open-source-ai hacktoberfest nodejs typescript
Why
New developers stall before they write anything useful. They want a Next.js site, a Python script that drives a browser, an agent with Google's ADK, or an Expo app, and the repo will not run. Node is too old. python3-venv was never installed. A key is missing. The README assumes a machine that does not look like theirs.
StackSpirit checks the machine first. You say what you want to build, or you point it at a project, and it prints what is installed, what is missing…
Repo: https://github.com/AlizayAyesha/StackSpirit (MIT licensed)
How I Built It
The part I trust is a built-in list: Node and Next.js, React with Vite, Python, Django, FastAPI, Playwright, Docker, Expo, Flutter, Go, Rust, Google ADK, LangChain, the OpenAI and Anthropic SDKs, and n8n. Versions, packages, env var names, and install commands live in that list. It works with --no-ai, and it works when no model is installed. The samples above were produced that way.
The model has two jobs.
When the sentence is not in the list — "a Hugo site", "a Godot game" — StackSpirit asks a local model to map it. If the model names a stack we already know, we use our commands, not whatever shell line it invented. If it names a new tool, the command has to be boring: one invocation, no pipes, no rm. Anything else is dropped.
When a model is up, it also writes the short "why this matters" paragraph under the table. The table itself stays deterministic. I do not want a model deciding that the install command for Node is something cute.
The default is Ollama and qwen2.5-coder, on 127.0.0.1:11434. You can point the same config at LM Studio, a llama.cpp server, or any other OpenAI-compatible endpoint, including a free model on OpenRouter if that is what you have. The prompt is the stack name, the OS, and rows like "Playwright: missing". File contents and .env values are not in it. I left a sendCode setting in the config so the policy is visible, and the CLI ignores it. There is no mode that uploads the repository.
Why Open Innovation Matters Here
A setup tool learns a lot about a computer. Which languages you have. Which versions. Which keys you have not set yet. That is a map of a beginner's machine, and often of a student's laptop. Sending that map to a hosted API so it can return four sentences is a bad trade.
A local open model is free. It works on a train. I can swap qwen2.5-coder for the next open model without rewriting the CLI. And because the knowledge base is there, the tool still works on a machine that is too new to have a model pulled down — which is, awkwardly, the machine this tool is for.
A closed API would also fail in the exact case I care about: the person is offline, or they have not made an account, or the key they were going to use is the thing they are trying to set up. Open and local is not a slogan here. It is the only setup that does not ask them to be finished before they can start.
Built by Zar Labs (zarlabs.online).
Top comments (0)