ifs-agents

An agent templating system based on Internal Family Systems (IFS). Interview your inner parts through guided LLM sessions, build evolving written profiles of each part — its qualities, fears, hopes, and relationships to the other parts — and then spawn those parts as AI agents that react to any dataset, document, or decision through their own lens, individually or around a shared table.

This repo ships no specific parts. It ships the flow: the question protocol, the profile schema, the safety rails, and the compilation step that turns a developed profile into a runnable agent. Your parts are yours.

A guide, not a therapist. Sessions are IFS-informed inner work. They can go as deep as a person's parts are willing to go — witnessing an exile, helping it let go of what it carries — but only through its protectors, and never by digging for or suggesting memories. The AI guide is not a therapist or a substitute for one. Read docs/safety.md before you start. If you are in crisis, use a crisis line (988 in the US), not this tool.

IFS in 30 seconds

IFS (Richard Schwartz) holds that everyone has an inner system of parts — subpersonalities with their own ages, feelings, jobs, and relationships: managers (proactive protectors), firefighters (reactive protectors), and exiles (young hurt parts the protectors shield). Beneath them all is Self — calm, curious, compassionate — the system's natural leader. Every part has a positive intent; there are no bad parts. Longer version: docs/ifs-primer.md.

How it works

  ┌────────────────┐    ongoing     ┌────────────────────┐
  │ intake session │──────────────▶│  part profile       │
  │ (meet a part)  │   check-ins    │  parts/<name>.md    │◀── relationship
  └────────────────┘                │  (md + YAML,        │    mapping
                                    │   grows over time)  │    (swarm graph)
                                    └─────────┬──────────┘
                                     readiness gate
                                              ▼
                                    ┌────────────────────┐
                                    │  compiled agent     │
                                    │  part-<name>.md     │
                                    └─────────┬──────────┘
                     your dataset / document / decision
                                              ▼
                                    ┌────────────────────┐
                                    │  table meeting      │
                                    │  each part reacts,  │
                                    │  Self synthesizes   │
                                    └────────────────────┘

1. Intake — a guided interview (permission-first, one question at a time) meets one part and writes its profile.
2. Check-ins — ongoing sessions deepen the profile over weeks. A per-category coverage map tracks what's been explored, what's partial, and what the part has declined — declined topics stay closed. Protectors set the pace; there is no finish line. As a part comes to trust Self, a check-in can go further than getting to know it — updating it, meeting what it protects, helping it let go of something — and the profile records how the part has changed, not just what it said.
3. Mapping — pairwise sessions capture how parts relate: who protects whom, who's allied, who's polarized. Edges are written symmetrically into both profiles, and the whole swarm renders as a Mermaid graph.
4. Compile — once a profile clears a minimum-development bar, it compiles into a self-contained agent prompt that embodies the part's voice and lens, with hard safety rules baked in.
5. Meet — point the swarm at any dataset. Each part responds in character (as parallel subagents in Claude Code); a Self-led synthesis names agreements, polarizations, needs, and a recommendation — for you to decide. The meeting closes with a round of the table: each part says how it is feeling toward each of the others right now, on a five-point scale, and those readings go back into the profiles and thicken the swarm graph.

Quickstart A — the webapp (Inner Table)

The app/ directory is Inner Table, a mobile-first installable webapp version of this whole flow. Your parts live in your account, so you sign in to reach them — and find the same parts on any device you sign in on, while anyone else can sign in on the same device to reach only their own. Live at ifs-agents.vercel.app (open it on your phone and Add to Home Screen):

It follows one spine — add a part → gather → integrate → connect:

• Add — upload a whole parts/ folder at once, paste raw journaling, or create by hand with just a name.

• Gather — the question bank from docs/source/ ships in the app. Tap any coverage category to work through its real IFS questions one per screen, answering, skipping, or declining — no API key needed. The same bank feeds the AI prompts, and check-ins target whichever category the profile is thinnest on.

• Integrate — answers write straight into the profile's fields. When an AI session closes, its profile is merged, not overwritten, and shown for confirmation first: a thin closing reply can never erase what you already had.

• Connect — the swarm map is the editing surface. Every pair of parts is already drawn as a faint thread, because parts sharing a system always relate — you just haven't named it yet. Tap a thread to name it, tap a part to focus its threads, and open the map key to read what every thread style, colour and thickness is saying — and to filter by tone (supportive / in tension / not mapped yet). The key stays closed until asked for, then opens as a sheet on a phone or a side panel on a wider screen, so the map keeps the whole canvas. Edges are written to both profiles, mirrored, with no AI required.

