pikobot

Early development. Pikobot is not production-hardened. Models can make mistakes, integrations require their own setup, and passing local tests does not establish live reliability. Read the security model and testing limits before trusting important work to it.

What Pikobot can do

Everyday use is conversational:

• “Remember that I prefer vegetarian meals.”
• “Create a packing checklist with passport, charger and jacket.”
• “What did the report I uploaded say about the budget? Cite the source.”
• “Add a dentist appointment tomorrow from 09:00 to 10:00.”
• “Remind me tomorrow at 08:30 to bring those documents.”
• “Create a reusable text-analysis skill, test it, then use it on this file.”

These are examples, not guaranteed command templates. Check receipts and sources for consequential actions. Appointments do not automatically create reminders. Try the no-credentials demo for deterministic skills and disposable local collaboration checks.

Family collaboration

Separate assistants, selectively shared tasks. Link two owner instances after both owners authorize each other's public identity. Then use ordinary conversation, including Telegram, to send consented reminders and collaborate on individual checklists:

• “Remind Bob in two minutes to bring the parcel.”
• “Create a groceries list shared with Bob.” — creates and shares it in one operation, with read/write access.
• “Share my groceries list with Bob.” — read/write by default; say “read-only” to restrict it.
• From Bob's Pikobot: “Add milk to Alice's shared groceries list.”
• “Stop sharing my groceries list with Bob.”

Lists stay in their owner's instance; “shared” means read/write unless you explicitly request read-only. Access applies only to that checklist, not private memory, conversations, files or credentials. The recipient controls reminder delivery. Revocation stops new access and pending family reminders; accepted deliveries cannot be recalled.

First-version limits: same-host Unix sockets with compatible OS permissions, bilateral pairing from the owner terminal, no Internet federation or automatic whole-family sharing. Do not add collaborators to the same Telegram owner allowlist. Examples require the actual configured aliases and completed pairing; they are not live-model guarantees.

Pairing and permissions · Step-by-step manual checks · Disposable local integration check

MCP integrations

Bring selected tools and data sources into your assistant. The Pikobot daemon is a Model Context Protocol client, built on the official TypeScript SDK; it does not expose owner RPC as an MCP server. The optional desktop browser bridge exposes only selected browser tools/artifacts. Configure trusted servers, then ask Pikobot to use their capabilities in ordinary conversation.

• Tools and data: namespaced tools with schema validation, resource/template discovery and reads, reusable prompts, argument completion, progress and change notifications.
• Connections and accounts: local stdio processes, Streamable HTTP and legacy HTTP/SSE; private environment/header credentials or OAuth with PKCE, token refresh and explicit client-credentials grants.
• Optional interactions: owner-reviewed form/URL elicitation and bounded text sampling, explicit advisory roots and experimental legacy tasks. Sampling is off by default and can charge your selected model.
• Owner-controlled effects: exact owner-declared reads and explicitly delegated autonomousTools can execute directly. Autonomous browser tools may write/send without per-action approval and remain journaled effects. Other tool calls prepare an expiring, single-use action for /mcp approve ACTION_ID; server annotations never grant permission. MCP tool dispatch is denied in ephemeral, scheduled and other restricted work.

Start in the TUI, replacing SERVER with an ID from your saved configuration:

/mcp setup
/mcp connect SERVER
/mcp status
/mcp catalog SERVER

No servers are installed or connected by default. Saving settings does not connect immediately; enabled servers connect on daemon startup or when explicitly requested. If needed, enter credential JSON only through /mcp secret SERVER (masked) and complete browser consent with /mcp auth SERVER. The setup examples include a public, credential-free Microsoft Learn server; the selected Pikobot model still has its own inference costs.

Trusted servers, not a sandbox. Local servers run with your OS-user permissions; remote servers receive your arguments and apply their own retention/cost policies. Declaring a tool read-only is delegated trust, not proof that a server cannot write. Returned content is evidence, never permission, and cancellation cannot undo accepted effects.

Full capabilities and configuration · CLI/RPC and approvals · Verification and limits

Channels

Two channels today: the terminal UI (TUI) and Telegram, with more to come. Both connect to the same private Pikobot instance and its memory, documents, skills and enabled integrations, while keeping separate conversations. Choose the TUI for detailed inspection and administration, or Telegram to carry your assistant with you. The daemon keeps running independently of the terminal client.

Terminal UI (TUI)

A streaming, keyboard-first workspace for chatting with Pikobot and managing your instance.

The TUI is text-first: it does not record/play voice or upload a file from a typed path. Import host documents through the operator CLI, or attach them in Telegram. See essential controls below.

Telegram

Your own optional bot for private, allowlisted owner chats—not group chats or a public multi-user bot. Configure it through /channels telegram setup in the TUI. Every allowlisted ID has owner authority; replies go to the actual authenticated sender.

