A private, IFS-informed self-exploration companion that runs on your machine.
Single Go binary. Local data. Cloud LLM. No subscriptions, no servers, no accounts.
Quick Start · Features · Configuration · Architecture · Crisis Safety
IFS-Kiseki is a standalone companion for Internal Family Systems self-exploration. It runs entirely on your machine as a small HTTP server that opens in your browser. Your conversations are stored in a local SQLite database — nothing leaves your machine except the messages you send to the LLM provider you choose.
The companion is grounded in IFS principles: it speaks in parts language, guides you through the 6 F's protocol, checks for Self-energy before going deeper, and never rushes toward exile work. It is warm, patient, and knowledgeable — not a chatbot reading a manual.
It is not therapy. It is a tool for self-reflection, built with the belief that understanding your inner world should be accessible, private, and safe.
🧠 IFS-Informed Companion — Deep knowledge of the 6 F's protocol, parts taxonomy (managers, firefighters, exiles), Self-energy (8 C's and 5 P's), unblending techniques, and session flow. The system prompt is sourced from IFS literature (see Sources) and crafted to feel like a warm, knowledgeable guide.
💬 Real-Time Streaming Chat — Responses appear word-by-word via WebSocket. Supports Claude (Anthropic) and Grok (xAI) as LLM providers.
🧩 Session Memory — Past sessions are saved locally and used to generate warm, contextual briefings at the start of each new conversation. Optional vector embeddings (via Ollama) enable semantic search across your history.
🛡️ Crisis Safety — Keyword-based detection scans every message before it reaches the LLM. When crisis language is detected, a resource overlay with hotline information appears and cannot be dismissed for 5 seconds. This is non-negotiable — it ships enabled by default.
🔒 Privacy-First — All data stays on your machine in a local SQLite database. The only outbound connections are to the LLM provider API you configure. Config files are stored with restrictive permissions (0600).
🎨 Warm, Appropriate UI — A clean web interface with dark mode support, designed to feel safe and grounding — not clinical, not flashy.
📋 Session History — Browse past sessions in the sidebar, resume previous conversations, and track your exploration over time.
⚙️ Configurable Companion — Name your companion, set focus areas (anxiety, perfectionism, relationships, etc.), add custom instructions, and switch providers at any time.
git clone https://github.com/Gsirawan/ifs-kiseki.git
cd ifs-kiseki
make buildOr build directly:
CGO_ENABLED=1 go build -ldflags "-X main.Version=0.1.0" -o ifs-kiseki .Choose one:
# Option A: Environment variable (recommended)
export ANTHROPIC_API_KEY="sk-ant-..."
# Option B: .env file
cp .env.example .env
# Edit .env and add your key./ifs-kisekiThe server starts at http://127.0.0.1:3737 and opens your browser automatically. On first launch, you'll see a disclaimer and onboarding flow.
| Target | Description |
|---|---|
make build |
Compile the binary with version info |
make run |
Build and run |
make test |
Run all tests |
make dev |
Run with go run (no binary on disk) |
make clean |
Remove binary and local database |
Session briefing with IFS-informed context from past conversations.
+------------------------------------------------------------------+
| IFS-KISEKI BINARY |
| |
| +------------------+ +------------------+ +-----------+ |
| | HTTP Server | | WebSocket Hub | | embed.FS | |
| | (localhost:NNN) |--->| (streaming chat) | | (SPA UI) | |
| +--------+---------+ +--------+---------+ +-----+-----+ |
| | | | |
| v v v |
| +------------------+ +------------------+ +-----------+ |
| | REST API | | Chat Engine | | Static | |
| | /api/sessions | | - turn mgmt | | Assets | |
| | /api/settings | | - prompt build | | HTML/CSS | |
| | /api/briefing | | - stream relay | | /JS | |
| +--------+---------+ +--------+---------+ +-----------+ |
| | | |
| v v |
| +------------------+ +------------------+ |
| | Memory Engine | | Provider Layer | |
| | (Kiseki-lite) | | | |
| | - save session | | +-------------+ | |
| | - search context| | | Anthropic | | |
| | - gen briefing | | | Client | | |
| | SQLite + Vec | | | (Claude) | | |
| | + Ollama embed | | +-------------+ | |
| +------------------+ | +-------------+ | |
| | | OpenAI- | | |
| | | Compatible | | |
| | | Client | | |
| | | (Grok/xAI) | | |
| | +-------------+ | |
| +------------------+ |
| |
| +------------------+ +------------------+ |
| | Config | | Crisis Safety | |
| | config.json | | - keyword scan | |
| | API keys | | - resource show | |
| | provider choice | | - disclaimer | |
| +------------------+ +------------------+ |
+------------------------------------------------------------------+
| |
v v
+-----------+ +---------------+
| SQLite DB | | Cloud APIs |
| (local) | | - Anthropic |
| sessions | | - xAI (Grok) |
| messages | | - Ollama |
| embeddings| | (embeddings)|
+-----------+ +---------------+
Key design decisions:
- Single binary — The web UI is embedded via Go's
embed.FS. No separate frontend build step, no Node.js, no npm. - Two API clients cover all providers — The Anthropic client handles Claude; the OpenAI-compatible client handles Grok and any future provider (Ollama, GPT, Groq, etc.).
- Graceful degradation — Every optional component (embeddings, memory, crisis detection) degrades gracefully when unavailable. The app always starts.
- Crisis detection runs before the LLM — Messages are scanned locally before being sent to the provider. No network dependency for safety.
Config is stored at ~/.config/ifs-kiseki/config.json (respects XDG_CONFIG_HOME). On first run, a default config is created automatically.
See config.example.json for the full schema.
| Field | Type | Default | Description |
|---|---|---|---|
version |
int | 1 |
Config schema version |
provider |
string | "claude" |
Active provider: "claude" or "grok" |
disclaimer_accepted |
bool | false |
Set automatically after first-launch acceptance |
| Field | Default | Description |
|---|---|---|
model |
"claude-sonnet-4-20250514" |
Model ID |
base_url |
"https://api.anthropic.com" |
API endpoint |
max_tokens |
4096 |
Max tokens per response |
temperature |
0.7 |
Sampling temperature |
api_key |
"" |
API key (prefer env var ANTHROPIC_API_KEY) |
| Field | Default | Description |
|---|---|---|
model |
"grok-4-1-fast-reasoning" |
Model ID |
base_url |
"https://api.x.ai" |
API endpoint |
max_tokens |
4096 |
Max tokens per response |
temperature |
0.7 |
Sampling temperature |
api_key |
"" |
API key (prefer env var XAI_API_KEY) |
| Field | Default | Description |
|---|---|---|
ollama_host |
"localhost:11434" |
Ollama server address |
model |
"qwen3-embedding:0.6b" |
Embedding model |
dimension |
1024 |
Vector dimension |
| Field | Default | Description |
|---|---|---|
host |
"127.0.0.1" |
Bind address (localhost only) |
port |
3737 |
HTTP port |
open_browser |
true |
Auto-open browser on start |
| Field | Default | Description |
|---|---|---|
name |
"Kira" |
Companion display name |
focus_areas |
["anxiety", "perfectionism"] |
IFS focus areas |
user_name |
"" |
Your name (optional) |
custom_instructions |
"" |
Additional prompt instructions |
| Field | Default | Description |
|---|---|---|
enabled |
true |
Enable crisis detection |
hotline_country |
"US" |
Country code for resource display |
| Field | Default | Description |
|---|---|---|
auto_save |
true |
Save sessions automatically |
briefing_on_start |
true |
Generate briefing from past sessions |
max_context_chunks |
5 |
Memory chunks included in context |
| Field | Default | Description |
|---|---|---|
theme |
"warm" |
UI theme |
font_size |
"medium" |
"small", "medium", or "large" |
Claude is the default and recommended provider for IFS self-exploration. Its conversational depth and emotional attunement make it well-suited for parts work.
- Get an API key at console.anthropic.com
- Set it via environment variable:
Or in
export ANTHROPIC_API_KEY="sk-ant-..."
.env:ANTHROPIC_API_KEY=sk-ant-...
Grok (xAI) is a premium alternative with strong therapeutic presence. It uses an OpenAI-compatible API.
- Get an API key at console.x.ai
- Set it via environment variable:
export XAI_API_KEY="xai-..."
To switch providers, change "provider" in config.json to "grok", or use the Settings page in the UI.
Session memory works without embeddings — sessions are saved and retrieved by recency. Embeddings add semantic search, surfacing relevant context from older conversations based on meaning rather than time.
- Install Ollama
- Pull the embedding model:
ollama pull qwen3-embedding:0.6b
- Start Ollama:
ollama serve
Ollama runs at localhost:11434 by default — no further configuration needed.
If Ollama is not running, IFS-Kiseki starts normally and falls back to recency-based memory. Sessions are still saved; embeddings are simply skipped. When you start Ollama later, new sessions will be embedded automatically.
API keys and the Ollama host can be set via environment variables. These always take precedence over config.json values.
cp .env.example .env
# Edit .env with your values| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
Anthropic API key for Claude |
XAI_API_KEY |
xAI API key for Grok |
OLLAMA_HOST |
Ollama server address (default: localhost:11434) |
IFS-Kiseki includes keyword-based crisis detection that scans every message before it reaches the LLM. When crisis language is detected, a resource overlay appears with country-specific hotline information. The overlay cannot be dismissed for 5 seconds.
Supported countries: US, GB, CA, AU, NZ, DE, FR, IN, AE — with automatic fallback to US resources.
Crisis detection is enabled by default and should not be disabled. It can be turned off in config (crisis.enabled: false), but this is strongly discouraged.
This feature is not a substitute for professional crisis support. If you or someone you know is in crisis, please contact a qualified professional or emergency services immediately.
- All data is stored locally at
~/.config/ifs-kiseki/ifs-kiseki.db - Config is stored at
~/.config/ifs-kiseki/config.jsonwith permissions0600 - The only outbound connections are to your configured LLM provider API and (optionally) local Ollama
- No telemetry, no analytics, no tracking
- Your conversations never leave your machine except as LLM API requests to the provider you chose
The IFS Protocol prompt in IFS-Kiseki is sourced from established Internal Family Systems literature:
- Richard C. Schwartz — Internal Family Systems Therapy (2nd ed., Guilford Press). The foundational IFS model: multiplicity of mind, Self-energy, the 8 C's and 5 P's, parts taxonomy (managers, firefighters, exiles), and the unburdening process.
- Jay Earley — Self-Therapy: A Step-By-Step Guide to Creating Wholeness Using IFS (Pattern System Books). The 6 F's protocol (Find, Focus, Flesh Out, Feel Toward, Befriend, Fear), practical self-guided IFS exercises, protector fears framework, and the P1-P5/E1-E5 session protocols.
- Bonnie J. Weiss — Healing the Fragmented Selves of Trauma Survivors (contributions to the IFS approach for trauma and exile work, unblending techniques).
- IFS Institute — ifs-institute.com. Official training materials, practitioner guidelines, and the "no bad parts" principle.
The protocol prompt was constructed from dedicated extraction documents that systematically captured techniques, questions, and session flows from these sources. The source extraction files are referenced in internal/chat/prompt_ifs.go.
IFS-Kiseki is not therapy and is not a substitute for professional mental health care.
It is a self-exploration tool informed by Internal Family Systems principles. It cannot diagnose, treat, or provide clinical advice. The companion is not a licensed therapist, counselor, or medical professional.
For deep trauma work, complex PTSD, dissociative experiences, or any situation where you feel unsafe, please work with a trained IFS therapist.
If you are experiencing a mental health crisis, contact emergency services or a crisis hotline in your country.
By using IFS-Kiseki, you acknowledge that you are using it as a personal reflection tool, not as a therapeutic intervention.
| Component | Technology |
|---|---|
| Backend | Go (single binary, embed.FS for static assets) |
| Database | SQLite + sqlite-vec (vector search) |
| Embeddings | Ollama (local, optional) |
| Frontend | Vanilla HTML/CSS/JS (no build step, no framework) |
| LLM Providers | Anthropic API (Claude), OpenAI-compatible API (Grok/xAI) |
| WebSocket | nhooyr.io/websocket |
MIT License — see LICENSE.
Contributions are welcome. If you're interested in contributing, please:
- Open an issue to discuss the change before submitting a PR
- Follow the existing code style and conventions
- Include tests for new functionality
- Do not modify the IFS Protocol prompt (
internal/chat/prompt_ifs.go) without discussion — it is carefully sourced from IFS literature (see Sources)
Built with care for people who want to understand themselves better.