A reflective companion for self-guided inner work.
AI-powered guides — shaped by your intake and refined through conversation — ask you the questions, leading reflective sessions drawn from therapy, spirituality, and philosophy. Everything stays local, readable, and yours.
If you're drawn to self-reflection, you already have plenty to read and almost nothing that actively guides you through it.
- Journaling gives you a blank page. Paralysis.
- Books and podcasts are passive. No interaction, no adaptation.
- Professional counseling is expensive and requires scheduling.
Spirit Guides is a different shape entirely. You open it with an intention — "I want to understand my relationship with control" — and the guide takes over. It reviews its full history with you, the frameworks you care about, and the intention you set, then asks you questions. You respond. It follows up. It feels like talking to a wise, patient guide who knows what resonates with you — because it does.
No prompts to write. No commands to master. Just a conversation that goes where you need it to.
Every other AI chat tool flips the dynamic: you struggle to craft the perfect prompt. Here, the guide holds the conversation. You bring the intention; the guide brings the questions.
Each guide is a dynamic, evolving prompt — not a static script. When you mash up guides or evolve them over time, you're merging and refining the prompts underneath. When you shape a guide through freeform chat, you're co-authoring it. Sessions adapt as the guide learns what resonates with you.
Every guide, every session, every intake, every guardrail log is a readable local markdown file on your machine. No opaque database. No cloud sync. Open any file in any text editor and read exactly what's there.
Power your guides with Claude, Codex, or Ollama (fully local). The app talks to each through its local CLI — no API keys, no HTTP — by spawning the binary as a subprocess and streaming stdout. One global setting — no per-guide configuration. Swap backends anytime without losing a single session.
Guardrails sit at the application code layer, not in the AI prompt. Invisible by default. They apply to every guide — no matter how it's evolved or mashed up — without relying on the AI to police itself.
- Soft rails gently redirect when a session veers into rumination or harmful self-talk, woven directly into the guide's normal responses.
- Hard rails stop the session and surface crisis resources if crisis signals appear. The session locks. You get real help.
Detection is evaluated against a labeled crisis-language corpus and gated in CI by minimum precision and recall thresholds (see ./tests/safety/). The corpus covers direct phrasing, paraphrases, negations, quotations, third-person references, and multilingual forms — but no classifier is perfect. Guardrails substantially raise the bar for safety; they are not a guarantee of detection in every possible case.
flowchart TD
A[First Run<br/>Intake Wizard] --> B[Select Concepts<br/>237 across 9 categories]
B --> C[5 AI-Generated<br/>Suggested Guides]
C --> D{Refine or<br/>Create from Scratch?}
D --> E[Freeform Creation Chat<br/>Co-author the guide]
E --> F[Invoke Guide<br/>It's now live]
F --> G[Home: Your Guides]
G --> H[Begin a Session<br/>State your intention]
H --> I[Guide Asks. You Answer.<br/>It follows up.]
I --> J{More to explore?}
J -->|Yes| K[Mashup or Evolve<br/>Blend guides, add influences]
K --> E
J -->|Across guides| L[Cross-Cutting Analysis<br/>Find patterns, new intentions]
L --> G
Start by telling Spirit Guides what resonates with you. Browse a searchable library of 237 concepts across nine categories — therapy modalities, spiritual traditions, philosophy, psychological frameworks, meaning & purpose, relationship & connection, emotional exploration, identity & self, daily practice & integration. Each has a description. Checkboxes, not commitment. Skip entirely if you'd rather start clean.
Your selections feed five AI-generated suggested guides — created from what actually interests you, not from templates.
This isn't a form to fill out. You have a freeform chat with the AI about what kind of guide you want — its approach, its personality, its focus. You can pull in concepts from the library as you go. When you're satisfied, you type "invoke guide" and it comes alive. The entire creation chat is saved as the guide's invocation record.
Guides aren't fixed. Combine two or more into a mashup. Or evolve an existing guide with new influences. On evolution, you choose:
- Preserve — the original keeps its full session history; a new guide starts fresh.
- Transform — the original guide gains new insight and keeps its session history.
Both are prompt-level operations: the underlying prompts are merged and refined, then you shape the result through the same freeform chat.
Pick a guide. State an intention. The guide reviews its history with you and the intention, then drives the conversation by asking reflective questions grounded in its concept blend, lineage, and everything it knows about you. You can suggest closing, but you have final authority.
Sessions save as local markdown in real time. When a guide is fresh, it asks broadly. Over time, it knows what you've already explored and where to go deeper.
When you invoke it — never automatically — and only for the guides you select — Spirit Guides reads across those guides' sessions and produces a dedicated report:
- Recommended intentions to explore next — clickable to start a session immediately.
- Recommended guide creations to consider — clickable to start guide creation.
No guide can read another guide's sessions unless you explicitly grant access for a single analysis run.
Resume open sessions. Review archived ones as read-only markdown. Close to archive. Unlock to revisit (which creates a continuation, not a resurrection). Export any session as PDF, ePub, or DOC for sharing or archiving.
The intake surface, the guide creation palette, and the evolution tool — all the same library. 237 concepts across nine categories (see ./src/data/concepts.json for the full data).
| Category | Count | Examples |
|---|---|---|
| Therapy Modalities | 27 | CBT, DBT, ACT, IFS, Schema, EFT, Somatic, Polyvagal Theory |
| Spiritual Traditions & Practices | 56 | Zen, Tibetan & Theravada Buddhism, Advaita Vedanta, Taoism, Sufism, Kabbalah, Christian Mysticism, Ho'oponopono, Dzogchen |
| Philosophy | 31 | Stoicism, Existentialism, Absurdism, Phenomenology, Virtue Ethics, Deontology, the Allegory of the Cave, the Socratic Method |
| Psychological Frameworks | 35 | Shadow Work, Active Imagination, the Enneagram, Flow, Growth Mindset, Attachment Theory, Ikigai, Kaizen |
| Meaning & Purpose | 19 | Life purpose, existential anxiety, authenticity, mortality awareness, the search for truth |
| Relationship & Connection | 17 | Attachment styles, compassionate communication, the drama triangle, inner child work |
| Emotional Exploration | 17 | Emotional regulation, self-compassion, values clarification, psychological flexibility |
| Identity & Self | 15 | Non-self, self-actualization, shadow integration, authenticity under pressure |
| Daily Practice & Integration | 20 | Habit formation, Ikigai, Kaizen, mindfulness as practice, not concept |
Add your own custom concepts to any category, anytime. They persist across every future guide interaction.
- Electron 33 — desktop-first, cross-platform (Windows / macOS / Linux)
- React 19 + TypeScript 5.7 — renderer, with React Router 7 (HashRouter)
- Zustand 5 — state management
- Tailwind CSS 3 — styling, with a custom design-token layer (
src/renderer/styles/tokens.css) - Vite 6 — bundler, via
@electron-forge/plugin-vite - lucide-react — icon set
- gray-matter / react-markdown / remark-gfm — markdown parsing and rendering
- md-to-pdf / epub-gen-memory / docx — session and invocation export (PDF / ePub / DOC)
- Vitest + Playwright — unit and end-to-end tests
- Local markdown — the only data store (one
settings.jsonis the sole non-markdown file)
- Node.js 22+ and npm
- At least one AI backend CLI installed and on your
PATH(or set an explicit path in Settings):
The app spawns the selected CLI as a subprocess and pipes the conversation via stdin/stdout. No API keys are stored or sent — each CLI handles its own authentication and model routing.
git clone https://github.com/john-paul-ruf/spirit-guides.git
cd spirit-guides
npm installnpm run devLaunches the Electron app with hot reload via Vite.
npm run build # type-check + bundle
npm run package # package the app for the current OS
npm run make # create installers for the current OSnpm test # Vitest unit tests
npm run test:e2e # Playwright end-to-end testsOn first launch, open Settings and select your AI backend. The app verifies the CLI is installed (runs <cli> --version) and shows connection status in the top bar at all times. Optionally set an explicit binary path or model override per backend; otherwise the CLI on your PATH and its own default model are used.
Every guide, session, intake, cross-cutting report, and guardrail log lives in a readable directory of local markdown files. Open it in your file manager. Open any file in a text editor. Read exactly what's there. Nothing is hidden.
Spirit Guides makes exactly one kind of outbound call — spawning the selected AI CLI as a local subprocess. It never makes direct HTTP calls to any AI vendor's API. No usage tracking, no error reporting to a third party, no sync. With Ollama selected, nothing leaves your machine at all.
The guardrail system is invisible until it needs to be visible. It doesn't diagnose, doesn't censor normal emotional expression, doesn't interrupt difficult philosophical or spiritual territory. Sadness, anger, grief, fear — all valid session topics. It intervenes only when a session drifts into real crisis or sustained harmful patterns, and even then the touch is calm, not clinical.
All guardrail triggers — soft and hard — are logged to local markdown files you can review anytime. Full transparency, no obfuscation.
Spirit Guides is a reflective companion. It is not a medical or therapeutic tool. It does not diagnose, treat, or replace professional counseling or crisis intervention. If you are in crisis, the app will surface resources and direct you to real help. If you need ongoing support, please reach out to a qualified professional.
| Screen | Mock | Purpose |
|---|---|---|
| Intake Wizard | ./mocks/intake.html |
First-run concept selection |
| Suggested Guides | ./mocks/suggested-guides.html |
Post-intake AI suggestions |
| Home / Dashboard | ./mocks/home.html |
Guide list and quick actions |
| Guide Detail | ./mocks/guide-detail.html |
Metadata, lineage, sessions |
| Guide Creation Chat | ./mocks/guide-creation.html |
Freeform guide shaping |
| Session | ./mocks/session.html |
Active guided conversation |
| Session List | ./mocks/session-list.html |
Per-guide session management |
| Mashup & Evolution | ./mocks/mashup.html |
Blend or evolve guides |
| Cross-Cutting Analysis | ./mocks/cross-cutting.html |
Invoke analysis, view report |
| Settings | ./mocks/settings.html |
AI backend, data, logs |
| Crisis Lock | ./mocks/crisis-lock.html |
Hard rail full-stop screen |
Open ./mocks/index.html in a browser to navigate the full prototype.
spirit-guides/
├── specs/ # Design and planning documents
│ ├── idea.md # The product vision
│ ├── requirements.md # Functional and non-functional requirements
│ ├── design.md # Visual and interaction design language
│ ├── architecture.md # System architecture
│ └── database.md # Storage model
├── mocks/ # HTML prototypes of every screen
├── src/
│ ├── data/ # Static app data (concepts.json)
│ ├── main/ # Electron main process
│ │ ├── ai/ # CLI adapters (Claude, Codex, Ollama) + prompt builder
│ │ ├── guardrails/ # Soft and hard rail logic + patterns + logger
│ │ ├── storage/ # Local markdown file storage + directory layout
│ │ ├── export/ # PDF / ePub / DOC export
│ │ ├── system/ # PATH repair for GUI-launched processes
│ │ └── ipc/ # IPC handlers (ai, filesystem, guardrail, export)
│ ├── renderer/ # React renderer
│ │ ├── routes/ # Screen-level views
│ │ ├── components/ # Reusable UI (chat, common, concept-library, guide, layout, session, feedback)
│ │ ├── stores/ # Zustand stores (guides, sessions, concepts, settings, guardrail)
│ │ ├── hooks/ # Hooks (streaming, session, concepts, theme)
│ │ ├── services/ # Renderer-side services (IPC client, stream client)
│ │ └── styles/ # Design tokens + global CSS
│ └── shared/ # Types and constants shared across processes
└── resources/ # Icons and assets
MIT — see ./LICENSE. Built by John Ruf.
The guide asks. You answer. That's the whole thing.