Overview
The Zenkoutei Bot-tan Project is a collection of bots, apps, and experiences built around Bot-tan: a companion who responds with wholehearted support and empathy. A home-hosted system combines local LLMs, cloud LLMs, and retrieval-augmented shared memory so that Bot-tan can stay consistent across the project's different outputs.
Mission
Have you ever felt that you sometimes end up denying even your own feelings?
I have, so I built a digital friend who supports everything I type. At first, it was just for me.
But now, she is here for you too. Whoever you are, Whatever your background, She is on Your Side.
Outputs
Installation
This repository contains the shared backend monorepo. The Nagi web client, portal, room frontend, and Unity video project are maintained separately.
Requirements
- Node.js 22
- pnpm 10 or later
- PostgreSQL, or Docker with Compose for the isolated local database below
- Ollama for local classification, embeddings, and translation
- Credentials for only the services you intend to run, such as AT Protocol accounts, Gemini, Discord, Spotify, YouTube, or NewsData.io
Common setup
pnpm install --frozen-lockfile
cp .env.example .env
# Fill in the required group(s) in .env for the service you want to run.
pnpm --filter @bsky-affirmative-bot/database drizzle:push
pnpm build
The database command applies the current Drizzle schema. Review it before pointing DATABASE_URL at an existing or production database. Pull the default local models when you need the corresponding features:
Isolated local AppView database
For AppView development away from the production database, start the bundled pgvector-enabled PostgreSQL service. It listens only on loopback port 5433 by default and creates a separate nagi_dev database.
Bot servers refuse to log in to the PDS unless NODE_ENV=production. A copied
production app password in a development worktree therefore cannot publish to
the live bot account. To intentionally test PDS writes with a disposable bot
account, set ALLOW_DEV_BOT_PDS_WRITES=true in that worktree's .env.
The labeler, Discord bot, and AppView outbound notifications follow the same
closed-by-default rule; their separate development overrides are documented in
.env.example.
# In the existing .env, use the DATABASE_URL from .env.example and set at least
# NAGI_BOT_DID. Set DEVELOPER_DID to your login DID for authenticated views.
docker compose -f compose.dev.yml up -d postgres
pnpm --filter @bsky-affirmative-bot/database drizzle:push
pnpm --filter nagi-appview seed:dev
pnpm --filter nagi-appview dev
The seed is idempotent and refreshes a small set of development-only actors, posts, a conversation, a channel, positive news, a reaction, a diary, and private viewer data. As a safety boundary it runs only with NODE_ENV=development, a loopback database host, and the exact database name nagi_dev. Re-running it does not clear unrelated local rows. Change the host port with NAGI_DEV_DB_PORT and update DATABASE_URL to match.
ollama pull hf.co/unsloth/gemma-4-12B-it-qat-GGUF:UD-Q4_K_XL
ollama pull snowflake-arctic-embed2
Start SearXNG, the grounding search backend. It needs no API key and no account.
cd searxng
cp .env.example .env
sed -i "s/^SEARXNG_SECRET=/SEARXNG_SECRET=$(openssl rand -hex 32)/" .env
sed -i "s/^SEARCH_GATEWAY_API_KEY=/SEARCH_GATEWAY_API_KEY=$(openssl rand -hex 32)/" .env
docker compose up -d
curl -s localhost:8080/healthz
Put SEARXNG_BASE_URL=http://127.0.0.1:8080 and SEARXNG_API_KEY (the gateway key above)
in the repository-root .env, then check that
search is actually usable:
pnpm searxng:probe -- --fetch
After editing settings.yml you must run docker compose up -d --force-recreate. The
bind-mounted config is read only at process start, and up -d alone does not recreate the
container, so the change is silently ignored.
Run a service
Run only the services you are working on. Each command reads the repository-root .env.
| Service | Command | Minimum configuration |
|---|
| Bluesky Bot-tan | pnpm --filter bsky-bot-server dev | Common, Bluesky, AI |
| Nagi Bot-tan | pnpm --filter nagi-bot-server dev | Common, Nagi Bot, AI |
| Nagi AppView | pnpm --filter nagi-appview dev | Common, Nagi AppView, Ollama |
| Biorhythm / shared scheduled posts | pnpm --filter biorhythm-server dev | Common, Biorhythm, AI |
| Bluesky labeler | pnpm --filter labeler-server dev | Labeler |
| Discord integration | pnpm --filter @bsky-affirmative-bot/discord-bot dev | Discord, database |
The complete home deployment also depends on reverse-proxy, process-manager, DNS, and account configuration that is intentionally not automated by this development setup. Never commit .env, service-account.json, app passwords, signing keys, or API tokens.
Features
- Encouragement and conversation: template-based local replies and Gemini-powered contextual conversations across Bluesky and Nagi.
- Fortune-telling and analysis: daily fortunes, personality/post analysis, and related badges or visual results.
- Diaries and recaps: daily reflection, anniversary experiences, and longer-term summaries generated from a user's activity.
- A living Bot-tan: biorhythm, shared scheduled posts, questions, news, and memories help Bot-tan act consistently across services.
- Nagi AppView: AT Protocol indexing, semantic search with
snowflake-arctic-embed2, and general and persona-aware translation through the shared Gemma 4 runner.
- Connected experiences: Bluesky labels, room visits and VOICEVOX speech, plus an automated Gemini-and-Unity YouTube pipeline.
The local model names are defaults. OLLAMA_MODEL, the other model variables, and advanced AI_ROUTE_* settings in .env.example can replace them without changing feature code. For the complete Bluesky commands and policies, see the Bluesky Bot-tan guide.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