• Round the table — a table meeting now ends the way the script does: each part is asked, by name, how it is feeling toward each of the others right now (hostile / wary / neutral / warm / close). Each reading is written to the part that gave it — directed, dated, and never mirrored, because what The Critic feels toward The Dreamer is nothing like what comes back — and the thread between them thickens on the map, a little more with every meeting they sit through. A pair nobody has named yet takes its colour from what they said they felt, so the map answers to a meeting instead of looking identical the morning after one. Parts may pass, and passing records nothing. Meetings you already held can still get their round, from the card on the Table tab — filed on that meeting's date, and never overwriting a more recent reading with an older one. The map key spells the whole scale out, alongside a live count of how many readings the system holds and how many pairs have answered in both directions.

• Parts library with coverage rings, type badges, and compile-readiness indicators; swarm map as an interactive touch-draggable graph.

Run it locally with any static server (python -m http.server --directory app, or npx serve app). There is no build step — app/ is served as static files, and pushing to main deploys it.

Run the safety tests with node test/run.js — no dependencies, no browser, no build. They cover data integrity rather than the UI: profile parsing and round trips, both merge paths, untrusted backups, the question bank, the store, and mic turn-taking.

Accounts and sync

Parts live in your account, not on the device. You sign in to reach them, and a part edited on your phone shows up on your desktop; sign out and the account's parts close, so anyone else can sign in on the same device and see only their own. The server side needs three environment variables on the Vercel project:

Variable	Where it comes from
UPSTASH_REDIS_REST_URL	your Upstash Redis database
UPSTASH_REDIS_REST_TOKEN	same
SESSION_SECRET	any long random string — openssl rand -base64 32

A new account opens on three example parts rather than an empty app — a critical manager, an ashamed exile, and a substance-using firefighter, already mapped in the shape those three usually take: both protectors standing in front of the same exile, polarized with each other. They are labelled as examples and sit deliberately short of the compile-readiness bar; rename them, rewrite them, or delete them. They are only ever seeded into an empty account, so signing up after using the app on a device never drops strangers among your own parts.

Accounts are created in the app itself — Create an account on the sign-in screen takes a username and a password of at least 8 characters. A name that already exists is refused rather than overwritten. Each account's parts are stored under its own key and are never readable by another account.

Anyone who can reach the URL can create an account, so treat the deployment as public. To make an account yourself instead — or to reset a forgotten password — run, from the project root:

node scripts/add-user.js <username>

That needs UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN in a local .env.local (copy them from the Upstash console — Vercel cannot pull back values marked Sensitive). The password is typed at a prompt rather than passed as an argument, so it never lands in shell history.

Each user's parts live under their own key and are never readable by another account. The Upstash token stays server-side in api/; the browser only ever holds a signed session token. This is a personal inner-work tool, not a clinical record system — the safety guide applies doubly once profiles are on a server.

Returning users

For whoever runs a deployment, the app counts how many people come back, and nothing else. A day counts when a signed-in account opens the app; the server keeps, per UTC day, a list of pseudonymous ids (an HMAC of the username, never the name), plus the day each account was made. Nothing about what anyone writes is recorded, there is no third-party analytics, and signed-out use is not counted at all. Day lists expire after 150 days.

The totals - who came back this week, who is new, how many came back within a week of their first day, weekly cohorts - appear in Settings → Usage, only for the accounts you name:

Variable	Where it comes from
STATS_USERS	optional - comma-separated usernames allowed to see Usage; to everyone else the section and /api/stats don't exist

A script can read the same JSON from /api/stats with CRON_SECRET as the bearer token. Accounts made before counting began count as returning, never as new.

Push notifications

A signed-in user can turn on notifications for one device at a time, from Settings → Notifications. This uses the Web Push standard, which is why it's tied to an account (the server needs somewhere to keep the subscription) and why, on iOS, it only works once the app is added to the home screen — Safari itself doesn't expose push at all; only the installed, standalone app does. Today this ships as infrastructure plus a Send test button; nothing sends notifications on its own yet.

It needs one more thing on top of the sync variables above — a VAPID key pair, which is how the server proves to browsers' push services that messages really come from this app:

