PinkyBot

PinkyBot

A personal AI companion framework powered by Claude Code.

PinkyBot turns Claude Code into a persistent AI agent with identity, long-term memory, messaging, scheduling, and a web dashboard — your AI sidekick that runs 24/7, connects to Telegram/Slack/Discord, and gets smarter over time.

What it does

• Persistent agents — Named AI agents with souls, memory, and roles. They wake up on a schedule, respond to messages, and remember everything across sessions.
• Long-term memory — Vector + keyword hybrid search. Agents reflect on experiences and recall them semantically across sessions.
• Multi-platform messaging — Telegram, Discord, Slack. Send and receive messages, photos, documents, voice notes, reactions.
• Event-driven triggers — Agents wake up automatically on webhooks, URL changes, or file changes.
• Project & task management — Milestones, sprints, burndown. Agents decompose projects and track progress.
• Dreaming — Agents autonomously consolidate memories and process the day while you sleep.
• Skills — Modular capability plugins (SKILL.md-based) agents can install to learn new things.
• Web dashboard — Chat, fleet management, memory browser, activity feed, presentations, project hub.
• Works with your Claude account — Uses Claude Code under the hood with your existing Max/Pro subscription. No separate API bills.

Quick Start

curl -fsSL https://pinkybot.ai/install.sh | bash

Installs the pinky command, Claude Code (if not present), and all dependencies. Then:

pinky --mode api --port 8888

Open the dashboard at http://localhost:8888.

Manual Install

Prerequisites

• Python 3.11+
• Claude Code — install with:

  curl -fsSL https://claude.ai/install.sh | bash
  

• A Claude Max or Pro subscription (or an API key)

Install

git clone https://github.com/bradbrok/PinkyBot.git
cd PinkyBot

python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[all,dev]"

Start

python -m pinky_daemon --mode api --port 8888 --host 0.0.0.0

Open the dashboard at http://localhost:8888.

Deployment checks

Run python -B -m pinky_daemon --mode check-startup --db-path PATH to check imports and the main data-root layout without opening stores or stopping a running daemon; a completed check prints JSON and exits 0 when clean, 1 for unscoped layout findings, or 3 when every finding belongs to an agent scope; an incomplete check exits 2 with its reason on stderr. Updates and restarts inspect that layout before changing the working tree or scheduling a restart, including forced updates; request the optional dry-run inspection with check_for_updates(preflight=True) or POST /admin/update?dry_run=true&preflight=true. After checkout and dependency installation, an update checks the target release in a child process before building the frontend; failure triggers an undo to the previous commit and restores dependencies if installation was attempted, reports whether the undo succeeded, and declines the restart. The command itself opens no store and writes no file; Python may write bytecode caches next to source files unless started with -B. The update's Python children (the installer version check, dependency install and startup check) disable bytecode writes; the startup check ends its process group before continuing, and a process that leaves that group on its own is outside this check's scope. Targets predating the check report that it was skipped. These checks cover imports and the main root's layout, not every possible startup failure; tenant roots are not covered, and their existing startup checks remain in place. Later releases may append stage names to checked, add keys to the report and add finding kinds; they do not remove, rename or reorder import and layout, every finding keeps kind and path, and the meaning of the exit status does not change.

An update that will restart arms a start guard in <data-root>/deploy/: three unsuccessful target starts cause the next start to restore the previous commit and dependencies, then exit 75 for the service manager to retry. An armed start has a 600-second deadline; listener readiness cancels it, and 120 seconds of serving confirms recovery. Five failed starts within 600 seconds also trigger an incident alert, with bounded retry delays and reminders no more often than every six hours. Only the update endpoint arms rollback; a scheduled updater that checks out a release and restarts outside that endpoint gets incident alerts without automatic rollback. Rollback does not rebuild the frontend, so the served frontend may remain the newer build until the next update; update status shows this limitation. An update while the data root is missing is refused. A predecessor without the guard receives one pre-exit notice saying it is starting and will not confirm readiness; a guard-aware predecessor reports recovery after readiness. Daemon-free alerts use a 0600 route file inside a 0700 directory, accept only the same user, and make one HTTPS attempt with no retry after a timeout. Set PINKY_DEPLOY_GUARD=0 or create deploy/guard.off to disable start-time recovery; readiness maintenance still runs. Failures of the interpreter or entry module before the guard can run, and releases that start but serve incorrectly, are outside this guard's scope. The startup inspection also checks guard_selftest.

Outside-root directory or database findings under <data-root>/agents/<name> hold that registered agent in memory while the daemon serves the others. The main agent starts with a warning and the findings in its wake prompt; registered-store and unscoped failures remain fatal. Updates and restarts decline scoped findings unless accept_findings=true is explicit (also available on their MCP tools). Agent detail, health and update status show the findings. After repair, use POST /agents/{name}/storage/recheck; the owner can temporarily bypass one hold with POST /admin/agents/{name}/storage/start-anyway. Plain configuration edits and explicit administrative teardown remain available; container runtime actions require clearing or bypassing the hold.