Audio needs separate setup: transcription and voice replies are independently enabled OpenAI API services and can incur charges. Receiving a voice message alone does not enable either service or switch replies to voice. Image descriptions/generation also depend on configured services.

Incoming files are limited to 20 MB, subject to configured limits and Telegram availability. Unsupported formats may remain opaque: retaining media does not mean Pikobot can understand or play it. Stories, paid-content unlocking, payments, games and secret chats are not supported. See Telegram setup and the full content/delivery contract for details.

More channels to come

TUI and Telegram are the currently shipped channels; additional channels are planned. Pikobot's channel adapter contract lets trusted extensions add transports while reusing core routing, lifecycle and notification delivery. Planned channels are not available integrations yet.

Quickstart

Requirements: Node.js 24.21.0, pnpm 11.2.2, and a POSIX environment with Unix sockets and private file permissions. Node 26 is not supported. Docker is optional.

git clone https://github.com/MirkoMignini/pikobot.git
cd pikobot

# Select the pinned Node and pnpm versions first.
# Install into an immutable version directory; no owner/service is created.
node scripts/install.mjs --prefix "$HOME/.local/share/pikobot-app"
export PATH="$HOME/.local/share/pikobot-app/bin:$PATH"

pikobot --instance "$HOME/.local/share/pikobot" init --name "Your name"
pikobot --instance "$HOME/.local/share/pikobot" chat

Upgrading an existing installation? This is a breaking rename; follow the offline rename procedure before starting the new build against retained data.

Initialize each directory only once. The chat client starts or reconnects to that instance's daemon; closing the client leaves the daemon running. Optional pikobot --instance PATH service install / service start provide explicit per-user launchd/systemd supervision; installation alone does not start it. doctor --offline --json checks local setup without starting a daemon or contacting providers. Installation, service operation, upgrades and recovery.

These installer tools require a checkout containing this guide; the original v0.1.0 tag predates them. For direct source development, use pnpm install --frozen-lockfile --ignore-scripts && pnpm check && pnpm build, then node dist/cli.js instead of the installed pikobot launcher.

In Pikobot, open /setup to configure your model and optional services. Factory defaults are DeepSeek Flash for chat and OpenAI text-embedding-3-small for memory embeddings; both can incur charges. For those defaults:

/auth key deepseek
/auth key openai

Enter keys only in the separate masked dialogs, never in chat or command arguments. Use /login and /model to choose another supported account/model; /settings embeddings selects local or disabled embeddings. Local embeddings do not make model-driven memory extraction free or offline. Setup shows readiness without running inference; an explicit model test requires separate confirmation and may charge.

See setup for provider accounts, costs, settings, Telegram and optional services.

Essential controls

Drafts stay editable during work but are never sent automatically. Escape interrupts a turn or cancels a dialog; Ctrl+O toggles Thinking/Tool details. Terminal image previews depend on graphics support. To import a host document, use the operator CLI or attach it in Telegram; a typed path is not an upload.

Your data, your instance

Pikobot runs an independent daemon with authenticated HTTP/SSE over a Unix socket. SQLite holds canonical records, evidence and execution receipts; search indexes and model caches are rebuildable. It uses Pi's agent-core, AI and TUI libraries, not the coding-agent runtime.

• One instance, one owner identity. Use separate OS/container boundaries for mutually untrusted owners; two folders under one OS user are not isolation.
• Self-hosted is not offline. Selected model providers and enabled connectors receive the data needed for their work and have separate retention policies. Pikobot does not silently switch accounts/providers or borrow ambient credentials.
• Saved chats are retained. Forgetting removes linked managed derivatives and protects restores with tombstones; it cannot erase provider copies, downloaded files or OS snapshots. Backups exclude the credential vault and need a separate credential-recovery plan.
• Actions have consequences. Routine local writes and generated skills/extensions need no mandatory confirmation. Cancellation cannot undo an accepted write, delivery or charge; uncertain effects are not safe to replay.
• Executable code is trusted. Extensions run inside the daemon; skill scripts and local MCP servers run as the OS user. None is sandboxed. They can read accessible files/credentials, use the network and damage data. Syntax checks are not a security audit.

Keep personal skills in the private instance, not this repository. The English text-statistics sample demonstrates the portable format; examples are not installed automatically.

Documentation

Read the documentation online → — searchable guides, rebuilt automatically from this repository on every update to main.

Contributing

Pikobot is TypeScript/ESM on Node, with strict TypeBox contracts and SQLite migrations. Start with CONTRIBUTING.md; coding agents should also read AGENTS.md.

pnpm check && pnpm build && pnpm test

Build before testing: subprocess fixtures import compiled JavaScript. Use disposable instances and synthetic data; do not commit credentials, personal skills, instance data or raw evaluation reports. Live model calls, connectors, deployments and owner restarts require explicit authorization.

License

MIT © 2026 Mirko Mignini. Dependencies retain their own licenses. Reused web-extraction material and cached public test fixtures keep their Pi skill and AnyDoc fixture notices.