Protos

A blueprint for personal AI assistants that build themselves.

Why

OpenClaw demonstrates that local AI assistants are incredibly useful. But it is also a large and complex system.

Protos explores the opposite extreme. It lets you build a powerful assistant that is:

• simple enough to understand
• built from readable files
• local-first
• entirely yours

Protos is an architecture specification — a set of documents precise enough that an AI coding agent can read them and generate a working personal assistant from scratch.

How it works

You don't install Protos. You point an AI coding agent at it and say:

build <channels>

where <channels> are the messaging platforms you want (Telegram, WhatsApp, Discord, Slack, iMessage, Terminal). The agent reads the spec and generates the assistant.

More specifically:

1. Clone the repo — git clone https://github.com/ninjudd/protos.git. No fork needed; your personal state lives in nested repos (agent/, config/, memory/) created during build, which are gitignored here.
2. Point your AI coding agent at it (Claude Code, Codex, etc.)
3. Tell the agent: build telegram (or whichever channel recipe under spec/channels/ you prefer)
   • The coding agent reads spec/ and generates the implementation in agent/. Approve its edits.
4. Fill in your API keys in config/.env
5. Start it — agent/protos start
6. Talk to it — DM the bot on your chosen channel, or run agent/protos chat for a local terminal chat over a Unix socket (always available, no messaging platform setup required). On first run, the agent asks for a name and personality.

The repository contains no running code. It contains the spec. The coding agent reads the spec and generates the implementation.

Updating

When the spec evolves, sync your implementation the same way you built it. Point your coding agent at the workspace and say:

update

The agent pulls the latest spec/, diffs it against your agent/ tree, shows what would change, and applies the edits once you approve. Restart with agent/protos restart to pick them up.

Only agent/ is regenerated. Your config/, memory/, and runtime/ are left alone.

Testing (optional)

To generate or refresh tests that verify your agent/ matches the spec, point your coding agent at the workspace and say:

test

The agent reads spec/ for the invariants and contracts the implementation must satisfy (tool return shapes, the call/result pairing rule, the skill loader's flat-scan + dual-form + merge behavior, render-filter rules, and so on), writes tests in agent/test/ that exercise them, and runs the suite. Tests use vitest by default.

test is always a manual step — build and update don't run it for you.

Reviewing & debugging (optional)

Two more workflow commands you can run any time:

review
debug <free-form description>

• review audits agent/ against spec/ and produces a markdown report of any drift — file references, what the spec requires, what the code does. Read-only; it never writes or modifies anything. Useful when you've hand-edited agent/ and want to know whether your changes diverged from the spec, or when something feels off and you want a structural check before reaching for debug.

• debug takes a free-form symptom (debug Telegram keeps crashing) and diagnoses it from your runtime/ logs, threads, and code. It asks clarifying questions if the description isn't enough, and may offer to write a test or run review as part of the investigation. Output is always a diagnosis plus a suggested change — never an auto-applied fix.

Both write a log under runtime/reviews/ or runtime/debug/ so you can re-read past sessions without re-running.

What you get

A personal AI assistant that:

• Runs as a single Node.js process on your machine
• Connects to your messaging apps (Telegram, WhatsApp, Discord, Slack, etc.)
• Uses any LLM you choose (model-agnostic via the Vercel AI SDK)
• Has a personality you define in config/SOUL.md
• Remembers things in markdown files you can read and edit
• Runs scheduled tasks on your behalf
• Can modify its own source code and restart to apply changes
• Is small enough to understand completely

Workspace layout

The workspace is split into five sibling domains. Only spec/ is tracked by this repo. agent/ is a nested Git repo (required — the self-edit auto-revert depends on git in that directory). config/ and memory/ are strongly recommended to be Git repos too; runtime/ is never versioned.

# Tracked by this repo
README.md, CLAUDE.md, AGENTS.md   # workspace entry-point docs
spec/                             # the blueprint
  architecture.md                 # system design
  agent.md                        # base prompt for the running assistant
  build.md                        # build instructions for coding agents
  channels/                       # channel recipes (markdown)
  tools/                          # tool recipes (markdown)
  skills/                         # bundled skills (markdown, agentskills.io format)
  cron/                           # default scheduled jobs (markdown)

# Gitignored (own repo)
agent/                            # generated implementation — TypeScript code
config/                           # behavior — SOUL.md, instance overrides, .env
memory/                           # durable state — facts, preferences, journal
runtime/                          # ephemeral state — threads, logs, pid files

The repo is the spec — the design. The build reads spec/ and generates agent/. Each user has their own agent/, config/, and memory/ as their own Git repos.

See spec/architecture.md for the full system design.

Principles

• Your machine, your data. Everything runs locally. Nothing phones home.
• Files over databases. Everything is plain files: identity, memory, skills, cron, and message history. No database, no driver, no schema. cat is your inspector.
• Specify the what, not the how. The spec defines components and responsibilities. Implementation details are left to the coding agent.
• No speculative features. Only what's needed for a working assistant.
• Five domains. spec/ (blueprint), agent/ (engine), config/ (behavior), memory/ (knowledge), and runtime/ (ephemeral state) are separate concerns with separate lifecycles.