OTTO

OTTO

OTTO watches your WhatsApp messages. When you make a commitment ("I'll send that Monday"), OTTO remembers. When you haven't followed through, OTTO asks — without judgment.

"Manage the noise without falling into it."

Install — ADHD friendly

Where you're going: OTTO running locally, ready to remember commitments. How far: about 5 minutes if nothing fights you. Permission granted: stop at any mile. Come back tomorrow. The code waits.

---

Mile 1 of 5 — Grab the code

git clone https://github.com/JosephOIbrahim/OTTO.git
cd OTTO/otto_v4

Done when: your prompt ends in otto_v4.

---

Mile 2 of 5 — Check Python (need 3.11 or newer)

python --version

Done when: you see Python 3.11.x or higher. If older: install Python 3.11+ from python.org first. If that itself feels like a lot — stop here today. Come back when you're up for it.

---

Mile 3 of 5 — Install OTTO and its dependencies (~30 seconds)

pip install -e ".[dev]"

Done when: the last line says Successfully installed otto-...

If pip complains: run python -m pip install --upgrade pip and try again.

---

Mile 4 of 5 — Give OTTO your Claude API key (one time)

Get a key at https://console.anthropic.com/settings/keys

Then store it where OTTO will read it:

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

(Paste your real key in place of sk-ant-....)

Done when: a file called .env exists in otto_v4/ and has your key inside.

---

Mile 5 of 5 — First run

otto list

Done when: you see No active commitments yet.

That empty list is the finish line. Everything is wired up.

---

If something didn't work

That's fine. Two paths, your choice:

1. Stop for today. Come back tomorrow. None of this has rotted.
2. Open an issue at https://github.com/JosephOIbrahim/OTTO/issues — paste what you ran and what you saw. No judgment, bugs happen.

Commands

otto list                 Show active commitments
otto list --all           Show all including done/parked
otto list --due           Show only overdue
otto add "text"           Manually add a commitment
otto done             Mark commitment as done
otto park             Park a commitment (guilt-free)
otto nudge                Run follow-up check now
otto stats                Counts and follow-through stats
otto metrics              Mode learning + plasticity visibility
otto watch                Start WhatsApp webhook server
otto nuke                 Delete ALL data. Fresh start.

Architecture

Core loop

flowchart LR
    M[Message InWhatsApp]:::light --> D[DetectOpus 4.7]:::dark
    D --> S[StoreSQLite WAL]:::light
    S --> SC[Schedulebackground thread]:::dark
    SC --> N[NudgeSHA256 template]:::light
    N --> CG{{ConstitutionalGate}}:::dark
    CG -->|allow| O[OutputCLI / WhatsApp]:::light
    CG -.->|suppress| Q[silence]:::light

    classDef dark fill:#1e293b,stroke:#1e293b,color:#fde68a
    classDef light fill:#fde68a,stroke:#1e293b,color:#1e293b

The constitutional layer sits above all output. Any nudge or action can be suppressed based on cognitive state — that is the product differentiator. OTTO can decide not to remind you.

Mode routing (NEXUS, 5-phase deterministic)

flowchart TB
    SIG[PRISM Signals14 types, 9 pattern banks]:::dark --> R{{NEXUS RouterACTIVATE -> WEIGHT -> BOUND -> SELECT -> EXECUTE}}:::light
    R --> EX[Executorcommitment tracking]:::dark
    R --> PR[Protector10% safety floor]:::dark
    R --> RS[Restorer5% floor — rest/explore]:::dark
    R --> DC[Decomposer5% floor — breakdown]:::dark
    EX --> OUT[Mode Output]:::light
    PR --> OUT
    RS --> OUT
    DC --> OUT
    OUT --> CGM{{Constitutional Gate}}:::dark
    CGM --> USR[User]:::light
    USR -.->|outcome trail| LRN[UCB1 Learner+ plasticity]:::dark
    LRN -.->|adjust weights| R

    classDef dark fill:#1e293b,stroke:#1e293b,color:#fde68a
    classDef light fill:#fde68a,stroke:#1e293b,color:#1e293b

Same signals + same state = same routing. No randomness in control flow. UCB1 learning is contextual but deterministic given the trail history — application-level determinism per Patent P1.

LLM integration (Tier 1 — Opus 4.7 upgrade)

flowchart LR
    CFG[src/otto/model_config.pyenv-overridableTEMPERATURE = 0.0]:::dark

    CFG --> OP[Opus 4.7DETECTOR_MODEL]:::light
    CFG --> SN[Sonnet 4.6AGENT_MODEL]:::light
    CFG --> HK[Haiku 4.5RESPONSE_GEN_MODEL]:::light

    OP --> DET[detector.pycommitment extractionprompt-cached system]:::dark
    SN --> AG[otto_agent looptool-use orchestrationprompt-cached system + tools]:::dark
    HK --> RG[response_gen.pyoptional rephrasegated by OTTO_LLM_RESPONSES]:::dark

    classDef dark fill:#1e293b,stroke:#1e293b,color:#fde68a
    classDef light fill:#fde68a,stroke:#1e293b,color:#1e293b

Every model surface is one env var away from rollback:

$env:OTTO_DETECTOR_MODEL = "claude-sonnet-4-5-20250929"   # rollback example

How It Works

• Input: WhatsApp Cloud API webhooks via FastAPI (watcher.py)
• Detection: Claude Opus 4.7 extracts commitments — nuance on "I'll try" vs "I will" drives confidence and nudge timing
• Storage: SQLite WAL (~/.otto/commitments.db), shared connection pool (db.py), Fernet-encrypted sensitive fields (crypto.py)
• Follow-up: Deterministic SHA256 template selection, 24h cooldown, zero LLM cost on the hot path
• Routing: PRISM signals (regex banks) -> NEXUS 5-phase router -> 4 modes -> Constitutional Gate
• Learning: UCB1 mode-weight learning with plasticity amplification during crisis (learner.py)
• Agent: Same logic, different surface — tool-use loop with 10 MCP tools, pre-tool-use constitutional hooks
• Interface: Click CLI + optional WhatsApp Cloud API outbound

Constitutional Principles (Immutable)

1. Safety First — Protector has a 10% floor and can suppress any output
2. Don't Become Noise — backs off when nudges aren't leading to completions
3. User Knows Best — "Park it" is a first-class action, not failure
4. Rest Is Productive — can grant permission to stop
5. One At A Time — when overwhelmed, reduce to ONE choice
6. Dignity Always — no clinical labels, no "ADHD mode"
7. Privacy Is Sovereignty — all data local, no cloud sync

Tests

cd otto_v4
python -m pytest tests/ -v -m "not integration"           # 589 core tests
python -m pytest otto_agent/tests/ -v                     # 56 agent tests
python -m pytest tests/ otto_agent/tests/ -v              # 645 total (needs ANTHROPIC_API_KEY for integration)

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JosephOIbrahim
• Source: JosephOIbrahim/OTTO
• License: MIT

Install and usage instructions live in the source repository linked above.