npm install
node scripts/gen-vapid-keys.js

Set the three variables it prints as Vercel env vars:

Variable	Where it comes from
VAPID_PUBLIC_KEY	printed by scripts/gen-vapid-keys.js
VAPID_PRIVATE_KEY	same — keep this one secret
VAPID_SUBJECT	a mailto: address or the site's https:// URL

Free AI for everyone

So that nobody has to bring an API key, the app can run sessions on free AI models through a FreeLLMAPI gateway you host. FreeLLMAPI routes each request to whichever free-tier provider (Google AI Studio, Groq, Cerebras, OpenRouter's free models…) still has room. The gateway's key stays server-side in api/free-ai.js. Only signed-in accounts can use it, each up to a daily allowance. It is the only AI set-up the app shows: Settings has no AI section. Everyone is told once, before their first session on it, where their words go, and can choose copy-prompt mode instead. Without the gateway configured, sessions fall back to copy-prompt mode.

Variable	Where it comes from
FREELLMAPI_URL	your FreeLLMAPI gateway's HTTPS address
FREELLMAPI_KEY	its unified key (freellmapi-…) from the gateway's Keys page
FREELLMAPI_MODEL	optional — the models to try, in order, comma-separated; the gateway's own auto routing is always tried last. auto alone by default
FREE_AI_DAILY_LIMIT	optional — messages per account per day, 500 by default

A model too small for a request, or at its per-minute limit, hands the request on to the next one instead of failing the person. Most of the free capacity is in a few providers: a gateway with only Groq's free tier runs out after a request or two a minute, because each session sends the person's whole inner system. docs/free-ai.md says which providers to add.

FreeLLMAPI can't run on Vercel; it needs an always-on host. On Railway that is a few clicks in a browser. docs/free-ai.md walks through it step by step, along with your own server as the other option, choosing providers with your users' privacy in mind, and the limits of free models.

Quickstart B — Claude Code

Install as a plugin (or clone and add the skills/ to your project), then from any project directory:

/part-intake                      # meet a new part → parts/<name>.md
/part-checkin <name>              # short ongoing session; deepens the profile
/part-map                         # map relationships between two parts + swarm graph
/part-compile <name>              # profile → .claude/agents/part-<name>.md
/parts-meeting <path-to-dataset>  # all compiled parts react; Self synthesizes

A typical first arc: one intake (10–20 min), two or three check-ins across a couple of weeks, a second part's intake, one mapping session — then your first table meeting over something real (a budget CSV, a job offer, a draft essay).

Quickstart C — any LLM (no tooling)

The templates/ files are self-contained prompts:

Do this	Paste this into a chat
Meet a new part	templates/interview-intake.md — save the profile it produces
Continue with a part	templates/interview-checkin.md + the saved profile
Map two parts	templates/relationship-mapping.md + both profiles
Have a part react to material	templates/embody-part.md + profile + the material
Hold a table meeting	templates/table-meeting.md + 2+ profiles + the material

Repo layout

Path	What it is
app/	Inner Table — the installable mobile webapp (PWA, zero backend)
app/js/questions.js	The IFS question bank as data — drives both the in-app questionnaire and the AI prompts
templates/	The portable prompts — the heart of the system
schema/part-schema.md	Canonical profile schema, edge types, coverage model, compile-readiness bar
skills/	Claude Code slash-command wrappers around the templates
docs/ifs-primer.md	IFS concepts as used here
docs/safety.md	Boundaries, when to stop, privacy — read this
docs/free-ai.md	Hosting the FreeLLMAPI gateway behind the app's free AI
docs/source/	The source question set this system was built from
examples/	A fully fictional sample part ("The Critic") and its compiled agent
parts/, sessions/	Your data — created at use time, gitignored, never shipped

Privacy

Part profiles are intimate. parts/, sessions/, and compiled .claude/agents/part-*.md are gitignored here — keep them out of shared repos, and remember that anything pasted into a hosted LLM is subject to that provider's data policies. Details in docs/safety.md.

Credits & license

IFS concepts originate with Richard C. Schwartz and the IFS Institute; the table-meeting format is modeled on George A. Fraser's Dissociative Table Technique (1991, revised 2003). This repo is an independent self-exploration tool and is not affiliated with or endorsed by the IFS Institute.

MIT License — see LICENSE.