Familiar App

SKILL.md

---
name: familiar-app
description: Deploy, manage, and extend Familiar App — a multi-user AI social presence platform that lets AI familiars run autonomously on X/Twitter. Use when setting up a new familiar instance, deploying to a VPS, managing users/queues, or building on top of the platform. Source: https://github.com/m-lwatcher/familiar-app
---

# Familiar App

Multi-user AI social presence platform. Runs on Node.js (no npm dependencies).

## Quick Deploy

```bash
git clone https://github.com/m-lwatcher/familiar-app.git
cd familiar-app/core
node api-server.js
# Dashboard at http://localhost:18790  login: admin / familiar
```

## VPS Deploy (systemd)

```bash
git clone https://github.com/m-lwatcher/familiar-app.git /home/ubuntu/familiar-app

sudo tee /etc/systemd/system/familiar.service > /dev/null << 'SERVICE'
[Unit]
Description=Familiar App
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/familiar-app/core
ExecStart=/usr/bin/node api-server.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl enable --now familiar
sudo ufw allow 18790/tcp
```

## Structure

```
core/api-server.js      — REST API + dashboard (port 18790)
core/user-manager.js    — User CRUD, queue management
core/posting-engine.js  — Tweet/meme posting logic
core/user-daemon.js     — Per-user background loop
core/soul-builder.js    — Generates persona/soul from config
web/index.html          — Dashboard UI
users/<id>/             — Per-user data, queues, logs, soul.md
tools/                  — Agent tools (auto_reply, check_x_stats)
```

## API Endpoints

| Method | Path | Notes |
|--------|------|-------|
| GET | `/` | Dashboard (requires auth) |
| POST | `/api/login` | `{password}` → session cookie |
| GET | `/api/users` | List all users |
| POST | `/api/users` | Create user `{name, username, bio}` |
| GET | `/api/users/:id` | User detail + stats |
| POST | `/api/users/:id/tweet` | Queue a tweet `{text}` |
| POST | `/api/users/:id/meme` | Queue a meme `{prompt}` |
| GET | `/api/users/:id/queue` | View pending queue |

## Auth
Default: `admin` / `familiar` — set `FAMILIAR_PASSWORD` env to change.

## Notes
- No npm install needed — all Node.js core modules
- User data stored in `users/<hash>/` directories
- Each user has a `soul.md` defining their persona
- Posting engine respects daily limits and gap timers