Create your first agent

Via the web UI at http://localhost:8888/#/agents, or via API:

# Create an agent
curl -X POST localhost:8888/agents \
  -H 'Content-Type: application/json' \
  -d '{"name": "myagent", "model": "claude-sonnet-4-6", "display_name": "My Agent"}'

# Wake it up
curl -X POST "localhost:8888/agents/myagent/wake?prompt=Hello"

# Chat with it
curl -X POST localhost:8888/agents/myagent/chat \
  -H 'Content-Type: application/json' \
  -d '{"content": "What can you do?"}'

Connect to Telegram (optional)

1. Create a bot via @BotFather
2. Go to Settings at http://localhost:8888/#/settings
3. Enter your bot token under Outreach Platforms
4. Assign the bot to your agent

Architecture

PinkyBot Daemon (FastAPI :8888)
├── Agent Registry        — named agents, soul, config, permissions
├── Streaming Sessions    — long-lived Claude Agent SDK sessions per agent
├── Message Broker        — routes inbound messages to the right agent
├── Scheduler             — heartbeats, URL watchers, wake schedules
├── Trigger Store         — webhook, URL, and file event triggers
├── Activity Log          — auditable log of all agent actions
└── MCP Servers (per agent session)
    ├── pinky-memory      — long-term memory (vector + BM25 + salience)
    ├── pinky-self        — agent self-management (tasks, schedules, triggers, health)
    ├── pinky-messaging   — outbound messaging (send, thread, react, broadcast)
    └── pinky-calendar    — Google Calendar / CalDAV (optional)

Frontend (Svelte 5 SPA)
├── Dashboard             — stats, burndown, activity feed
├── Chat                  — per-agent conversation with tool use + thinking display
├── Fleet                 — multi-agent overview, status, comms
├── Agents                — agent config, MCP servers, skills, triggers
├── Memory                — browse and search long-term memory
├── Projects              — project hub, milestones, sprints
└── Presentations         — shareable AI-generated slide decks

Core concepts

Agents

An agent is a named entity with:

• Soul — personality and values in CLAUDE.md (you edit this)
• Model — which Claude model to use (claude-sonnet-4-6, claude-opus-4-6, etc.)
• Tools — what MCP tools it has access to
• Users — who can talk to it and how
• Skills — installed capability plugins
• Triggers — what events wake it up

Memory

All persistent memory goes through the pinky-memory MCP server:

• reflect(content) — store a cross-session learning or fact
• recall(query) — semantic search across all memories
• introspect() — list your stored memories

Memory persists across context restarts, daemon restarts, and sessions. Agents consolidate memories autonomously during dream runs.

Triggers

Agents can be woken by external events:

• Webhook — POST to a unique URL; agent wakes with the payload
• URL watcher — polls a URL on a schedule, wakes on change
• File watcher — watches a file path for changes

Agents manage their own triggers via the pinky-self MCP.

Skills

Skills are SKILL.md files that add capabilities to agents. Skills can contribute:

• Instructions and domain knowledge
• Additional MCP servers
• Persistent directives

Project structure

PinkyBot/
├── src/
│   ├── pinky_daemon/       # Core: FastAPI, broker, scheduler, sessions, triggers
│   ├── pinky_memory/       # MCP: long-term memory with vector + keyword search
│   ├── pinky_self/         # MCP: schedules, tasks, triggers, health, context
│   ├── pinky_messaging/    # MCP: outbound messaging (send, thread, react, broadcast)
│   ├── pinky_outreach/     # MCP: platform adapters (Telegram, Discord, Slack)
│   ├── pinky_calendar/     # MCP: Google Calendar / CalDAV
│   ├── pinky_hub/          # Hub: cross-instance registry, presentation sync
│   └── pinky_cli/          # CLI: init, serve, run
├── frontend-svelte/        # Svelte 5 SPA source
├── frontend-dist/          # Generated, gitignored frontend build (served by daemon)
├── docs/                   # Architecture docs and specs (HTTP access logging: docs/access-log.md)
├── tests/                  # pytest suite
└── data/                   # Runtime data (SQLite, agent files) — gitignored

Development

pip install -e ".[all,dev]"

# Run tests
pytest

# Frontend dev server
cd frontend-svelte && npm install && npm run dev  # :5173

# Build frontend
cd frontend-svelte && npm run build

License

MIT

Built by

Brad Brockman

Dream receipts migration

The durable dream-receipts migration is one-way. Rolling back below PinkyBot 26.08.020 after this migration is unsupported: pre-gate builds may start with stale watermark semantics beside v1 receipt rows. Builds at or above 26.08.020 fail closed if they encounter a future dream schema version.

HTTP request receipts, authentication gates, and retention: Access log.